So fügen Sie Ihrer SaaS mithilfe bereits vorhandener APIs einen KI-Agenten hinzu

Diese Anleitung implementiert eine vollständige AgentChat-Integration für ein fiktives SaaS namens SupportFlow. SupportFlow verfügt bereits über APIs zum Auffinden überfälliger Rechnungen, zum Senden von Erinnerungen und zum Hinzufügen von Kontonotizen. Wir werden diese APIs in AgentChat bereitstellen, einen benutzerbezogenen Chat erstellen, einen asynchronen Agentenlauf starten und das Ergebnis aus dauerhaft gespeicherten Nachrichten und der eigenen Datenbank von SupportFlow darstellen.

Die wichtige architektonische Grenze ist konkret: AgentChat übernimmt die Modelllogik, die Tool-Auswahl, den Chatverlauf und die Ablaufsteuerung. SupportFlow bleibt für Kunden, Rechnungen, Autorisierung, Validierung und die endgültigen Geschäftsdatensätze zuständig. Die API-Dokumentation verbindet die beiden Systeme.

Sie fügen nicht jede SaaS-Funktion zur Agentenlaufzeit hinzu. Sie stellen eine kleine Gruppe zentraler Geschäftsoperationen als HTTP-APIs bereit und stellen deren Verträge für jeden Chat bereit.

Der abgeschlossene Anfrageablauf

SupportFlow erstellt über das Dashboard einen einzigen AgentChat-API-Schlüssel und speichert ihn ausschließlich in seinem Backend.
Sein Backend registriert die SupportFlow-Operationen mit POST /api/api-documents.
Wenn ein Benutzer den Assistenten öffnet, erstellt SupportFlow eine Sitzung mit der Dokument-UUID, einer UUID für die LLM-Konfiguration und nur zum Schreiben bestimmten Benutzerzugangsdaten für seinen API-Host.
SupportFlow sendet die Benutzernachricht an POST /api/agent/sessions/{id}/chat.
AgentChat liest den angehängten Vertrag und verwendet sein integriertes Tool http_request, um SupportFlow aufzurufen.
SupportFlow fragt die AgentChat-Nachrichten regelmäßig ab, während die normale Benutzeroberfläche Rechnungen und Notizen aus der SupportFlow-Datenbank liest.

Schritt 1: Eng gefasste Geschäftsoperationen bereitstellen

Der Agent benötigt weder Datenbankzugriff noch eine einzige übergroße interne API. Für diesen Ablauf stellt SupportFlow genau drei mandantenfähige Endpunkte bereit:

GET /v1/invoices?status=overdue&limit=3
→ { "items": [{ "invoice_id": "inv_72", "account_id": "acct_9", "amount": 480, "currency": "USD", "due_at": "2026-08-01" }] }

POST /v1/reminders
{ "invoice_id": "inv_72", "tone": "friendly" }
→ { "reminder_id": "rem_31", "status": "queued" }

POST /v1/accounts/acct_9/notes
{ "body": "Friendly reminder queued for overdue invoice inv_72." }
→ { "note_id": "note_55", "created_at": "2026-08-23T09:30:00Z" }

Jeder Endpunkt authentifiziert den Aufrufer, leitet den Mandanten aus den Zugangsdaten ab und filtert jeden Datenbankvorgang. IDs, die von einem Aufruf zurückgegeben werden, werden zu sicheren Eingaben für den nächsten. Das Modell erhält niemals ein Datenbankpasswort oder eine uneingeschränkte Abfrageschnittstelle.

Schritt 2: Die Modellkonfiguration einmalig erstellen

Jede AgentChat-Sitzung erfordert eine benutzereigene LLM-Konfiguration. SupportFlow kann eine über das Dashboard oder die API erstellen und die zurückgegebene UUID speichern.

POST $AGENTCHAT_SITE_URL/api/llm-config
Authorization: Bearer ac_live_AGENTCHAT_KEY
Content-Type: application/json

{
  "name": "Support production model",
  "api_url": "https://llm-provider.example.com/v1/chat/completions",
  "api_key": "provider_secret",
  "model": "provider-model-name",
  "max_context_length": 128000,
  "max_output_tokens": 8192,
  "temperature": 0.2,
  "disable_reasoning": false
}

Die Antwort ist in success und data verpackt. Speichern Sie data.id als llm_config_id, die beim Erstellen von Chats verwendet wird. AgentChat maskiert den Anbieterschlüssel beim erneuten Auslesen der Konfigurationen.

Schritt 3: Das SupportFlow-API-Dokument bereitstellen

Dies ist der Plugin-Mechanismus. Das Dokument enthält operative Anweisungen, exakte Eingaben, exakte Ausgaben und Regeln für die Reihenfolge – keinen Marketingtext und keinen Link, der den Agenten zum Raten zwingt.

POST $AGENTCHAT_SITE_URL/api/api-documents
Authorization: Bearer ac_live_AGENTCHAT_KEY
Content-Type: application/json

{
  "title": "SupportFlow Invoice Actions",
  "description": "Find overdue invoices, queue reminders, and record account notes.",
  "content": "# SupportFlow Invoice Actions\nBase URL: https://support.example.com/v1\n\nGET /invoices?status=overdue&limit=3 returns items with invoice_id, account_id, amount, currency, and due_at. Use only when the user requests invoice lookup.\n\nPOST /reminders body: invoice_id required; tone is friendly or firm. Response: reminder_id and status. Never send more reminders than the user requested.\n\nPOST /accounts/{account_id}/notes body: body required. Call only after the reminder request succeeds. Include the invoice ID and reminder status in the note.\n\nIf any write returns 401 or 403, stop writing and explain that the session credential needs access. Do not retry a permission denial."
}

AgentChat gibt das neue Dokument einschließlich seiner UUID in data zurück. Bewahren Sie diese UUID in der Integrationskonfiguration von SupportFlow auf. Wenn Sie dieses Dokument später aktualisieren, ändern sich die Anweisungen, die für nachfolgende Chat-Nachrichten verwendet werden, da Sitzungen das Dokument anhängen, anstatt es zu kopieren.

Schritt 4: Erstellen Sie einen Chat für den aktuellen SupportFlow-Benutzer

POST $AGENTCHAT_SITE_URL/api/agent/sessions
Authorization: Bearer ac_live_AGENTCHAT_KEY
Content-Type: application/json

{
  "title": "Invoice assistant for user_42",
  "llm_config_id": "llm_config_uuid",
  "api_document_ids": ["supportflow_document_uuid"],
  "system_prompt": "Act only on the user’s explicit request. Summarize every write with the affected invoice and account IDs.",
  "compact_threshold_percent": 80,
  "max_turns": 12,
  "tool_timeout_seconds": 120,
  "tool_result_max_chars": 10000,
  "host_headers": [
    { "host": "support.example.com", "header_key": "Authorization", "header_value": "Bearer short_lived_user_42_token" },
    { "host": "support.example.com", "header_key": "X-Workspace-ID", "header_value": "workspace_7" }
  ]
}

Header-Werte sind schreibgeschützt. AgentChat speichert sie für diese Sitzung, fügt sie nur ein, wenn http_request den passenden Host als Ziel verwendet, und gibt ihre Werte weder an das Modell noch in API-Antworten weiter. Ein zweiter SupportFlow-Benutzer erhält eine andere Sitzung mit derselben Dokument-UUID, aber anderen Headern.

Schritt 5: Starten Sie den asynchronen Vorgang

POST $AGENTCHAT_SITE_URL/api/agent/sessions/session_uuid/chat
Authorization: Bearer ac_live_AGENTCHAT_KEY
Content-Type: application/json

{ "message": "Find my three most overdue invoices, send each a friendly reminder, and add a note to each account." }

→ { "success": true, "data": { "session_id": "session_uuid", "state": "processing" } }

AgentChat kehrt sofort zurück und setzt den Lauf im Hintergrund fort. Der Agent erhält das angehängte SupportFlow-Dokument sowie genau vier integrierte Tools: get_api_document, http_request, sleep und view_image. Die SupportFlow-Funktionen sind nicht in diese Tools kompiliert; sie werden aus dem bereitgestellten API-Vertrag erlernt und über http_request ausgeführt.

Was der Agent während dieser Anfrage tut

Den dokumentierten Endpunkt für überfällige Rechnungen über http_request aufrufen.
Die strukturierten Einträge lesen und höchstens die drei vom Benutzer angeforderten Rechnungen auswählen.
Erinnerungen in die Warteschlange stellen. Unabhängige Aufrufe, die durch eine Modellantwort erzeugt werden, können gleichzeitig ausgeführt werden.
Nachdem erfolgreiche Erinnerungergebnisse vorliegen, den Endpunkt für Kontonotizen mit jeder zurückgegebenen Rechnungs- und Konto-ID aufrufen.
Eine abschließende Assistentennachricht erstellen, in der die abgeschlossenen Vorgänge und jeder Fehler pro Rechnung aufgeführt werden.

Deshalb ist das Design von Antworten wichtig. Ein vages Ergebnis wie „Erfolg“ lässt dem Agenten nichts Verlässliches, woran er die nächste Aktion anknüpfen kann. Strukturierte IDs und Statusangaben ermöglichen es der Denkschleife, mehrere gewöhnliche APIs zu einem einzigen Ergebnis für den Benutzer zu verknüpfen.

Schritt 6: Dauerhafte Nachrichten statt eines LLM-Streams abfragen

GET $AGENTCHAT_SITE_URL/api/agent/sessions/session_uuid/messages?after_id=&after_revision=0
Authorization: Bearer ac_live_AGENTCHAT_KEY

→ {
  "success": true,
  "data": {
    "messages": [{ "id": "message_uuid", "role": "assistant", "content": "...", "stream_status": "streaming", "revision": 4 }],
    "last_id": "message_uuid",
    "last_revision": 4,
    "is_processing": true,
    "total_tokens": 2840
  }
}

SupportFlow fragt einmal pro Sekunde über sein Backend oder einen vorgeschalteten Client ab, führt Zeilen anhand der Nachrichten-ID zusammen und ersetzt den Inhalt nur, wenn die Revision zunimmt. Die Datenbank von AgentChat ist die maßgebliche Quelle für die Gesprächsausgabe. Die Datenbank von SupportFlow bleibt die maßgebliche Quelle für Rechnungen, Erinnerungen und Notizen.

Sobald is_processing den Wert false annimmt, kann SupportFlow seine Rechnungs- und Kontenabfragen aktualisieren. Die normale Produktoberfläche zeigt dann die über die eigenen APIs erstellten Erinnerungen und Notizen an; sie muss nicht die Formulierungen des Assistenten analysieren, um den Geschäftszustand zu rekonstruieren.

Steuerung der Ausführung und Fehlerbehebung

GET  /api/agent/sessions/session_uuid/state
POST /api/agent/sessions/session_uuid/stop
POST /api/agent/sessions/session_uuid/continue

Der Status-Endpunkt gibt an, ob die Verarbeitung aktiv ist und ob die nächste Aktion „continue“ lautet. Stop-Anfragen brechen einen aktiven Lauf ab. Wenn ein behebbarer Fehler oder das Limit für die maximale Anzahl von Turns die Arbeit pausiert, startet „continue“ einen weiteren Lauf mit einem neuen Turn-Budget und demselben persistenten Gesprächskontext.

Was bereitgestellt werden sollte – und was nicht

Stellen Sie APIs bereit, die stabile Geschäftsfunktionen abbilden: Suchen, Erstellen, Aktualisieren, Validieren, Veröffentlichen oder das Prüfen des Jobstatus.
Dokumentieren Sie erforderliche Felder, Einschränkungen, Antwortobjekte, Fehlerbedeutungen, Seiteneffekte und Anforderungen an die Reihenfolge.
Binden Sie nur die für das Chat-Erlebnis erforderlichen Dokumente ein, statt jeden internen Endpunkt einzubinden.
Halten Sie Zugangsdaten in host-spezifischen Session-Headern, niemals in Prompts oder im Inhalt der API-Dokumentation.
Stellen Sie kein rohes SQL, keinen uneingeschränkten Dateizugriff und keinen generischen internen Proxy bereit, nur um den Agenten flexibel zu machen.
Lassen Sie Ihre eigene Autorisierung und Validierung bei jeder Tool-Anfrage genau so laufen wie bei anderen Clients.

Warum der Funktionsumfang wachsen kann, ohne dass der Kernwerkzeugsatz erweitert werden muss

Ein RAG-Produkt kann Such- und Zitations-Endpunkte bereitstellen. Ein Story-Produkt kann Endpunkte für Kapitel, Bildgenerierung und Veröffentlichung bereitstellen. Ein Coding-Produkt kann Endpunkte für Workspace-Dateien, Prüfungen und Deployments bereitstellen. AgentChat verwendet weiterhin dieselben vier Kernwerkzeuge. Die anwendungsspezifischen Operationen werden als API-Dokumente bereitgestellt, sodass das Hinzufügen einer Fähigkeit eine Bereitstellungsänderung und kein neues Release der Agent-Laufzeit erfordert.

Das ist das zentrale AgentChat-Muster: API-Dokumente erstellen, eine Chat-Sitzung mit festgelegtem Geltungsbereich erstellen, den Agenten deine HTTP-Operationen zusammenstellen lassen, dauerhafte Nachrichten verarbeiten und die daraus resultierenden Datensätze aus deiner eigenen Anwendungsdatenbank rendern.