<!-- 来源: https://hostanagent.com/docs/reference/configuration/ | 协议: 1.0 | 更新: 2026-09-30 -->

# 配置与生命周期 API

配置 REST 参考基址为 `https://api.hostanagent.com/v1`。下表是公开配置资源的主要入口；字段、分页及响应结构以本站经过公开范围筛选的[OpenAPI](/docs/reference/openapi.json)为准。MCP 提供相同配置服务的[22 个工具](/docs/mcp/tools/)。

| 操作 | REST 路径 | 关键约束 |
|---|---|---|
| 列表/创建 Agent | `GET/POST /configuration/agents` | 写入需稳定请求号，默认草稿 |
| 读取/修改 Agent | `GET/PATCH /configuration/agents/{agent_id}` | 修改携带 `expected_revision`；按字段局部更新 |
| 版本列表/指定版本 | `GET /configuration/agents/{agent_id}/versions`、`.../versions/{version_id}` | 历史版本不可变，列表使用游标 |
| 比较/复制/回滚 | `GET .../compare`、`POST .../copy`、`POST .../rollback` | 回滚重新发布新版本，复制新草稿 |
| 服务状态与删除申请 | `POST .../state`、`POST .../deletion-request`、`GET .../references` | 删除申请不物理清理 |
| 工具集与执行绑定 | `/configuration/toolsets`、`/configuration/bindings` | 工具集新版本需显式关联 Agent |
| 配置验证 | `POST /configuration/validate` | `valid` 与 `ready` 含义不同；余额仍在运行时检查 |

上表省略重复的 `/v1` 前缀；精确 HTTP 方法、路径参数和 JSON Schema 查 OpenAPI。读取与写入分别要求 `configuration:read`、`configuration:write`，账号/Agent 范围另外检查。旧 `/v1/agents` 和 `/v1/toolsets/{id}/versions` 的兼容入口也以同一服务校验发布配置与模型价格。

写请求重试复用相同 `request_id` 和正文。`REVISION_CONFLICT` 时先读最新状态、核对差异，再决定是否提交新的修改；同号更换正文属于幂等冲突。`ready=true` 仅说明配置可发布，不表示账号有余额。`state=paused` 或 `archived` 阻止所有版本新运行；已接受 Run 的核对不受草稿变更影响。[版本指南](/docs/console/versions-lifecycle/)。

## 输入窗口与工具结果

Agent 的 `config.limits` 仅保留输入 Token 窗口：`{"max_context_tokens":256000}`，可设 1,024–1,000,000。正常压缩以完整请求的 Token 用量为依据；实际窗口受模型输入容量、总容量和输出预留约束。Run 的 `limits.max_context_tokens` 只能收紧此窗口。

每个工具定义的 `max_result_context_bytes` 控制其结果首次进入执行上下文的 UTF-8 字节预算，默认 16,384（16 KiB），可设 1,024–32,768（1–32 KiB）。通过工具集配置 REST 或 MCP 的 `create_toolset` / `update_toolset` 修改，随后发布引用该工具集的 Agent 版本，新 Session 使用新配置。按 `result` 紧凑 JSON 的 UTF-8 大小计量，包含转义与裁剪提示；大结果应分页、筛选字段或按需读取，见[工具结果规则](/docs/reference/tools/)。完整回执不因该预算而拒收。

## 从旧配置迁移

2026-09-28 服务升级已经完成存量配置迁移，旧的工具 Token 配置统一改为默认 16 KiB，没有把 Token 数直接换算成字节。原有正式历史、完整回执和已提交执行历史保持；接入方仍需更新自己保存的请求模板、表单和配置生成代码。

| 已删除字段 | 接入方处理 |
|---|---|
| `limits.max_context_chars` | 删除；仅使用 `max_context_tokens` 配置整体窗口 |
| 工具 `max_result_bytes` | 删除原回执拒收额度；若要控制模型看到的结果，显式设置 `max_result_context_bytes` |
| 工具 `max_result_tokens` | 删除；重新选择 1–32 KiB 的字节预算，不直接复制数值 |

这些字段在 REST/MCP 入口都被拒绝，没有别名、自动换算或忽略逻辑。旧累计 Run 配额字段仍兼容接收但不执行，与上表严格删除的三个字段不同；新接入无需提交这些累计配额。[运行边界](/docs/reference/errors-limits/)。

修改并验证的顺序：

1. 读取当前 Agent revision、工具集版本及完整工具定义，删除旧字段。
2. 用 `update_toolset` 的 `upsert_tools` 提交该工具完整定义，保存新工具集版本；不要把它当作单字段补丁。
3. 将新工具集关联到 Agent，按需修改 `config.limits.max_context_tokens`，校验并发布新 Agent 版本。配置写入仍使用稳定 `request_id` 与当前 revision。
4. 用新 Agent 版本调用工具 dry-run，检查模型可见结果；再新建 Session 使用新配置。继续旧 Session 不会切换到新发布版本。

控制台对应“工具”和“我的 Agents”的高级设置。[MCP 配置步骤](/docs/mcp/recipes/)、[工具模拟预览](/docs/reference/tools/)、[已发布 SDK 的类型边界](/docs/releases/compatibility/)。