Diese Fallstudie integriert AgentChat in eine mandantenfähige Projekt-SaaS namens ProjectDesk. Jeder Kunde verwendet dieselben Projekt- und Aufgaben-APIs, aber die Benutzerin Alice darf nur im Workspace_a und der Benutzer Bob nur im Workspace_b agieren. Wir verwenden ein einziges API-Dokument wieder und erstellen dabei zwei Sitzungen mit unterschiedlichen schreibgeschützten Request-Headern.
Die Sicherheitsgrenze ist kein Prompt, der das Modell auffordert, innerhalb eines Workspace zu bleiben. ProjectDesk authentifiziert und autorisiert jede HTTP-Tool-Anfrage. AgentChat wählt die Operationen aus und fügt die richtigen Sitzungsdaten zur Authentifizierung ein; ProjectDesk entscheidet, ob die jeweilige Operation zulässig ist.
Schritt 1: Die Business-API mandantenfähig machen
GET /v1/projects?status=active
→ { "items": [{ "project_id": "proj_12", "name": "Website launch", "role": "editor" }] }
POST /v1/projects/proj_12/tasks
{ "title": "Review launch checklist", "due_at": "2026-08-28" }
→ { "task_id": "task_91", "project_id": "proj_12", "status": "open" }ProjectDesk überprüft das Bearer-Token, leitet daraus die Identität des Benutzers ab, bestätigt die Mitgliedschaft im Workspace aus X-Workspace-ID und fügt diesen Workspace jeder Datenbankabfrage hinzu. Eine Projekt-ID allein umgeht den Mandantenfilter niemals. Lese- und Schreibbereiche werden separat geprüft.
Schritt 2: Ein wiederverwendbares ProjectDesk-Dokument registrieren
POST $AGENTCHAT_SITE_URL/api/api-documents
Authorization: Bearer ac_live_AGENTCHAT_KEY
Content-Type: application/json
{
"title": "ProjectDesk Projects and Tasks",
"description": "List authorized projects and create tasks inside them.",
"content": "# ProjectDesk API\nBase URL: https://projects.example.com/v1\n\nGET /projects?status=active returns only projects visible to the authenticated workspace member. Response items contain project_id, name, and role.\n\nPOST /projects/{project_id}/tasks body: title required, due_at optional ISO date. Create only after resolving a project through GET /projects. Response contains task_id, project_id, and status.\n\n401 means the session credential is missing or expired. 403 means the current member lacks permission. On either response, do not retry and tell the user that the chat credential or role must be updated."
}Dieses Dokument beschreibt eine Fähigkeit, nicht eine Identität. ProjectDesk speichert die UUID des zurückgegebenen Dokuments einmalig und hängt sie an Chats für jeden Mandanten an. In das Dokument sind weder eine Mandanten-ID noch ein Benutzertoken oder ein Geheimnis eingebettet.
Schritt 3: Alices AgentChat-Sitzung erstellen
POST $AGENTCHAT_SITE_URL/api/agent/sessions
Authorization: Bearer ac_live_AGENTCHAT_KEY
Content-Type: application/json
{
"title": "ProjectDesk assistant — Alice",
"llm_config_id": "llm_config_uuid",
"api_document_ids": ["projectdesk_document_uuid"],
"system_prompt": "Help the current member manage projects. Never infer access from names; rely on API results.",
"max_turns": 10,
"host_headers": [
{ "host": "projects.example.com", "header_key": "Authorization", "header_value": "Bearer alice_short_lived_token" },
{ "host": "projects.example.com", "header_key": "X-Workspace-ID", "header_value": "workspace_a" }
]
}Die Sitzungsantwort enthält die üblichen Konfigurationsdaten, gibt jedoch niemals header_value zurück. AgentChat kann Alices Token in eine passende HTTP-Anfrage einfügen, während das Modell weder das Token noch den gespeicherten Autorisierungs-Header sehen kann.
Schritt 4: Bobs Sitzung aus demselben Dokument erstellen
POST $AGENTCHAT_SITE_URL/api/agent/sessions
Authorization: Bearer ac_live_AGENTCHAT_KEY
Content-Type: application/json
{
"title": "ProjectDesk assistant — Bob",
"llm_config_id": "llm_config_uuid",
"api_document_ids": ["projectdesk_document_uuid"],
"system_prompt": "Help the current member manage projects. Never infer access from names; rely on API results.",
"max_turns": 10,
"host_headers": [
{ "host": "projects.example.com", "header_key": "Authorization", "header_value": "Bearer bob_short_lived_token" },
{ "host": "projects.example.com", "header_key": "X-Workspace-ID", "header_value": "workspace_b" }
]
}Der API-Vertrag und die Modellkonfiguration können gemeinsam genutzt werden, während Sitzungs-Header den Aufrufer für jede Konversation festlegen. Dadurch wird vermieden, für jeden Kunden doppelte Dokumente zu erstellen, und die Rotation von Zugangsdaten bleibt unabhängig von der Dokumentation der Fähigkeiten.
Schritt 5: Führen Sie in beiden Sitzungen dieselbe Anweisung aus
POST /api/agent/sessions/alice_session_uuid/chat
{ "message": "Create a task called Review launch checklist in the Website launch project, due August 28." }
POST /api/agent/sessions/bob_session_uuid/chat
{ "message": "Create a task called Review launch checklist in the Website launch project, due August 28." }Für Alice sendet http_request Alices Token und workspace_a ausschließlich an projects.example.com. ProjectDesk gibt die für Alice sichtbaren Projekte zurück; der Agent ermittelt das angeforderte Projekt aus diesem Ergebnis und erstellt die Aufgabe. Bobs Ausführung folgt demselben Plan, aber ProjectDesk filtert anhand von workspace_b. Wenn Bob dieses Projekt nicht sehen kann, erhält der Agent kein passendes Projekt und darf weder Alices Projekt-ID erfinden noch wiederverwenden.
Wie Host-Matching das Durchsickern von Zugangsdaten verhindert
AgentChat fügt einen Sitzungs-Header nur dann hinzu, wenn das HTTP-Ziel mit dem konfigurierten Hostnamen und dem optionalen Port übereinstimmt. Weiterleitungen werden bei jedem Hop erneut abgeglichen. Eine Berechtigung für projects.example.com wird daher weder an files.example.net, einen Bildhost noch an ein unerwartetes Weiterleitungsziel übertragen.
So sieht ein Berechtigungsfehler aus
HTTP/1.1 403 Forbidden
Content-Type: application/json
{ "error": "insufficient_scope", "required_scope": "tasks:write" }Die Anweisungen von AgentChat behandeln 401 und 403 als Probleme bei der Konfiguration der Zugangsdaten. Der Agent sollte den blockierten Vorgang stoppen und dem Benutzer mitteilen, welche Berechtigung überprüft werden muss. Er sollte das Geheimnis nicht im Chat anfordern, gespeicherte Header-Werte nicht offenlegen und eine Ablehnung nicht wiederholt erneut versuchen.
ProjectDesk sollte Ablehnungsantworten nützlich, aber nicht sensibel halten. Es kann den erforderlichen Berechtigungsumfang nennen, ohne zu bestätigen, ob ein mandantenübergreifender Datensatz existiert. Audit-Protokolle sollten den verifizierten Akteur und die angeforderte Ressource erfassen, während Bearer-Tokens und andere Header-Werte geschwärzt werden.
Schritt 6: Den AgentChat-Zustand und den ProjectDesk-Zustand getrennt verarbeiten
GET /api/agent/sessions/alice_session_uuid/messages?after_id=&after_revision=0
GET /api/agent/sessions/alice_session_uuid/state
GET https://projects.example.com/v1/projects/proj_12/tasksDie ProjectDesk-Chatoberfläche fragt AgentChat-Nachrichten regelmäßig ab und führt während der Verarbeitung Überarbeitungen des Assistenten zusammen. Nach Abschluss des Laufs lädt das Projektboard die Aufgaben über die ProjectDesk-API oder aus der Datenbank neu. Die Antwort des Assistenten erklärt die Aktion, aber der gespeicherte Aufgabensatz – nicht der Text – ist der maßgebliche Produktzustand.
Verwenden Sie getrennte Sitzungen für unterschiedliche Berechtigungsstufen
Ein schreibgeschützter Assistent kann Such- und Berichtsdokumente mit einem Token anhängen, dessen Berechtigungen auf Lesebereiche beschränkt sind. Ein Projekteditor kann Dokumente zum Erstellen von Aufgaben mit einem Token mit Schreibberechtigungen anhängen. Hochriskante Vorgänge wie Änderungen an der Abrechnung, die Löschung eines Kontos oder die Veröffentlichung für die Öffentlichkeit sollten eine engere Sitzung oder einen produktseitigen Endpunkt für ausstehende Genehmigungen verwenden.
Bei Genehmigungsabläufen erstellt der Agent eine ausstehende Aktion und gibt deren ID zurück. ProjectDesk zeigt dem Benutzer die genaue Änderung an, protokolliert die ausdrückliche Genehmigung und führt den irreversiblen Vorgang in seinem eigenen Backend aus. Die endgültige Autorisierungsentscheidung hängt nie davon ab, dass das Modell eine Bestätigungsformulierung interpretiert.
Tests zur Isolierung der Produktionsumgebung
- Verwenden Sie Alices Sitzung, um eine bekannte Projekt-ID von workspace_b anzufordern, und überprüfen Sie, dass ProjectDesk keine mandantenübergreifenden Daten zurückgibt.
- Führen Sie für Alice und Bob identische Prompts aus und überprüfen Sie, dass ihre HTTP-Aufrufe unterschiedliche autorisierte Ergebnisse erhalten.
- Lassen Sie jedes Sitzungstoken ablaufen, widerrufen Sie es, lassen Sie es weg und beschädigen Sie es, und überprüfen Sie jeweils das korrekte 401-Verhalten.
- Geben Sie einem Mitglied einen schreibgeschützten Berechtigungsumfang und überprüfen Sie, dass jeder Schreibvorgang für Aufgaben den Status 403 zurückgibt, ohne die Datenbank zu verändern.
- Leiten Sie eine Anfrage an einen anderen Hostnamen weiter und überprüfen Sie, dass AgentChat keine konfigurierten Zugangsdaten weiterleitet.
- Untersuchen Sie die Antworten der Sitzungs-API, Tool-Ergebnisse, Anwendungsprotokolle und Fehlermeldungen auf das versehentliche Offenlegen von Geheimnissen.
- Stoppen Sie einen Lauf und setzen Sie ihn fort. Überprüfen Sie anschließend, dass die fortgesetzte Arbeit weiterhin ausschließlich die Header und Dokumentbindungen dieser Sitzung verwendet.
Das wiederverwendbare mandantenfähige Muster
Registrieren Sie die Geschäftsfunktion einmalig. Erstellen Sie eine AgentChat-Sitzung pro Benutzerunterhaltung. Fügen Sie die relevanten Dokument-UUIDs hinzu, injizieren Sie kurzlebige Zugangsdaten ausschließlich für den jeweiligen API-Host und erzwingen Sie Identität und Richtlinien innerhalb Ihrer SaaS-Endpunkte. Überlassen Sie AgentChat anschließend die Verwaltung der Schlussfolgerungen und des dauerhaft gespeicherten Unterhaltungsverlaufs, während Ihre eigene Datenbank die maßgebliche Quelle bleibt.