如何使用現有的API為你的SaaS新增AI代理

本指南將為一個名為 SupportFlow 的虛構 SaaS 實作完整的 AgentChat 整合。SupportFlow 已經提供用於尋找逾期發票、傳送提醒以及新增帳戶備註的 API。我們將把這些 API 配置到 AgentChat 中，建立一個使用者範圍的聊天，啟動一次非同步代理程式執行，並從持久化訊息和 SupportFlow 自有的資料庫中呈現結果。

重要的架構邊界是明確的：AgentChat 負責模型推理、工具選擇、聊天記錄和執行控制。SupportFlow 繼續負責客戶、發票、授權、驗證以及最終的業務記錄。API 文件將這兩個系統連接起來。

不需要將 SaaS 的每項功能都新增至代理程式執行環境。將少量核心業務操作公開為 HTTP API，並將這些 API 契約配置到每個聊天中。

完成後的請求流程

1. SupportFlow 從控制面板建立一個 AgentChat API 金鑰，並且只將其儲存在後端。
2. 其後端透過 POST /api/api-documents 註冊 SupportFlow 作業。
3. 當使用者開啟助理時，SupportFlow 會使用文件 UUID、LLM 設定 UUID，以及用於其 API 主機的唯寫使用者憑證建立工作階段。
4. SupportFlow 將使用者訊息傳送至 POST /api/agent/sessions/{id}/chat。
5. AgentChat 讀取附加的合約，並使用其內建的 http_request 工具呼叫 SupportFlow。
6. SupportFlow 輪詢 AgentChat 訊息，而其一般 UI 則從 SupportFlow 資料庫讀取發票和備註。

步驟 1：公開範圍明確的業務作業

代理程式不需要存取資料庫，也不需要一個龐大的單一內部 API。在此工作流程中，SupportFlow 確切公開三個支援租戶識別的端點：

GET /v1/invoices?status=overdue&limit=3
→ { "items": [{ "invoice_id": "inv_72", "account_id": "acct_9", "amount": 480, "currency": "USD", "due_at": "2026-08-01" }] }

POST /v1/reminders
{ "invoice_id": "inv_72", "tone": "friendly" }
→ { "reminder_id": "rem_31", "status": "queued" }

POST /v1/accounts/acct_9/notes
{ "body": "Friendly reminder queued for overdue invoice inv_72." }
→ { "note_id": "note_55", "created_at": "2026-08-23T09:30:00Z" }

每個端點都會驗證呼叫者的身分，從憑證推導出租戶，並對每項資料庫操作套用篩選條件。一次呼叫所傳回的 ID 可安全地作為下一次呼叫的輸入。模型永遠不會接收到資料庫密碼或不受限制的查詢介面。

步驟 2：建立一次模型設定

每個 AgentChat 工作階段都需要一項由使用者擁有的 LLM 設定。SupportFlow 可以透過儀表板或 API 建立設定，並保留傳回的 UUID。

POST $AGENTCHAT_SITE_URL/api/llm-config
Authorization: Bearer ac_live_AGENTCHAT_KEY
Content-Type: application/json

{
  "name": "Support production model",
  "api_url": "https://llm-provider.example.com/v1/chat/completions",
  "api_key": "provider_secret",
  "model": "provider-model-name",
  "max_context_length": 128000,
  "max_output_tokens": 8192,
  "temperature": 0.2,
  "disable_reasoning": false
}

回應會封裝為 success 和 data。請將 data.id 儲存為建立聊天時使用的 llm_config_id。AgentChat 在讀取設定時會遮罩提供者金鑰。

步驟 3：佈建 SupportFlow API 文件

這就是外掛機制。該文件包含操作指示、確切的輸入、確切的輸出以及執行順序規則，而不是行銷文案，也不是會迫使代理猜測的連結。

POST $AGENTCHAT_SITE_URL/api/api-documents
Authorization: Bearer ac_live_AGENTCHAT_KEY
Content-Type: application/json

{
  "title": "SupportFlow Invoice Actions",
  "description": "Find overdue invoices, queue reminders, and record account notes.",
  "content": "# SupportFlow Invoice Actions\nBase URL: https://support.example.com/v1\n\nGET /invoices?status=overdue&limit=3 returns items with invoice_id, account_id, amount, currency, and due_at. Use only when the user requests invoice lookup.\n\nPOST /reminders body: invoice_id required; tone is friendly or firm. Response: reminder_id and status. Never send more reminders than the user requested.\n\nPOST /accounts/{account_id}/notes body: body required. Call only after the reminder request succeeds. Include the invoice ID and reminder status in the note.\n\nIf any write returns 401 or 403, stop writing and explain that the session credential needs access. Do not retry a permission denial."
}

AgentChat 會在 data 中回傳包含其 UUID 的新文件。請將該 UUID 保存在 SupportFlow 的整合設定中。之後更新此文件會改變後續聊天回合所使用的指示，因為工作階段附加的是該文件，而不是複製它。

步驟 4：為目前的 SupportFlow 使用者建立聊天

POST $AGENTCHAT_SITE_URL/api/agent/sessions
Authorization: Bearer ac_live_AGENTCHAT_KEY
Content-Type: application/json

{
  "title": "Invoice assistant for user_42",
  "llm_config_id": "llm_config_uuid",
  "api_document_ids": ["supportflow_document_uuid"],
  "system_prompt": "Act only on the user’s explicit request. Summarize every write with the affected invoice and account IDs.",
  "compact_threshold_percent": 80,
  "max_turns": 12,
  "tool_timeout_seconds": 120,
  "tool_result_max_chars": 10000,
  "host_headers": [
    { "host": "support.example.com", "header_key": "Authorization", "header_value": "Bearer short_lived_user_42_token" },
    { "host": "support.example.com", "header_key": "X-Workspace-ID", "header_value": "workspace_7" }
  ]
}

標頭值是唯寫的。AgentChat 會為此工作階段儲存這些標頭，僅在 http_request 的目標主機與之相符時才注入這些標頭，並且不會將其值公開給模型或 API 回應。第二個 SupportFlow 使用者會獲得一個不同的工作階段，該工作階段使用相同的文件 UUID，但標頭不同。

步驟 5：開始非同步執行

POST $AGENTCHAT_SITE_URL/api/agent/sessions/session_uuid/chat
Authorization: Bearer ac_live_AGENTCHAT_KEY
Content-Type: application/json

{ "message": "Find my three most overdue invoices, send each a friendly reminder, and add a note to each account." }

→ { "success": true, "data": { "session_id": "session_uuid", "state": "processing" } }

AgentChat 會立即返回，並在背景中繼續執行。代理會收到隨附的 SupportFlow 文件，以及恰好四個內建工具：get_api_document、http_request、sleep 和 view_image。SupportFlow 的功能並未編譯到這些工具中；代理會從已提供的 API 合約中學習這些功能，並透過 http_request 執行它們。

代理在此次請求中執行的操作

1. 透過 http_request 呼叫文件中記錄的逾期發票端點。
2. 讀取結構化項目，並從使用者要求的發票中選取最多三張。
3. 將提醒加入佇列。由同一個模型回應產生的獨立呼叫可以並行執行。
4. 在取得成功的提醒結果後，使用每個返回的發票和帳戶 ID 呼叫帳戶備註端點。
5. 產生一則最終助理訊息，列出已完成的操作以及每張發票的失敗情況（如有）。

這就是回應設計至關重要的原因。模糊的「成功」結果無法為代理留下任何可以可靠關聯到下一步操作的資訊。結構化的 ID 和狀態讓推理迴圈能夠將多個一般 API 組合成一個使用者結果。

第 6 步：輪詢持久化訊息，而不是 LLM 串流

GET $AGENTCHAT_SITE_URL/api/agent/sessions/session_uuid/messages?after_id=&after_revision=0
Authorization: Bearer ac_live_AGENTCHAT_KEY

→ {
  "success": true,
  "data": {
    "messages": [{ "id": "message_uuid", "role": "assistant", "content": "...", "stream_status": "streaming", "revision": 4 }],
    "last_id": "message_uuid",
    "last_revision": 4,
    "is_processing": true,
    "total_tokens": 2840
  }
}

SupportFlow 從其後端或代理用戶端每秒輪詢一次，按訊息 ID 合併各列，並且只有在 revision 增大時才替換內容。AgentChat 的資料庫是對話輸出的事實來源。對於發票、提醒和備註，SupportFlow 的資料庫仍是事實來源。

當 is_processing 變為 false 時，SupportFlow 可以重新整理其發票和帳戶查詢。隨後，一般產品 UI 會顯示透過其自身 API 建立的提醒和備註；它不需要解析助理的文字來重建業務狀態。

執行控制與故障復原

GET  /api/agent/sessions/session_uuid/state
POST /api/agent/sessions/session_uuid/stop
POST /api/agent/sessions/session_uuid/continue

state 端點會回報處理是否處於作用中狀態，以及下一個動作是否為 continue。Stop 要求會取消正在執行的工作。如果可復原的失敗或最大回合數限制導致工作暫停，continue 會使用全新的回合預算和相同的持久化對話內容啟動另一次執行。

應提供哪些內容，以及不應提供哪些內容

無需擴充核心工具集，也能擴展能力範圍的原因

RAG 產品可以配置搜尋和引用端點。故事產品可以配置章節、圖像生成和發布端點。程式設計產品可以配置工作區檔案、檢查和部署端點。AgentChat 仍然使用相同的四個核心工具。應用程式特定的操作會以 API 文件的形式提供，因此新增能力只需變更配置，無需發布新的代理執行階段版本。

這就是 AgentChat 的核心模式：建立 API 文件，建立具有限定範圍的聊天工作階段，讓代理組合你的 HTTP 操作，消費持久化訊息，並從你自己的應用程式資料庫中呈現由此產生的記錄。