常见 MCP 配置任务

这些步骤适用于已经连接并授予相应权限的客户端。每次写操作前先读现状，向用户说明将改变的 Agent、上下文配置或服务状态；完成后回读，报告实际 ID、revision 与版本。

创建并发布文本 Agent

用 list_models 查看模型是否开放、支持哪些思考强度，再用 get_model_pricing 了解价格与参考预留。它不是针对具体消息的报价。
list_agents 检查是否已有目标 Agent，避免误建重复对象。
用 create_agent 创建草稿。下面只展示形状；模型和上下文配置需按当前目录、工具 Schema 和用户意图填写；无需配置累计预算或输出额度。

{
  "data": {
    "request_id": "由客户端生成并保存的稳定请求号",
    "name": "任务整理助手",
    "description": "整理用户授权的任务资料",
    "config": {
      "system_prompt": "只根据用户提供的信息回答，不执行未授权业务操作。",
      "model": null
    },
    "publish": false
  }
}

读取新 Agent 的配置，选定真实平台模型后调用 validate_configuration。ready=true 时按 get_agent 返回的 revision 用 update_agent 提交 expected_revision 和 publish=true。回读 get_agent 与 list_agent_versions 核对新版本。没有可用模型时保留草稿。

更新工具集与 Agent

先 list_executor_bindings 和 list_toolsets 复用现有对象。需要新绑定才调用 create_executor_binding；create_toolset/update_toolset 只保存 Schema。工具集更新基于 base_version，每个 upsert_tools 项是该工具的完整定义；移除用 remove_tools。用 set_agent_toolset 关联新的固定版本，带 expected_revision 和新 request_id，再校验并按需发布。最后回读 Agent 的版本与工具集引用。配置成功不代表业务执行器已经连接。工具页。

调整上下文窗口或工具结果大小

Agent 的 config.limits.max_context_tokens 控制单次输入窗口，默认 256,000 Token，可设 1,024–1,000,000；Run 覆盖只能收紧，不能突破模型容量。每个外部工具的 max_result_context_bytes 控制执行结果的字节预算，默认 16,384，可设 1,024–32,768。两者单位和作用不同，不按比例换算。

先读取完整 Agent 和工具定义。修改工具时，在 update_toolset 的 data.upsert_tools 中保留其名称、Schema、绑定、权限与执行语义，只改变目标预算；每一项是完整定义。保存后将新工具集版本关联到 Agent，再校验、发布并回读固定版本。新建 Session 才使用新配置。MCP 不执行 dry-run；预览通过控制台或具备 runtime:read / configuration:read / tools:execute 其中一项权限的应用 Key 调用 REST。迁移步骤和结果预览。

不要提交 max_context_chars、max_result_bytes 或 max_result_tokens，服务端会拒绝旧字段。工具结果经常超过 32 KiB 时，应让产品增加分页、筛选或按需读取能力；提高整体 Token 窗口不能取消单工具裁剪。

比较、回滚或停用

list_agent_versions → get_agent_version → compare_agent_versions 先向用户展示差异。rollback_agent 重新校验并发布新版本；既有历史和草稿不改写。
copy_agent 创建新的独立草稿，不复制 Key、Session 或业务资产。
set_agent_state 设为 paused 会阻止所有版本的新 Run；设为 archived 也从默认列表隐藏。恢复归档后是否启用需显式处理。已接受 Run 不因状态切换自动终止。
get_agent_references 看引用后才考虑 request_agent_deletion。删除申请仅归档与记录，可撤回；D08 物理清理尚未实施。

响应丢失时重用原 request_id 与完全相同的正文核对。REVISION_CONFLICT 需要重新读配置，不能用旧 revision 覆盖。MCP 无 Run、余额或充值工具；需要对话时改走运行接入。