Agent API（Responses）

端点

POST   /v1/responses                创建响应
GET    /v1/responses/{response_id}  获取存储的响应
DELETE /v1/responses/{response_id}  删除存储的响应（连同其对话）
Authorization: Bearer mb_live_*

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

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

由于它说的是 Responses 协议，openai-agents SDK 只需改 base URL 即可直接使用 —— 已实测：

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

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

agent = Agent(name="Health assistant", model="mirobody-flash")
print(Runner.run_sync(agent, "How is my fasting glucose trending?").final_output)

当前可用的接入环境是全球 test 集群：

https://test-mirobody-api.thetahealth.ai/v1

其数据为非生产数据、可能随时重置 —— 切勿写入真实终端用户数据。完整域名矩阵与上线状态见区域。

创建响应

curl https://test-mirobody-api.thetahealth.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://test-mirobody-api.thetahealth.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 扩展。把本轮及后续轮次绑定到一个永续命名对话（永不自动过期）。
`tools`	array	客户端 function 工具（`{"type": "function", "name", "description", "parameters"}`；completions 嵌套形式也接受）。最多 64 个；名称需匹配 `[a-zA-Z0-9_-]{1,64}` 且不得与内置工具重名。见 Function calling。
`tool_choice`	string \| object	`"auto"`（默认）/ `"none"` / 指名某个客户端工具。其它取值 → `400 unsupported_parameter`。
`user`	string	租户隔离键 → 一个 Subject。

user 字段是租户隔离键。 后端把 (你的账户, user) 映射为内部的数据主体(Subject)；你传入的每个 user 彼此完全隔离。为每个终端用户传入其稳定 id，数据就绝不会串。省略时回落到你账户的默认 Subject。Subject 对 Mirobody 消费端 App 和其他开发者均不可见。

响应对象

{
  "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 }
  },
  "tool_steps": [],                                      // Mirobody 扩展：服务端工具轨迹
  "health_records": [],                                  // Mirobody 扩展：{tool, data} 证据
  "citations": [],                                       // Mirobody 扩展：文献证据
  "previous_response_id": null,
  "store": false,
  "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 统计思考 token。计数为该 agent 轮次内所有模型调用之和。

获取存储的响应

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

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

删除存储的响应

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

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

删除该存储的响应。若它是所在对话的最后一个存活响应，整段对话也会被一并拆除 —— 会话投影、agent 线程状态与对话衍生的记忆。这是存储对话的自助”被遗忘权”入口。

状态模型

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/extract`（`store=true` 时）	`permanent`（别名 `persistent`）/ `1d` / `6h` / `2h` / `1h` / `session`	你写入的健康记录 / 文件在 Subject 存储中的存活时长。时间粒度自动删除（硬上限 ≤ 24h）；`session` 把记录绑定到 `session_id`，`DELETE /v1/sessions/{id}` 可立即清除。

存储的对话（store=true）本身不会持久化任何健康数据；永久健康记录也不会让对话常驻。按需组合：例如 store=false + retention=1h 得到完全短暂的一次运行；session_id 绑定的响应 + retention=session 数据则得到”对话永续、工作数据随会话销毁”的形态。完整细节 —— TTL、链式续聊语义、无状态回放，以及 store=true 供给的跨会话记忆 —— 见状态与记忆。

错误

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

HTTP	何时
`400`	`input` 缺失/为空；`tools` 非法（名称非法、与内置重名、重复、超过 64、非 function 类型）；不支持的 `tool_choice`；交接续跑格式错误（见 Function calling）
`404`	`previous_response_id` 或 `response_id` 未知 / 已过期 / 已删除
`502`	上游 agent 错误 —— 瞬态；退避重试

​端点

​创建响应

​请求体

​响应对象

​用量口径

​获取存储的响应

​删除存储的响应

​状态模型

​错误

端点

创建响应

请求体

响应对象

用量口径

获取存储的响应

删除存储的响应

状态模型

错误