AgentChat
🇺🇸English 🇨🇳简体中文 🇭🇰繁體中文 🇯🇵日本語 🇰🇷한국어 🇫🇷Français 🇩🇪Deutsch 🇪🇸Español 🇮🇹Italiano
登入
← 所有文章
案例研究·11 分鐘閱讀

如何將故事創作代理加入 AI 寫作應用程式

一套完整的 API 工作流程：使用你自己的資料庫建立故事、產生插圖、儲存章節並呈現結果。

本案例研究將現有的 AI 故事 SaaS StoryShelf 連接到 AgentChat。使用者透過對話建立故事；代理透過 StoryShelf API 寫入結構化的故事和章節記錄，啟動插圖工作，檢查回傳的圖片 URL，並更新故事。接著，StoryShelf 讀取自身的資料庫，並在其一般的作品庫和編輯器中顯示結果。

重要的一點是，AgentChat不會變成故事資料庫，StoryShelf也不會將一段很長的助理回答解析成記錄。代理執行的是StoryShelf應用程式已經理解的同樣受控操作。

步驟1：公開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

每個建立回應都會返回穩定的ID。故事和章節寫入操作使用client_request_id實現冪等，因此重試不會建立重複項目。圖像工作是非同步的，並返回poll_after_seconds。已完成的圖像回應包含asset_id和image_url，絕不包含base64資料。

步驟2：配置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."
}

該文件包含一些無法僅從OpenAPI路徑列表中可靠推斷出的工作流程規則：保留ID、分開處理非同步回合、檢查圖像URL，以及不要隱式發布。

步驟3：建立使用者的故事工作階段

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 從後端建立此工作階段，並將傳回的工作階段 UUID 儲存在使用者對話旁邊。這個短期有效的標頭會將所有故事 API 的讀取和寫入限制為 user_88。它會在請求時注入，不會包含在 LLM 內容或 AgentChat API 回應中。

第 4 步：讓使用者透過聊天建立內容

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 儲存使用者訊息並回傳 processing。StoryShelf UI 不會讓聊天請求保持開啟，而是立即開始輪詢訊息。

具體的工具呼叫順序

  1. 代理規劃標題、前提、受眾、風格以及三部分大綱。
  2. 呼叫 POST /stories，並接收 story_id story_123。
  3. 透過個別的 API 呼叫分別寫入第一章、第二章和第三章，並保留每個 chapter_id。
  4. 建立與已儲存故事風格一致的影像提示詞，並呼叫 POST /image-jobs。
  5. 由於工作必須非同步完成，下一次模型回合會使用 poll_after_seconds 呼叫 sleep，之後在後續請求中輪詢 GET /image-jobs/job_7。
  6. 當回應包含 image_url 時，代理會呼叫 view_image，讓插圖以原生多模態輸入的形式進入上下文。
  7. 如果圖片與故事相符，代理會攜帶 asset_id 呼叫 PUT /stories/story_123/cover。如果不相符，則會將修改後的提示詞作為新工作提交。
  8. 最後返回已儲存的故事 ID、章節摘要和封面狀態。

工具結果會在完成後立即持久化，但下一次模型請求會按照原始工具呼叫順序接收並行執行的工具結果。API 文件應建議：當一個呼叫需要另一個呼叫返回的 ID 時，不要在同一個並行批次中執行相互依賴的寫入操作。

第 5 步：正確合併 AgentChat 訊息

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

StoryShelf 用戶端僅在 revision 增加時替換訊息。它可以呈現助理文字、精簡的插圖工作活動資訊，以及最終影像預覽。失敗的部分助理訊息仍會顯示，但 AgentChat 會將其排除在未來的 LLM 上下文之外。

如果圖像生成使用了剩餘的回合預算，AgentChat 會回傳 next_action 為 continue 的狀態。StoryShelf 會顯示「繼續」按鈕，並呼叫 POST /api/agent/sessions/session_uuid/continue。新的執行會獲得全新的回合預算，並從持久化訊息繼續執行。

第 6 步：從 StoryShelf 資料庫渲染故事

POST /stories、POST /chapters 和 PUT /cover 已經將經過驗證的記錄寫入 StoryShelf。資料庫頁面會查詢 StoryShelf 資料表，並顯示新的標題和封面。編輯器會根據 story_id 載入章節。系統不會解析聊天記錄來重建故事。

這種設計可以安全地處理部分完成的情況。如果封面工作失敗，三個章節仍然存在。使用者可以繼續使用同一個 AgentChat 工作階段，並要求產生新的封面，而無需重新產生故事。

上線前必須測試的內容

  • 使用相同的 client_request_id 重試建立故事和章節，並確認不會出現重複記錄。
  • 返回圖片工作失敗，並驗證代理程式保留故事內容並說明可復原的步驟。
  • 在圖片輪詢期間停止，然後繼續工作階段並完成封面。
  • 使用注入的權杖嘗試讀取其他使用者的故事 ID，並驗證 StoryShelf 返回 403 或「找不到」。
  • 返回無效的圖片 URL，並驗證代理程式回報工具錯誤，而不是將其嵌入為文字。
  • 每次完成變更後，從其自身資料庫重新整理 StoryShelf 內容庫。