Cómo añadir un agente de creación de historias a una aplicación de escritura con IA

Este estudio de caso conecta un SaaS de historias con IA ya existente, llamado StoryShelf, con AgentChat. Un usuario crea una historia mediante una conversación; el agente escribe registros estructurados de la historia y los capítulos a través de las API de StoryShelf, inicia trabajos de ilustración, inspecciona las URL de imagen devueltas y actualiza la historia. Después, StoryShelf lee su propia base de datos y muestra el resultado en su biblioteca y editor habituales.

El detalle importante es que AgentChat no se convierte en la base de datos de historias y StoryShelf no analiza una respuesta larga del asistente para convertirla en registros. El agente realiza las mismas operaciones controladas que la aplicación StoryShelf ya entiende.

Paso 1: exponer el paquete de capacidades de 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

Cada respuesta de creación devuelve identificadores estables. Las escrituras de historias y capítulos son idempotentes mediante client_request_id, por lo que un reintento no crea duplicados. Los trabajos de imágenes son asíncronos y devuelven poll_after_seconds. La respuesta de una imagen completada contiene asset_id e image_url, nunca datos en base64.

Paso 2: aprovisionar el documento de 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."
}

El documento contiene reglas de flujo de trabajo que no se pueden inferir de forma fiable a partir de una lista de rutas de OpenAPI: conservar los identificadores, separar las operaciones asíncronas, inspeccionar las URL de las imágenes y no publicar implícitamente.

Paso 3: crear la sesión de historia del usuario

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 esta sesión desde su backend y almacena el UUID de sesión devuelto junto a la conversación del usuario. El encabezado de corta duración limita todas las lecturas y escrituras de la API de historias a user_88. Se inyecta en el momento de la solicitud y no se incluye en el contexto del LLM ni en las respuestas de la API de AgentChat.

Paso 4: permitir que el usuario cree contenido mediante el 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 almacena el mensaje del usuario y devuelve el estado «processing». La interfaz de StoryShelf comienza a consultar los mensajes de inmediato en lugar de mantener abierta la solicitud de chat.

La secuencia concreta de llamadas a herramientas

1. El agente planifica el título, la premisa, la audiencia, el estilo y un esquema de tres partes.
2. Llama a POST /stories y recibe story_id story_123.
3. Escribe los capítulos uno, dos y tres mediante llamadas independientes a la API y conserva cada chapter_id.
4. Crea un prompt de imagen coherente con el estilo guardado de la historia y llama a POST /image-jobs.
5. Como el trabajo debe completarse de forma asíncrona, el siguiente turno del modelo llama a sleep usando poll_after_seconds; después, una solicitud posterior consulta GET /image-jobs/job_7.
6. Cuando la respuesta contiene image_url, el agente llama a view_image para que la ilustración entre en el contexto como entrada multimodal nativa.
7. Si la imagen coincide con la historia, llama a PUT /stories/story_123/cover con asset_id. Si no, envía un prompt revisado como un nuevo trabajo.
8. Finaliza con el ID de la historia guardada, el resumen del capítulo y el estado de la portada.

Los resultados de las herramientas se guardan a medida que se completan, pero la siguiente solicitud al modelo recibe los resultados de las herramientas ejecutadas simultáneamente en el orden original de las llamadas a herramientas. El documento de la API debería desaconsejar las escrituras dependientes en el mismo lote paralelo cuando una llamada necesita un ID devuelto por otra.

Paso 5: combinar correctamente los mensajes de AgentChat

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

El cliente de StoryShelf reemplaza un mensaje solo cuando aumenta su revisión. Puede mostrar texto del asistente, una actividad compacta de trabajo de ilustración y una vista previa final de la imagen. Los mensajes parciales del asistente que hayan fallado permanecen visibles, pero AgentChat los excluye del contexto futuro del LLM.

Si la generación de imágenes utiliza el presupuesto de turnos restante, AgentChat devuelve un estado cuyo next_action es continue. StoryShelf muestra un botón «Continuar» y llama a POST /api/agent/sessions/session_uuid/continue. La nueva ejecución recibe un presupuesto de turnos renovado y continúa a partir de los mensajes persistentes.

Paso 6: renderizar la historia desde la base de datos de StoryShelf

POST /stories, POST /chapters y PUT /cover ya han escrito registros validados en StoryShelf. La página de la biblioteca consulta las tablas de StoryShelf y muestra el nuevo título y la portada. El editor carga los capítulos mediante story_id. La transcripción del chat no se analiza para reconstruir la historia.

Este diseño hace segura la finalización parcial. Si falla la tarea de la portada, los tres capítulos siguen existiendo. El usuario puede continuar la misma sesión de AgentChat y solicitar una nueva portada sin volver a generar la historia.

Qué debe probarse antes del lanzamiento