> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirobody.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent API（Responses）

> POST /v1/responses —— 兼容 OpenAI Responses 的智能体接口：客户端工具、存储的对话、previous_response_id 链式续聊。

## 端点

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

**Agent API** 是 Mirobody 兼容 [OpenAI Responses API](https://platform.openai.com/docs/api-reference/responses) 的接口 —— **在 Mirobody 上构建 agent 的推荐方式**。它具备 [Answers API](/zh/api-reference/chat) 的全部能力（基于 Subject 真实健康数据的 grounded 回答、服务端工具、推理），并新增：

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

由于它说的是 Responses 协议，**[openai-agents SDK](https://github.com/openai/openai-agents-python) 只需改 base URL 即可直接使用** —— 已实测：

```python theme={null}
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://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",
              model_settings=ModelSettings(extra_body={"user": "alice"}))
print(Runner.run_sync(agent, "How is my fasting glucose trending?").final_output)
```

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

```text theme={null}
https://mirobody-api.thetahealth.ai/v1
```

其数据为非生产数据、可能随时重置 —— 切勿写入真实终端用户数据。完整域名矩阵与上线状态见[区域](/zh/api-reference/regions/overview)。

## 创建响应

<CodeGroup>
  ```bash curl theme={null}
  curl https://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"
        }'
  ```

  ```python Python (OpenAI SDK) theme={null}
  from openai import OpenAI

  client = OpenAI(api_key="mb_live_...", base_url="https://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)
  ```
</CodeGroup>

### 请求体

| 字段                     | 类型               | 说明                                                                                                                                                                                                                                                                                                                                            |
| ---------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `model`                | string           | `mirobody-flash`（默认）或 `mirobody-expert`。详见[模型](/zh/api-reference/models)。                                                                                                                                                                                                                                                                     |
| `input`                | string \| array  | **必填。** 字符串（一个用户轮次）或 item 数组：`message` item（`{role, content}`），以及在续跑工具交接时的 `function_call` / `function_call_output` item。见 [Function calling](/zh/api-reference/function-calling)。                                                                                                                                                            |
| `instructions`         | string           | 本轮的系统级指令（作为 system 消息前置）。                                                                                                                                                                                                                                                                                                                     |
| `stream`               | bool             | `true` → 标准 `response.*` 事件的 SSE。见[流式传输](/zh/api-reference/streaming)。                                                                                                                                                                                                                                                                        |
| `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 嵌套形式)以及/或远程 **MCP** server(`{"type": "mcp", "server_label", "server_url", …}`——服务端执行)。最多 64 个;名称须匹配 `[a-zA-Z0-9_-]{1,64}` 且不得与内置工具重名。见 [Function calling](/zh/api-reference/function-calling) · [MCP servers](/zh/api-reference/mcp-servers)。 |
| `tool_choice`          | string \| object | `"auto"`（默认）/ `"none"` / 指名某个**客户端**工具。其它取值 → `400 unsupported_parameter`。                                                                                                                                                                                                                                                                    |
| `user`                 | string           | 租户隔离键 → 一个 Subject。                                                                                                                                                                                                                                                                                                                           |

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

### 响应对象

```jsonc theme={null}
{
  "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`](/zh/api-reference/streaming#服务端工具旁路通道) 呈现。`health_records` 与 `citations` 携带回答所用的证据，与 [Answers API](/zh/api-reference/chat#响应) 完全一致。

### 用量口径

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

## 获取存储的响应

```bash theme={null}
curl https://mirobody-api.thetahealth.ai/v1/responses/resp_147e9b14... \
  -H "Authorization: Bearer $MIROBODY_API_KEY"
```

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

## 删除存储的响应

```bash theme={null}
curl -X DELETE https://mirobody-api.thetahealth.ai/v1/responses/resp_147e9b14... \
  -H "Authorization: Bearer $MIROBODY_API_KEY"
```

```json theme={null}
{ "id": "resp_147e9b14...", "object": "response.deleted", "deleted": true }
```

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

## 状态模型

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

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

存储的对话（`store=true`）本身**不会**持久化任何健康数据；永久健康记录也不会让对话常驻。按需组合：例如 `store=false` + `retention=1h` 得到完全短暂的一次运行；`session_id` 绑定的响应 + `retention=session` 数据则得到"对话永续、工作数据随会话销毁"的形态。

完整细节 —— TTL、链式续聊语义、无状态回放，以及 `store=true` 供给的跨会话记忆 —— 见[状态与记忆](/zh/api-reference/state-and-memory)。

## 错误

标准[错误信封](/zh/api-reference/overview#错误格式)。此面特有情形：

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