Come aggiungere un agente per la creazione di storie a un’app di scrittura con IA

Questo caso di studio collega ad AgentChat un SaaS di storie basato sull’IA già esistente, chiamato StoryShelf. Un utente crea una storia tramite una conversazione; l’agente scrive record strutturati della storia e dei capitoli tramite le API di StoryShelf, avvia processi di illustrazione, esamina gli URL delle immagini restituiti e aggiorna la storia. StoryShelf legge quindi il proprio database e visualizza il risultato nella sua normale libreria e nel suo editor.

Il dettaglio importante è che AgentChat non diventa il database delle storie e StoryShelf non analizza una lunga risposta dell’assistente per trasformarla in record. L’agente esegue le stesse operazioni controllate che l’applicazione StoryShelf già comprende.

Passaggio 1: esporre il pacchetto di funzionalità di StoryShelf

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

Ogni risposta di creazione restituisce ID stabili. Le scritture di storie e capitoli sono idempotenti tramite client_request_id, quindi un nuovo tentativo non crea duplicati. I processi delle immagini sono asincroni e restituiscono poll_after_seconds. La risposta relativa a un’immagine completata contiene asset_id e image_url, mai dati in base64.

Passaggio 2: predisporre il documento StoryShelf

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."
}

Il documento contiene regole del flusso di lavoro che non possono essere dedotte in modo affidabile da un semplice elenco di percorsi OpenAPI: preservare gli ID, separare le operazioni asincrone, controllare gli URL delle immagini e non pubblicare implicitamente.

Passaggio 3: creare la sessione della storia dell’utente

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 crea questa sessione dal proprio backend e memorizza l’UUID della sessione restituito accanto alla conversazione dell’utente. L’header a breve durata limita tutte le letture e scritture dell’API delle storie a user_88. Viene iniettato al momento della richiesta e non è incluso nel contesto dell’LLM né nelle risposte dell’API AgentChat.

Passaggio 4: consentire all’utente di creare tramite la 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 memorizza il messaggio dell’utente e restituisce lo stato «processing». L’interfaccia di StoryShelf inizia immediatamente a eseguire il polling dei messaggi invece di mantenere aperta la richiesta di chat.

La sequenza concreta delle chiamate agli strumenti

1. L’agente pianifica il titolo, la premessa, il pubblico, lo stile e una scaletta in tre parti.
2. Chiama POST /stories e riceve story_id story_123.
3. Scrive i capitoli uno, due e tre tramite chiamate API separate e conserva ogni chapter_id.
4. Crea un prompt per l’immagine coerente con lo stile della storia salvato e chiama POST /image-jobs.
5. Poiché il job deve essere completato in modo asincrono, il turno successivo del modello chiama sleep usando poll_after_seconds; in seguito, una richiesta successiva esegue il polling di GET /image-jobs/job_7.
6. Quando la risposta contiene image_url, l’agente chiama view_image affinché l’illustrazione entri nel contesto come input multimodale nativo.
7. Se l’immagine corrisponde alla storia, chiama PUT /stories/story_123/cover con asset_id. In caso contrario, invia un prompt modificato come nuovo lavoro.
8. Conclude fornendo l’ID della storia salvata, il riepilogo del capitolo e lo stato della copertina.

I risultati degli strumenti vengono resi persistenti man mano che vengono completati, ma la richiesta successiva al modello riceve i risultati degli strumenti eseguiti simultaneamente nell’ordine originale delle chiamate agli strumenti. Il documento dell’API dovrebbe sconsigliare le scritture dipendenti nello stesso batch parallelo quando una chiamata necessita di un ID restituito da un’altra.

Passaggio 5: unire correttamente i messaggi di AgentChat

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

Il client StoryShelf sostituisce un messaggio solo quando la sua revisione aumenta. Può visualizzare il testo dell’assistente, un’attività compatta relativa a un lavoro di illustrazione e un’anteprima finale dell’immagine. I messaggi parziali dell’assistente che hanno avuto esito negativo rimangono visibili, ma AgentChat li esclude dal contesto futuro dell’LLM.

Se la generazione delle immagini utilizza il budget di turni rimanente, AgentChat restituisce uno stato il cui next_action è impostato su continue. StoryShelf mostra un pulsante «Continua» e chiama POST /api/agent/sessions/session_uuid/continue. La nuova esecuzione riceve un nuovo budget di turni e prosegue dai messaggi persistenti.

Passaggio 6: eseguire il rendering della storia dal database di StoryShelf

POST /stories, POST /chapters e PUT /cover hanno già scritto record convalidati in StoryShelf. La pagina della libreria interroga le tabelle di StoryShelf e mostra il nuovo titolo e la nuova copertina. L’editor carica i capitoli tramite story_id. La trascrizione della chat non viene analizzata per ricostruire la storia.

Questo design rende sicuro il completamento parziale. Se il processo di creazione della copertina non riesce, i tre capitoli continuano a essere disponibili. L’utente può continuare la stessa sessione AgentChat e chiedere una nuova copertina senza generare nuovamente la storia.

Cosa deve essere testato prima del lancio