Agent API

POST /v1/agent 是平台的核心端点:发一段文本(可带图),拿到一条 SSE 流式回复。鉴权用 Bearer API key(见认证)。

请求

code

POST /v1/agent
Authorization: Bearer sk-meow-…
Content-Type: application/json

请求体字段(逐个)

字段	类型	必填	说明
`text`	string	是	用户消息。空白串会被拒(400「text 不能为空」)
`session_id`	string	否	会话标识,决定多轮记忆落在哪个会话。缺省 `"anon"`(本租户共享一个匿名会话,建议总是传)。仅用于会话寻址,租户间同名互不相通
`persona`	string	否	直传的人格提示(system prompt),仅本次请求生效;缺省用默认人格「喵喵」
`persona_id`	string	否	人格库引用:用控制台建好的人格 id。查得到则覆盖 `persona`;查不到静默回落默认(不报错)。只查你自己租户的人格
`images`	string[]	否	图片列表:`https://…` URL 或 `data:image/…;base64,…`。空数组 = 纯文本
`kb`	boolean	否	知识库检索注入开关(缺省 `true`)。本租户有文档即自动检索引用(无文档零开销);`false` = 本轮显式关。详见知识库

模型 / 思考开关 / 温度不在请求体里传——它们是每租户配置,在控制台「模型设置」里改,见控制台指南。

key 决定 App 身份

用 App 级 key(从某个应用签发,见应用)调本端点时,对话行为即该 App 的配置:提示词按 app.system_prompt > app.persona_id→人格库 > 请求体 persona_id/persona > 租户默认人格 > 默认喵喵 解析(App 显式配置 > 请求级参数——给 App 配了提示词后,请求体里的 persona/persona_id 覆盖不掉它);模型/思考/温度逐字段回落 App > 租户设置 > 平台默认;App 关了 kb_enabled 则本轮不做知识库注入(与 kb:false 同效);tools_enabled 白名单限定可用工具。App 归属由 key 决定,请求体无法指定或切换 App(防串扰)。租户通用 key(非 App 签发)行为与本页其余描述完全一致,不受 App 特性影响。

响应(成功)

200 OK,Content-Type: text/event-stream(另带 Cache-Control: no-cache、X-Accel-Buffering: no)。

响应(失败)

码	含义
400	请求体不是合法 JSON(`bad request body`)或 `text` 为空
401	key 缺失 / 无效 / 已撤销(统一「未授权」,不区分原因)
429	限流,带 `Retry-After` 头(秒)

注意:HTTP 200 之后的运行期错误(如上游过载重试耗尽)不再改状态码,而是走流内的 error 事件。

SSE 事件契约(逐个)

帧格式固定为:

code

event: <type>
data: {"type":"<type>", …}

关键解析纪律:type 同时出现在 event: 行和 data JSON 里,请按 data 内的 type 字段分发——event: 行只是标准 SSE 装饰。

type	data 字段	触发时机	客户端怎么用
`kb_refs`	`refs`(`[{doc_id,title,seq,score}]`)	本轮命中知识库注入时,先于一切 llm 事件(没命中则没有这帧)	做「引用来源」UI。additive 新事件,老客户端按未知 type 忽略即可。见知识库
`provider_fallback`	`from`(恒 `"byo"`)、`reason`(脱敏分类词:`retry_exhausted`/`upstream_4xx`/`upstream_5xx`/`channel_unavailable`/`provider_error`)	租户自带通道终败、平台通道接管重跑本轮时,先于重跑的一切 llm 事件(没配 BYO / BYO 成功则没有这帧)	清空本轮已渲染的增量(其后的 `llm_delta` 流从头重来),可提示「已切换平台通道」。additive 新事件,老客户端忽略即可。见自带模型通道
`llm_delta`	`text`(string)	模型每吐一段文本	逐段拼接做打字机效果
`tool_call`	`name`(string)	模型决定调某工具	显示「正在搜索…」之类。只带工具名,绝无参数(隐私纪律)
`tool_result`	`name`(string)、`ok`(bool)	该工具执行完	显示成败。绝无结果内容
`stats`	`iterations`(number)、`channel`(string,additive:`"byo"`/`"platform"`/`"platform_fallback"`)	一轮成功收尾前	`iterations`:`1`=没调工具直答;`2`=调了一轮工具再答,以此类推。`channel`:本轮实际走的通道(`platform_fallback`=BYO 失败后由平台通道重跑),账单可解释
`llm_end`	`reply`(string)	一轮正常结束	权威全文,以它定稿(弥补 delta 可能的客户端侧丢失)
`error`	`message`(string)	带内错误	直接展示;`message` 是友好话术,技术细节只在服务端日志

事件顺序

成功:[kb_refs(仅命中时)] → [provider_fallback(仅 BYO 回落时,其前可能已有失败通道流出的 llm_delta,应丢弃)] → llm_delta* 与(tool_call → tool_result)按工具循环交错 → stats → llm_end(极少数情况其后还有一条 error,表示历史存回失败);
失败:已发出的 llm_delta… → error(没有 stats / llm_end,该轮历史不会存回);
流结束:连接自然关闭,没有显式终止事件——以 llm_end(或 error)为一轮的语义终点。

内置工具

模型按需要自行决定是否调用,无需任何配置:

工具	作用
`web_search`	联网搜索实时信息
`get_time`	取当前时间 / 星期(治报时幻觉)
`calculator`	精确算术(治算术幻觉)

完整示例

bash

curl -N "$BASE/v1/agent" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "帮我算 (111+222)*3,再说现在几点",
    "session_id": "demo-1",
    "persona_id": "你的人格id(可选)"
  }'