配置与生命周期 API
配置 REST 参考基址为 https://api.hostanagent.com/v1。下表是公开配置资源的主要入口；字段、分页及响应结构以本站经过公开范围筛选的OpenAPI为准。MCP 提供相同配置服务的22 个工具。
| 操作 | 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 的核对不受草稿变更影响。版本指南。
输入窗口与工具结果
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 大小计量，包含转义与裁剪提示；大结果应分页、筛选字段或按需读取，见工具结果规则。完整回执不因该预算而拒收。
从旧配置迁移
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 配额字段仍兼容接收但不执行，与上表严格删除的三个字段不同；新接入无需提交这些累计配额。运行边界。
修改并验证的顺序：
- 读取当前 Agent revision、工具集版本及完整工具定义，删除旧字段。
- 用
update_toolset的upsert_tools提交该工具完整定义，保存新工具集版本；不要把它当作单字段补丁。 - 将新工具集关联到 Agent，按需修改
config.limits.max_context_tokens，校验并发布新 Agent 版本。配置写入仍使用稳定request_id与当前 revision。 - 用新 Agent 版本调用工具 dry-run，检查模型可见结果；再新建 Session 使用新配置。继续旧 Session 不会切换到新发布版本。
控制台对应“工具”和“我的 Agents”的高级设置。MCP 配置步骤、工具模拟预览、已发布 SDK 的类型边界。