So fügen Sie einer KI-Schreibanwendung einen Agenten zur Story-Erstellung hinzu

Diese Fallstudie verbindet einen bestehenden KI-Story-SaaS namens StoryShelf mit AgentChat. Ein Benutzer erstellt eine Geschichte durch ein Gespräch; der Agent schreibt strukturierte Geschichten- und Kapitelaufzeichnungen über die StoryShelf-APIs, startet Illustrationsaufträge, prüft die zurückgegebenen Bild-URLs und aktualisiert die Geschichte. StoryShelf liest anschließend seine eigene Datenbank und zeigt das Ergebnis in seiner normalen Bibliothek und seinem Editor an.

Der wichtige Punkt ist, dass AgentChat nicht zur Story-Datenbank wird und StoryShelf keine lange Antwort des Assistenten in Datensätze zerlegt. Der Agent führt dieselben kontrollierten Vorgänge aus, die die StoryShelf-Anwendung bereits versteht.

Schritt 1: das StoryShelf-Fähigkeitenpaket bereitstellen

POST /v1/stories
GET  /v1/stories/{story_id}
POST /v1/stories/{story_id}/chapters
PUT  /v1/stories/{story_id}/chapters/{chapter_id}
POST /v1/image-jobs
GET  /v1/image-jobs/{job_id}
PUT  /v1/stories/{story_id}/cover

Jede Antwort auf eine Erstellungsanfrage gibt stabile IDs zurück. Schreibvorgänge für Stories und Kapitel sind mit einer client_request_id idempotent, sodass ein erneuter Versuch keine Duplikate erstellt. Bildaufträge laufen asynchron und geben poll_after_seconds zurück. Die Antwort auf einen abgeschlossenen Bildauftrag enthält asset_id und image_url, niemals Base64-Daten.

Schritt 2: das StoryShelf-Dokument bereitstellen

POST /api/api-documents
Authorization: Bearer ac_live_AGENT_CHAT_KEY
Content-Type: application/json

{
  "title": "StoryShelf Story and Illustration API",
  "description": "Create stories and chapters, generate illustrations, and attach image assets.",
  "content": "# StoryShelf API\nBase URL: https://stories.example.com/v1\n\nCreate the story record before chapters and preserve every returned ID. Write chapters one at a time.\n\nPOST /stories body: client_request_id, title, audience, style, premise, outline[]. Response: story_id, status.\n\nPOST /stories/{story_id}/chapters body: client_request_id, position, title, content. Response: chapter_id, revision.\n\nPOST /image-jobs body: client_request_id, story_id, chapter_id optional, prompt, aspect_ratio. Response: job_id, status, poll_after_seconds. Start the job in one turn; sleep and poll in a later turn.\n\nGET /image-jobs/{job_id} returns status and, when succeeded, asset_id and image_url. Call view_image when visual inspection is useful.\n\nPUT /stories/{story_id}/cover body: asset_id.\n\nNever publish a draft unless the user explicitly asks."
}

Das Dokument enthält Workflow-Regeln, die sich aus einer Liste von OpenAPI-Pfaden nicht zuverlässig ableiten lassen: IDs beibehalten, asynchrone Vorgänge getrennt behandeln, Bild-URLs prüfen und nicht implizit veröffentlichen.

Schritt 3: die Story-Sitzung des Benutzers erstellen

POST /api/agent/sessions
Authorization: Bearer ac_live_AGENT_CHAT_KEY
Content-Type: application/json

{
  "title": "Story creator for user_88",
  "llm_config_id": "creative_model_uuid",
  "api_document_ids": ["story_api_document_uuid"],
  "system_prompt": "Help the user plan and create stories. Save approved creative work through StoryShelf APIs. Keep the user informed when image jobs are running.",
  "max_turns": 25,
  "tool_timeout_seconds": 180,
  "tool_result_max_chars": 12000,
  "host_headers": [
    { "host": "stories.example.com", "header_key": "Authorization", "header_value": "Bearer short_lived_story_user_token" }
  ]
}

StoryShelf erstellt diese Sitzung über sein Backend und speichert die zurückgegebene Sitzungs-UUID neben der Unterhaltung des Benutzers. Der kurzlebige Header beschränkt alle Lese- und Schreibzugriffe auf die Story-API auf user_88. Er wird zum Zeitpunkt der Anfrage injiziert und ist weder im LLM-Kontext noch in den Antworten der AgentChat-API enthalten.

Schritt 4: Der Benutzer erstellt Inhalte über den Chat

POST /api/agent/sessions/session_uuid/chat
Authorization: Bearer ac_live_AGENT_CHAT_KEY
Content-Type: application/json

{
  "message": "Create a three-chapter story for ages 8-10 about a child who repairs a lighthouse for lost spaceships. Use a gentle watercolor style and make an illustrated cover."
}

AgentChat speichert die Benutzernachricht und gibt den Status „processing“ zurück. Die StoryShelf-Oberfläche beginnt sofort, Nachrichten abzufragen, anstatt die Chat-Anfrage offen zu halten.

Die konkrete Abfolge der Tool-Aufrufe

1. Der Agent plant den Titel, die Prämisse, die Zielgruppe, den Stil und eine dreiteilige Gliederung.
2. Er ruft POST /stories auf und erhält story_id story_123.
3. Er schreibt Kapitel eins, zwei und drei über separate API-Aufrufe und bewahrt jede chapter_id auf.
4. Er erstellt einen Bild-Prompt, der mit dem gespeicherten Stil der Geschichte übereinstimmt, und ruft POST /image-jobs auf.
5. Da der Auftrag asynchron abgeschlossen werden muss, ruft der nächste Modell-Turn sleep mit poll_after_seconds auf; eine spätere Anfrage fragt dann GET /image-jobs/job_7 ab.
6. Wenn die Antwort image_url enthält, ruft der Agent view_image auf, sodass die Illustration als native multimodale Eingabe in den Kontext gelangt.
7. Wenn das Bild zur Geschichte passt, ruft er PUT /stories/story_123/cover mit asset_id auf. Andernfalls übermittelt er einen überarbeiteten Prompt als neuen Auftrag.
8. Zum Abschluss gibt er die ID der gespeicherten Geschichte, eine Kapitelzusammenfassung und den Status des Titelbilds aus.

Tool-Ergebnisse werden gespeichert, sobald sie abgeschlossen sind. Die nächste Modellanfrage erhält jedoch die gleichzeitig ausgeführten Tool-Ergebnisse in der ursprünglichen Reihenfolge der Tool-Aufrufe. Das API-Dokument sollte von voneinander abhängigen Schreibvorgängen im selben parallelen Batch abraten, wenn ein Aufruf eine von einem anderen zurückgegebene ID benötigt.

Schritt 5: AgentChat-Nachrichten korrekt zusammenführen

GET /api/agent/sessions/session_uuid/messages?after_id=msg_uuid&after_revision=6
Authorization: Bearer ac_live_AGENT_CHAT_KEY

Der StoryShelf-Client ersetzt eine Nachricht nur, wenn ihre Revision höher ist. Er kann Assistententext, eine kompakte Aktivität für einen Illustrationsauftrag und eine abschließende Bildvorschau darstellen. Fehlgeschlagene unvollständige Assistentennachrichten bleiben sichtbar, werden aber von AgentChat aus dem künftigen LLM-Kontext ausgeschlossen.

Wenn die Bildgenerierung das verbleibende Turn-Budget verbraucht, gibt AgentChat einen Zustand zurück, dessen next_action auf continue gesetzt ist. StoryShelf zeigt eine Schaltfläche „Weiter“ an und ruft POST /api/agent/sessions/session_uuid/continue auf. Der neue Lauf erhält ein frisches Turn-Budget und setzt anhand der dauerhaft gespeicherten Nachrichten fort.

Schritt 6: Die Geschichte aus der StoryShelf-Datenbank rendern

POST /stories, POST /chapters und PUT /cover haben bereits validierte Datensätze in StoryShelf geschrieben. Die Bibliotheksseite fragt die StoryShelf-Tabellen ab und zeigt den neuen Titel und das neue Cover an. Der Editor lädt die Kapitel anhand von story_id. Das Chat-Transkript wird nicht geparst, um die Geschichte zu rekonstruieren.

Dieses Design macht eine teilweise Fertigstellung sicher. Wenn der Cover-Auftrag fehlschlägt, sind die drei Kapitel weiterhin vorhanden. Der Benutzer kann dieselbe AgentChat-Sitzung fortsetzen und um ein neues Cover bitten, ohne die Geschichte erneut zu generieren.

Was vor dem Start getestet werden muss