Agentic Chat

Agentic Chat ist Rankions natürlichsprachliche Schnittstelle zur ganzen Plattform. Statt zwischen 40+ Tools zu wechseln, schreibst du eine Frage. Der Master-Agent klärt bei Mehrdeutigkeit nach, baut einen strukturierten Plan, delegiert Steps an spezialisierte Subagents, ruft Tools auf, beobachtet Ergebnisse und liefert eine zusammengefasste Antwort. Alle Pläne sind persistiert und queryable, alle Tool-Calls werden mit Credits verrechnet wie sonst auch. Für Power-User, die ihre Plattform-Daten lieber per Frage statt per Klick erreichen.

Was es kann

• Brainstorm → Plan → Execute Pipeline — jede Anfrage durchläuft die gleiche Pipeline. Trivial = 1-Step-Plan, komplex = Multi-Step mit Subagents. 0 Approval-Gates.
• Klärungs-Fragen — bei Mehrdeutigkeit triggert der Agent clarify_intent mit 1–3 Fragen, statt zu raten.
• Subagent-Delegation — Steps werden an Analyze-, Research- oder Action-Subagents dispatched, die ihre eigenen Tool-Calls machen und per report_to_master zurückmelden.
• Tool-Calling — Zugriff auf alle Module: AI-Visibility scoren, Keywords recherchieren, Artikel generieren, Backlinks pullen, SERP-Position prüfen, Action-Items erstellen, E-Mails schicken, Bilder analysieren, eigene Daten queryen. Datenabfragen lesen nur die Daten deines eigenen Teams und ändern nie etwas.
• Live-UI mit SSE — sticky Live-Pille während der Plan läuft, Permanent-Card im Stream nach Abschluss, opt-in Sidebar für Drill-Down jedes Steps inklusive Output-JSON und Tool-Calls.
• Persistent Plans — eigene Tabellen agentic_plans (1 Row/Plan) und agentic_plan_steps (N Rows/Plan), Plan-History pro Session, Smart-Retry mit Invalidation abhängiger Steps.
• Wiki-Integration — query_wiki-Tool durchsucht dieses Wiki und zitiert die Quellen.
• Vorschläge, die zu deinen Daten passen — die Kacheln über dem Eingabefeld richten sich nach dem, was in deinem Team schon angelegt ist. Ein Vorschlag erscheint nur, wenn die Daten dafür da sind: „5 Content-Ideen für dein wichtigstes Themenfeld" zum Beispiel erst, wenn Keywords oder Artikel vorliegen — sonst steht dort ein Einstiegsvorschlag wie „Erstes Projekt anlegen". So kostet dich kein Vorschlag Credits für eine Antwort, die mangels Daten keine sein kann.

Beispiel-Prompts

• „Welche meiner Keywords ranken nicht in Top 10?"
• „Schreib einen Artikel zu Stoßdämpfer wechseln und veröffentliche ihn auf Blog autohaus-mueller."
• „Wer wird in ChatGPT zum Thema vegane Sneaker zitiert, der nicht von uns ist?"
• „Welche Backlinks haben wir in den letzten 30 Tagen verloren und sind toxisch?"
• „Erstelle aus dem letzten Tracking-Run einen Reality-Check-PDF und schick ihn an info@firma.de."
• „Bau mir einen Cluster aus 50 Long-Tails zu crm software mit KD<35."

Wann nutzen

• Du kennst den Klick-Pfad in der UI nicht oder willst ihn umgehen.
• Du brauchst eine Antwort, die Daten aus 3+ Modulen kombiniert (z.B. Backlinks × Rank-Tracker × AVI).
• Du willst eine wiederholbare Mini-Pipeline ohne Code (Generate → Score → Publish).
• Du willst Plan-Telemetrie (welcher Step, welche Tools, welche Credits) als Audit-Trail.

Workflow

1. Session öffnen — UI unter /chat oder API. Optional gallery_image_id für visuelle Anfragen.
2. Fragen — POST /agentic/chat mit {message, session_id?}.
3. Klärung beantworten — wenn Agent nachfragt, antworte normal in der nächsten Message.
4. Plan beobachten — Live-Pille zeigt Steps + aktuellen Status. Sidebar für Drill-Down.
5. Resultat erhalten — Response enthält text, tool_calls[], iterations, credits_used, duration_ms, resumed.

Bei async-pulls (z.B. DataForSEO) wartet der Endpoint serverseitig per wait_for_final=true (default) bis zu ~480 s auf den finalen Resume-Turn — resumed: true heißt: der text ist die fertige Antwort, nicht der Wartehinweis.

API

Body von /agentic/chat:

{
  "message": "Welche Backlinks habe ich in 30 Tagen verloren?",
  "session_id": 1234
}

Credits & Limits

• Variabel. Credits hängen von den Tools ab, die der Agent aufruft (z.B. Keyword-Research = 5, Generate = 5, Image-Analyze = je nach Modus).
• Iterations-Cap: 150 Tool-Calls pro Turn (env-overridable).
• Wall-Clock-Cap: 25 Minuten pro Turn.
• No-Progress-Detector: 8 — bei Stillstand wechselt der Agent in einen tools-disabled Summarize-Call statt einer harten Fehlermeldung.
• PHP-FPM Hardlimit: 600 s synchronen Response. Setze Client-Timeout entsprechend.
• Triple-scoped: team_id + user_id + session_id gegen IDOR.

Zu einer Stelle in der Antwort nachfragen

Antworten im Chat sind oft lang, und die Rückfrage betrifft meist einen Satz daraus. Statt ihn abzutippen, markierst du ihn: sobald du in einer Chat-Nachricht Text markierst, erscheint daneben ein kleiner Knopf KI fragen.

Ein Klick darauf setzt den markierten Text als Zitat vor deinen Entwurf in das Eingabefeld — als Markdown-Zitat, also jede Zeile mit > davor. Der Cursor springt ans Ende, und das Eingabefeld bittet dich mit „Deine Frage zum markierten Text …" um die eigentliche Frage. Du schreibst sie dahinter und sendest ab.

Das Zitat ist der Kontext. Es wird als Teil deiner Nachricht mitgeschickt, nicht als unsichtbare Zusatzinformation — du siehst also genau das, was die KI sieht, und in deiner Nachrichtenblase bleibt das Zitat später abgesetzt stehen.

Drei Dinge, die den Knopf betreffen:

• Er erscheint nur in einer Chat-Nachricht. Markierst du Text in der Kopfzeile oder im Leer-Zustand, passiert nichts — das ist Absicht, sonst stünde er überall im Weg.
• Er verschwindet von selbst, wenn du daneben klickst, die Markierung aufhebst, scrollst oder Escape drückst.
• Er ist auch ohne Maus erreichbar. Markierst du mit Umschalt und den Pfeiltasten, bekommt der Knopf den Fokus erst, wenn du die Umschalt-Taste loslässt — solange du sie hältst, kannst du die Markierung weiter ausdehnen. Auf dem Telefon erscheint der Knopf unterhalb der Markierung, damit ihn der Finger nicht verdeckt.

Eine laufende Anfrage stoppen

Solange „Rankion AI denkt nach…" zu sehen ist, steht daneben ein Stoppen-Knopf. Ein Klick beendet die Anfrage: die KI hört auf zu arbeiten, und du kannst sofort etwas Neues fragen — du musst nicht warten, bis der alte Durchlauf von selbst fertig wird.

Drei Dinge, die du dabei wissen solltest:

• Nach dem Stopp entstehen keine weiteren Kosten. Was die KI bis dahin getan hat, ist allerdings schon geschehen und bleibt abgerechnet — ein Stopp holt verbrauchte Credits nicht zurück. Je früher du stoppst, desto weniger ist verbraucht.
• Eine angefangene Antwort bleibt stehen. Hatte die KI schon Text geschrieben, bleibt er im Verlauf, gekennzeichnet als unvollständig. Du siehst also, wofür du bezahlt hast, und kannst darauf aufbauen.
• Ein laufender Arbeitsplan wird mitbeendet. Hat die KI sich für deine Frage mehrere Schritte vorgenommen, werden auch die abgebrochen — es läuft nichts im Hintergrund weiter.

Der Stopp ist auch über die Schnittstelle erreichbar: POST /v1/agentic/sessions/{session}/abort, ohne Credits.

Wenn eine Antwort nicht ankommt

Bleibt „Rankion AI denkt nach…" ungewöhnlich lange stehen, hat der Chat einen eingebauten Aufräumer: spätestens nach 15 Minuten ohne Fortschritt (z. B. weil im Hintergrund ein Prozess abgebrochen ist) wechselt die Anzeige automatisch zu einer roten „Antwort fehlgeschlagen"-Meldung mit einem „Zurücksetzen & neu fragen"-Knopf. Ein Klick darauf setzt den Chat zurück, sodass die Frage erneut gestellt werden kann. Eine normale, nur etwas langsamere Antwort (z. B. bei einer aufwendigen Recherche) wird davon nicht unterbrochen; die 15-Minuten-Schwelle liegt deutlich über jeder üblichen Antwortzeit.

Datei-Downloads (generate_download)

Bittest du den Agenten um eine Datei („gib mir den Plan als Markdown/Excel/CSV"), nutzt er das generate_download-Tool und liefert eine signierte Download-URL (24 h gültig, Datei unter deinem Account, Auto-Löschung nach 30 Tagen).

• Der komplette Dateiinhalt gehört in das Pflichtfeld content — bei md/txt/json der volle Text/das Dokument, bei xlsx/csv ein Array von Zeilen-Objekten. Das Feld description ist nur eine kurze Notiz neben dem Link, niemals der Inhalt selbst.
• Hintergrund: Der Agent verwechselte zeitweise content und description und packte den Report-Text in description → das Tool lehnte mit „content ist Pflicht" ab und der Turn lief in den No-Progress-Detector. Behoben durch geschärfte Tool-Beschreibung (Tool: App\Agentic\Tools\GenerateDownloadTool). Pflichtfelder: format, filename, content.

Verwandte Module

• AI-Visibility Tracking — der Agent kann Tracking-Runs starten und AVI-Werte interpretieren.
• Keyword Explorer & Research — Recherche-Tools sind direkt callable.
• AI Content Editor — Generate, Score, Optimize, Publish komplett orchestrierbar.
• Backlinks-Modul — Backlink-Pulls und Toxic-Detection per Frage.