Agent API（Responses）

复制本页的 curl 示例前，先选择 Cloud 区域。需要认证的调用必须使用与密钥同一区域的地址。下方示例都使用 MIROBODY_API_BASE：

export MIROBODY_API_BASE="https://api.mirobody.cn/v1"  # 中国区账户
# export MIROBODY_API_BASE="https://api.mirobody.ai/v1" # 全球区账户：改用这一行

SDK 示例中如果写有全球区的完整地址，中国区账户须换成对应的中国区地址。参阅区域。

端点

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 "$MIROBODY_API_BASE/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 "$MIROBODY_API_BASE/responses/resp_147e9b14..." \
  -H "Authorization: Bearer $MIROBODY_API_KEY"

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

删除存储的响应

curl -X DELETE "$MIROBODY_API_BASE/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 "$MIROBODY_API_BASE/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 模式：把这个端点变成裸推理后端。

​端点

​创建响应

​请求体

​响应对象

​用量口径

​获取存储的响应

​删除存储的响应

​状态模型

​严格校验

​错误

​另见

端点

创建响应

请求体

响应对象

用量口径

获取存储的响应

删除存储的响应

状态模型

严格校验

错误

另见