如何使用现有API为你的SaaS添加AI代理

本指南将为一个名为 SupportFlow 的虚构 SaaS 实现完整的 AgentChat 集成。SupportFlow 已经提供了用于查找逾期发票、发送提醒以及添加账户备注的 API。我们将把这些 API 配置到 AgentChat 中，创建一个用户范围的聊天，启动一次异步代理运行，并从持久化消息和 SupportFlow 自己的数据库中呈现结果。

重要的架构边界是明确的：AgentChat 负责模型推理、工具选择、聊天历史记录和运行控制。SupportFlow 继续负责客户、发票、授权、验证以及最终的业务记录。API 文档将这两个系统连接起来。

无需将 SaaS 的每项功能都添加到代理运行时中。将少量核心业务操作作为 HTTP API 暴露出来，并将这些 API 契约配置到每个聊天中。

完成后的请求流程

SupportFlow 从控制面板创建一个 AgentChat API 密钥，并仅将其存储在后端。
其后端通过 POST /api/api-documents 注册 SupportFlow 操作。
当用户打开助手时，SupportFlow 会使用文档 UUID、LLM 配置 UUID 以及用于其 API 主机的只写用户凭据创建会话。
SupportFlow 将用户消息发送到 POST /api/agent/sessions/{id}/chat。
AgentChat 读取附加的合同，并使用其内置的 http_request 工具调用 SupportFlow。
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 执行它们。

代理在此次请求中执行的操作

通过 http_request 调用文档中记录的逾期发票端点。
读取结构化条目，并从用户请求的发票中选择最多三张。
将提醒加入队列。由同一个模型响应生成的独立调用可以并发执行。
在获得成功的提醒结果后，使用每个返回的发票和账户 ID 调用账户备注端点。
生成一条最终助理消息，列出已完成的操作以及每张发票的失败情况（如有）。

这就是响应设计至关重要的原因。模糊的“成功”结果无法为代理留下任何可以可靠关联到下一步操作的信息。结构化的 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 会使用全新的轮次预算和相同的持久化对话上下文启动另一次运行。

应提供哪些内容，以及不应提供哪些内容

提供代表稳定业务能力的 API，例如搜索、创建、更新、验证、发布或检查作业状态。
记录必填字段、约束条件、响应对象、错误含义、副作用以及顺序要求。
仅附加聊天体验所需的文档，而不是所有内部端点的文档。
将凭据保存在特定于主机的会话标头中，绝不要放在提示词或 API 文档内容中。
不要仅为了让代理更灵活，就暴露原始 SQL、不受限制的文件访问权限或通用内部代理。
对每个工具请求执行你自己的授权和验证，执行方式要与对其他客户端的处理完全一致。

无需扩展核心工具集，也能扩展能力范围的原因

RAG 产品可以配置搜索和引用端点。故事产品可以配置章节、图像生成和发布端点。编程产品可以配置工作区文件、检查和部署端点。AgentChat 仍然使用相同的四个核心工具。应用特定的操作以 API 文档的形式提供，因此新增能力只需更改配置，无需发布新的智能体运行时版本。

这就是 AgentChat 的核心模式：创建 API 文档，创建具有作用域限制的聊天会话，让智能体组合你的 HTTP 操作，消费持久化消息，并从你自己的应用数据库中渲染由此产生的记录。