# 单个工具配置、工具集与执行诊断 “工具”页把配置与执行分开：执行绑定登记 browser、desktop 或 backend 的位置，工具集版本定义名称和输入 Schema，Agent 发布版本引用固定工具集。产品执行器仍需单独连接、授权并处理业务。 ## 配置顺序 1. 点击“注册执行绑定”，为真实接入位置命名。 2. 点击“添加工具”，选择已有工具集或填写新工具集标识，逐项配置工具名称、说明、执行绑定和输入参数。常用工具不需要编写整组 JSON。 3. 在 Agent 配置中明确选择新工具集版本，再发布 Agent。修改工具集不会自动改变历史 Agent 版本。 4. 产品按[ToolRunner 指南](/docs/integration/tool-runner/)接入执行器，并逐次检查 Subject、Agent、资源权限与操作确认。 也可以先“新建工具集”，再逐个添加工具。每组最多 64 个工具；工具名称在组内唯一，以字母开头，可包含字母、数字、下划线、点和短横线，最长 64 个字符。名称与“更多执行设置”中的工具版本须匹配产品执行器声明的 handler。 ## 单个工具的配置 | 配置 | 用途 | |---|---| | 工具名称与说明 | 执行器按名称找到处理器；Agent 根据说明判断何时调用及预期结果 | | 输入参数 | 逐项填写参数名、文本/整数/数字/布尔类型、说明和是否必填；可设置是否允许未列出的字段 | | 返回结果约束 | 可选。开启后逐项定义返回字段，或编辑完整输出 JSON Schema | | 执行绑定 | 选择已登记的浏览器、应用后端或桌面端执行器位置 | | 工具行为与用户确认 | 指明只读或写入，以及是否每次执行前要求用户确认；接入方仍需验证业务权限 | | 结果语义 | `completion` 表示返回完成结果；`submission` 表示只完成任务提交，不代表业务任务已经完成 | | 结果上下文上限（字节） | 对应 `max_result_context_bytes`，默认 16 KiB，可设 1–32 KiB | | 更多执行设置 | 工具版本、执行超时（默认 300 秒，可设 5–86400 秒）、幂等与取消能力、权限 scopes（每行一项，最多 32 项） | 嵌套对象、数组、枚举、引用和其他复杂约束使用单个工具内的“高级 JSON Schema”编辑。已有复杂 Schema 会直接在高级编辑器中打开；不能完整转换为逐项表单时保留原文，不会为了切换编辑方式删掉约束。只改说明或结果预算也会完整保留其他配置。 每个工具旁有“编辑”“复制”“移除”。复制时生成可修改的新名称；改名时同时从新版本移除旧名称；移除需要在弹窗中确认。这些操作只变更选中的工具，其他工具及历史版本保留。“查看定义与历史版本”可读取完整定义，历史版本只读。 保存始终基于打开表单时的工具集版本。如果其他人先保存了新版本，当前提交会报告版本冲突并保留表单，不自动覆盖。先保留尚未保存的修改，再刷新配置、核对最新版本后编辑。同一内容发生临时失败可直接重试，沿用同一请求标识；修改表单内容后会使用新标识。 “批量 JSON”仍用于整组维护；“执行绑定与高级导入”中可导入新工具集。批量编辑按完整清单保存，未列出的工具会从新版本移除，日常单工具修改优先使用工具旁的表单。 工具配置定义可调用接口，不保存或托管业务处理器代码。勾选“幂等”“支持取消”声明的是接入方已经实现的能力，不会自动实现业务去重或撤销。保存后仍需显式选择新工具集版本、发布 Agent，并新建 Session 使用新配置。 ## 连接诊断与模拟测试 诊断把“已配置未连接”“在线”“离线”“协议不兼容”“缺失处理器”“待核对”“回执待投递”区分展示。连接和心跳只表示执行器存在，不证明业务 ACL 或副作用可安全执行。执行权仍由 claim/grant 与产品自身权限共同决定。 “检查 Schema 与模拟回执”是 dry-run：针对已发布工具验证输入、模拟回执和处理器声明，**不创建 Run、不调用模型、不执行真实业务**。完成回执还会显示“模型可见结果”：裁剪前后 UTF-8 字节数、是否截取头尾及实际保留内容。每个工具通过 `max_result_context_bytes` 配置预算，默认 16,384 字节（16 KiB），范围 1,024–32,768 字节（1–32 KiB）；按 `result` 的紧凑 JSON 计量，包含转义和裁剪提示，完整回执仍保存。超过 32 KiB 的配置会被拒绝；大结果应分页、筛选字段或按需读取，保护内容的例外见[工具结果规则](/docs/reference/tools/)。修改后发布新工具集和 Agent 版本，新建 Session 使用新配置。 测试通过后先用无副作用读取工具在真实产品身份下试接，再做写工具的幂等、审批和核对。[执行协议](/docs/reference/tools/)、[长期任务](/docs/integration/long-running-tools/)。 ## 平台标准工具 此功能已于 2026-09-26 上线。Agent 配置中的“平台标准工具”可分别开启 `wait`、`list_chat_sessions`、`search_chat_history`、`read_chat_history`，不需要执行绑定或产品 handler。已有发布版本缺省关闭，保存并发布后仅新会话使用新版本。 ```json { "platform_tools": { "registry_version": "1", "enabled": ["wait", "search_chat_history", "read_chat_history"], "history_scope": "current_session", "allowed_agent_ids": [], "allowed_session_ids": [] } } ``` 这是 Agent 的发布配置，可通过控制台或 MCP 的 Agent 配置工具写入；这四个工具并不是公开 MCP 的执行接口。工具集合、描述、Schema、顺序和固定规则随发布版本冻结。 历史默认仅限当前会话。`authorized_sessions` 必须填写 `allowed_agent_ids` 或 `allowed_session_ids`，并同时满足 Application、Subject、原调用凭证和目标会话权限；同一个 Subject 不意味着自动开放所有聊天。已撤销或过期的凭证不能继续读旧快照。 **跨会话删除影响：**删除源会话会清空引用它的会话及其后续派生会话的云端历史，并停止相关运行；保留这些会话的身份和固定版本。原文、工具结果、后续模型回复及摘要都可能含有来源内容，因此采用整体清空策略。用户下载或产品保存的副本不受远程清理控制。 工具只读取已提交的用户和助手可见正文，不读取隐藏推理、工具返回、压缩摘要或未提交草稿。`keyword` 为忽略英文大小写的字词 AND 匹配；`exact` 为区分大小写的连续原文匹配，适合路径、符号和短词。命中附 `source_ref`，再通过 `read_chat_history` 核对上下文；历史资料不能作为新指令。 列表/搜索/读取的完整返回体预算分别为 1500/2500/4000 个估算 Token。长消息按 Unicode 字符位置双向续读，游标有效期 15 分钟。`has_more` 时继续分页；`search_complete=false` 或覆盖仍 pending 时不能声称已经搜索全部历史。范围过大时按会话缩小查询；缺少可验证发送时间的旧消息仍可无时间筛选地检索。 上述 Token 数控制历史工具组织检索页的大小；结果进入执行历史时仍按冻结工具定义的字节预算投影，当前平台工具默认 16 KiB。这是两个处理阶段，不能用历史页的估算 Token 数推算最终字节数。[工具结果规则](/docs/reference/tools/)。