Agent API（Responses）

端点

POST   /v1/responses                创建响应
GET    /v1/responses/{response_id}  获取存储的响应
DELETE /v1/responses/{response_id}  删除存储响应；若它是最后一个存活响应，再拆除其对话
Authorization: Bearer mb_live_*

Agent API 说的是 OpenAI Responses 协议：在 Mirobody 上构建 agent 的推荐方式。它具备 Answers API 的全部能力（基于 Subject 真实健康数据的有据可循的回答、服务端工具、推理），并新增：

• 客户端 function 工具：注入你自己的工具；模型通过 function_call output item 交接（见 Function calling）。
• 存储的对话：store 默认 true；用 previous_response_id 链式续聊，或用 session_id 绑定永续对话（见状态与记忆）。
• 标准 response.* 流式事件（见流式传输）。

由于它说的是这套协议，openai-agents SDK 只需改 base URL 即可：

from agents import Agent, ModelSettings, Runner, set_default_openai_client, set_tracing_disabled
from openai import AsyncOpenAI

set_default_openai_client(AsyncOpenAI(
    base_url="https://api.mirobody.ai/v1", api_key="mb_live_..."))
set_tracing_disabled(True)   # tracing 会请求 api.openai.com

agent = Agent(name="Health assistant", model="mirobody-flash",
              model_settings=ModelSettings(extra_body={"user": "alice"}))
print(Runner.run_sync(agent, "How is my fasting glucose trending?").final_output)

所有 /v1 接口共用一个 base URL，按你账户使用的集群选择：

https://api.mirobody.ai/v1   # 全球
https://api.mirobody.cn/v1   # 中国

以上是 Cloud 的集群。自部署不提供 /v1，它暴露的是自己的 /api/* 路由与一个 /mcp 端点，见自部署 Mirobody。

日本与欧盟集群正在筹备中，见区域。模型提供方与定价可能因区域不同，请从实际调用的集群读取 GET /v1/models。

创建响应

curl https://api.mirobody.ai/v1/responses \
  -H "Authorization: Bearer $MIROBODY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "mirobody-flash",
        "input": "How is my fasting glucose trending?",
        "user": "alice"
      }'

from openai import OpenAI

client = OpenAI(api_key="mb_live_...", base_url="https://api.mirobody.ai/v1")

resp = client.responses.create(
    model="mirobody-flash",
    input="How is my fasting glucose trending?",
    user="alice",
)
print(resp.output_text)

请求体

字段	类型	说明
model	string	mirobody-flash（默认）或 mirobody-expert。详见模型。
input	string | array	必填。 字符串（一个用户轮次）或 item 数组：message item（{role, content}），以及在续运行工具交接时的 function_call / function_call_output item。见 Function calling。
instructions	string	本轮的系统级指令（作为 system 消息前置）。
stream	bool	true → 标准 response.* 事件的 SSE。见流式传输。
store	bool	默认 true。 持久化响应 + 对话：30 天 TTL，绑定 session_id 时永久。启用 previous_response_id 与 GET /v1/responses/{id}。
previous_response_id	string	续接某个已存储响应的对话（服务端状态，无需重发历史）。id 未知、已过期或已删除时返回 404。
session_id	string	Mirobody 扩展。把本轮及后续轮次绑定到一个永续命名对话（永不自动过期）。应生成全局唯一、不含业务语义的 id（如 UUID），且不能跨 Subject 复用。
tools	array	客户端 function 工具（{"type": "function", "name", "description", "parameters"}，也接受 completions 嵌套形式）以及/或远程 MCP server（{"type": "mcp", "server_label", "server_url", …}，服务端执行）。最多 64 个；名称须匹配 [a-zA-Z0-9_-]{1,64} 且不得与内置工具重名。见 Function calling · MCP servers。
tool_choice	string | object	"auto"（默认）/ "none" / "required" / 指名某个客户端工具。"required" 与命名的保证适用于 backbone 模式；完整契约（含 400 情形）在那里。
mode	string	"agent"（默认，完整服务端 agent）或 "model"（backbone 模式，裸推理，无服务端工具/状态）。
builtin_tools	string | array	"auto"（默认）/ "none" / 内置工具名白名单数组。裁剪服务端领域工具，见 backbone 模式。
text.format	object	结构化输出（json_object / json_schema）。仅 backbone 模式；agent 模式下会返回 400。见结构化输出。
strict	bool	为 true（或头 X-Mirobody-Strict: 1）时，未知顶层参数以 400 unsupported_parameter 拒绝而非忽略。见严格校验。
user	string	租户隔离键 → 一个 Subject。

注意

user 字段是租户隔离键。 后端把 (你的账户, user) 映射为内部的数据主体（Subject），Subject 之间完全隔离：为每个终端用户传入其稳定 id，任何用户都看不到别人的数据。省略时回落到你账户的默认 Subject。Subject 对 Mirobody 网页应用和其他开发者均不可见。

该值在映射前会被归一化（去首尾空白 + 转小写），Alice 与 alice 解析为同一个 Subject。请传入稳定、规范的 id。

响应对象

{
  "id": "resp_147e9b14c172429a8b19da4be9489243",
  "object": "response",
  "created_at": 1783741077,
  "status": "completed",
  "model": "mirobody-flash",
  "output": [
    { "type": "reasoning", "id": "rs_0", "status": "completed",
      "summary": [{ "type": "summary_text", "text": "..." }] },
    { "type": "message", "id": "msg_0", "status": "completed", "role": "assistant",
      "content": [{ "type": "output_text", "text": "Your fasting glucose has trended down ..." }] }
  ],
  "output_text": "Your fasting glucose has trended down ...",
  "usage": {
    "input_tokens": 9,                                   // 只计你可见的输入
    "output_tokens": 5,
    "total_tokens": 14,
    "input_tokens_details": { "system_tokens": 10096, "cached_tokens": 0 },
    "output_tokens_details": { "reasoning_tokens": 0 },
    "billed_tokens": { "input": 20391, "output": 841, "total": 21232 }   // 实际计量的 token 总数
  },
  "tool_steps": [],                                      // Mirobody 扩展：服务端工具轨迹
  "health_records": [],                                  // Mirobody 扩展：{tool, data} 证据
  "citations": [],                                       // Mirobody 扩展：文献证据
  "previous_response_id": null,
  "store": true,
  "tools": [],
  "error": null,
  "metadata": {}
}

output 数组只包含标准 OpenAI item 类型：reasoning、message，以及（客户端工具交接时的）function_call。官方 SDK 可原样解析。

服务端内置工具的运行刻意不作为 output item 出现。 其轨迹位于顶层 tool_steps 扩展字段（{id, name, arguments, result}，与 Answers API 同形），SDK 会安全地忽略它。流式下则通过旁路事件 response.mirobody_tool_call 呈现。health_records 与 citations 携带回答所用的证据，与 Answers API 完全一致。

用量口径

usage.input_tokens 只报告你实际发送的输入；平台系统提示 / 工具 schema 的开销单列在 input_tokens_details.system_tokens。output_tokens_details.reasoning_tokens 报告 provider 的推理 token。计数为该 agent 轮次内所有模型调用之和。

usage.billed_tokens（{input, output, total}）就是你被计量的口径，Agent API 与 Answers API 都会返回。按模型目录的标准输入/输出单价计算可得到估算值；提示词缓存折扣可能使实际计量费用更低。

获取存储的响应

curl https://api.mirobody.ai/v1/responses/resp_147e9b14... \
  -H "Authorization: Bearer $MIROBODY_API_KEY"

返回存储的响应对象。仅 store=true 的响应可获取；已过期（30 天 TTL）或已删除的响应返回 404。

删除存储的响应

curl -X DELETE https://api.mirobody.ai/v1/responses/resp_147e9b14... \
  -H "Authorization: Bearer $MIROBODY_API_KEY"

{ "id": "resp_147e9b14...", "object": "response.deleted", "deleted": true }

若它是所在对话的最后一个存活响应，整段对话也会被一并拆除，包括其历史与对话衍生的记忆。这也就是存储对话的自助「被遗忘权」入口。

状态模型

store 与 retention 正交，一个管对话，一个管数据面：

开关	作用于	取值	管什么
store	POST /v1/responses	true（默认）/ false	响应对象 + 对话线程是否持久化：store=true 保留 30 天（绑定 session_id 则永久），从而支持 previous_response_id 链式续聊与 GET /v1/responses/{id}。store=false 则回复结束后什么都不留。
retention	POST /v1/data、POST /v1/files、POST /v1/standardize（store=true 时）	permanent（别名 persistent）/ 1d / 6h / 2h / 1h / session	你写入的健康记录 / 文件在 Subject 存储中的存活时长。时间粒度自动删除（硬上限 ≤ 24h）；session 把记录绑定到 session_id，DELETE /v1/sessions/{id} 可立即清除。

retention 管理显式的数据面写入，不管理存储对话。store=true 的对话还可能从内容中抽取出健康记录与持久记忆，这些记录用 DELETE /v1/data 删除，或直接删除该 Subject。store=false 的对话则不会产生任何此类数据。

完整细节（TTL、链式续聊语义、无状态回放，以及 store=true 供给的跨会话记忆）见状态与记忆。

严格校验

默认接口是宽松的（兼容优先），未知顶层参数会被忽略。在 body 里设 strict: true 或发送头 X-Mirobody-Strict: 1，它就会变成硬 400 unsupported_parameter，param 指向第一个出问题的键。两个接口（/v1/responses 与 /v1/chat/completions）都遵守它。集成联调期建议打开，尽早发现拼写错误与放错位置的字段。

curl https://api.mirobody.ai/v1/responses \
  -H "Authorization: Bearer $MIROBODY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Mirobody-Strict: 1" \
  -d '{"model":"mirobody-flash","input":"hi","bogus_param":1,"user":"alice"}'
# → 400 {"error":{"code":"unsupported_parameter","param":"bogus_param", ...}}

注意

reasoning（如 {"effort": "low" | "medium" | "high"}）已生效：effort 映射到底层模型的深度思考 / 推理预算。思考内容通过 response.reasoning_summary_text.* 事件流式返回，并落在非流式的 reasoning 输出项里；usage.output_tokens_details.reasoning_tokens 计入其 token。省略 reasoning 即为模型默认行为。无思考模式的模型会直接忽略（不报错）。

错误

标准错误信封。此面特有情形：

HTTP	何时
400	input 缺失/为空；tools 非法（名称非法、与内置重名、重复、超过 64、非法类型、MCP server 不可达）；不支持的 tool_choice（见契约）；agent 模式下的 text.format；mode:"model" 携带 previous_response_id/session_id/MCP 工具；未知的 builtin_tools 名字；strict 下的未知顶层参数；交接续运行格式错误（见 Function calling）
404	previous_response_id 或 response_id 未知 / 已过期 / 已删除
429	rate_limit_exceeded（按 key 限流）或 insufficient_quota（按账户月度上限），见限流与配额
502	上游 agent 错误：瞬态问题，退避重试即可。backbone 模式下 provider 错误会被分类（400 / 429 / 502），而非统一 502。

另见

• Function Calling：声明客户端工具与交接后的续运行。
• 状态与记忆：store、会话状态与跨会话记忆。
• 流式传输：response.* 事件序列。
• Backbone 模式：把这个端点变成裸推理后端。