执行器与工具回执协议

配置工具 Schema 与执行真实业务是两个阶段。Agent 引用的工具集版本描述工具名、输入和绑定；产品执行器必须在线、在授权范围内取得唯一 claim，并在业务操作前确认 grant/accepted 回执。

路径省略 /v1 前缀。tools:execute 只准入通用协议；产品还必须按自己的 Subject、Agent、资源版本、参数摘要及业务权限逐次校验。执行器连接许可不能替代 claim/receipt 权限。候选列表不给工具参数或执行 grant，不能从一个 binding ID 推断有执行权。身份范围。

写工具先持久化操作键与 assignment，收到 accepted 的明确确认后才开始副作用。进度和最终回执先保存再发送，重投沿用同一 receipt_id/正文；replayed=true 只核对并重投，不重跑 handler。普通异常视为可能已有业务结果，进入 reconciliation_required；明确业务失败/取消须由产品确认后提交相应终态。迟到回执不会复活已终止 Run。

cancel、断开浏览器、执行器 detach、业务任务取消和补偿是不同操作。完整请求 Schema 查看OpenAPI，产品实现步骤查看ToolRunner和异步任务。

工具结果的上下文上限

工具定义示例（binding_id 替换为已注册执行绑定）：

{
  "name": "tasks.read",
  "description": "分页读取任务",
  "binding_id": "binding_example",
  "input_schema": {"type": "object", "properties": {"cursor": {"type": "string"}}},
  "output_schema": {"type": "object"},
  "max_result_context_bytes": 16384
}

max_result_context_bytes 默认 16,384 字节（16 KiB），可设 1,024–32,768 字节（1–32 KiB）。计量对象是 result 的紧凑 JSON：UTF-8 编码、直接保留中文与 emoji、无缩进和分隔空格；字符串的引号、JSON 转义和裁剪提示本身都计入预算，不包含外层回执或消息封套。它不依赖 Token 估算系数，32 KiB 也不代表 32k Token。

完整工具回执按原样持久保存；完成结果首次进入执行历史时超限才形成头尾预览。裁剪保持合法 Unicode 和 JSON，但可能把原始嵌套结构换成 preview.head / preview.tail，中间字段可能不再可见，不能假设 data.next_cursor 等分页信息会完整保留。部分短状态字段会尽量放入 preserved_fields，仍受同一字节预算约束。已有投影不会在每轮重新生成，保障未压缩时的上下文前缀稳定。

单工具可配置上限是 32 KiB，即 32,768 字节。 超过上限的配置会校验失败。多个工具结果会累积占用 Agent 输入窗口；整个请求仍按 max_context_tokens 和真实 usage 校准后的 Token 估算决定是否压缩。

如果一个工具经常需要返回超过 32 KiB 的内容，应调整工具设计：支持分页或游标续读、按条件与字段筛选，先返回摘要和标识，再按需读取片段。开发者和接入 Agent 不应依赖提高配置上限解决大结果问题，也不能假设头尾预览保留了中间全部事实。分页游标、状态与关键标识应放在紧凑结果中，并使用下面的预览核验它们是否可见。

submission、未知业务结果和不透明回放受协议保护，不进行此裁剪。多模态结果仅裁剪文本块，文本块及包装、转义、裁剪提示计入预算；图片等非文本内容原样保留、不占文本裁剪预算，所以完整结果的 retained_bytes 可以超过配置值。最终完整请求仍须通过输入 Token 窗口检查。完整回执不会因为这个裁剪预算而被拒收；通用 HTTP 传输限制仍适用，较大的业务数据应分页或提供可继续读取的引用。

旧 max_result_tokens 与旧回执拒收字段 max_result_bytes 已删除，传入会校验失败，不提供别名兼容。本次服务升级已将存量 Token 配置一次性替换为默认 16 KiB，保留已提交执行历史。此后修改预算需要发布新工具集与 Agent 版本，并新建 Session。配置迁移。

检查模型实际看到什么

用具有目标 Agent 范围、且具备 runtime:read / configuration:read / tools:execute 其中一项权限的服务端身份调用 POST /v1/tools/dry-run，将下面版本 ID 换成真实发布版本，工具名和参数匹配该版本的工具定义：

{
  "agent_version": "替换为已发布的固定版本 ID",
  "tool_name": "tasks.read",
  "arguments": {},
  "mock_receipts": [
    {
      "receipt_id": "dry-run-page-001",
      "kind": "completed",
      "result": {"next_cursor": "page-2", "tasks": []}
    }
  ]
}

响应的 context_preview 包含 max_result_context_bytes、original_bytes、retained_bytes、truncated 和 result。original_bytes / retained_bytes 是裁剪前后完整 result 的紧凑 JSON UTF-8 字节数；result 是这条回执首次进入执行历史时的内容，之后仍可能随整体上下文压缩而变化。没有 completed 模拟回执时，预览为 null。

将示例 result 换成产品的真实大小样本，检查是否截断，以及游标、ID、状态和关键事实是否仍可见。控制台“检查 Schema 与模拟回执”展示同一预览；这一步不创建 Run、不调用模型、不执行业务。execution_verified=false，即使 Schema 校验通过也不证明真实业务可用。

本地可先用 Python 测量原始结果，裁剪后的准确内容仍以 dry-run 为准：

import json

result = {"next_cursor": "page-2", "tasks": []}
size_bytes = len(json.dumps(
    result, ensure_ascii=False, sort_keys=True,
    separators=(",", ":"), allow_nan=False,
).encode("utf-8"))

测量的是 JSON 编码后的 result，不能用字符长度、文件大小或 Token 估算系数代替。分页和字段筛选应尽量让每页完整落在预算内，避免把必要信息寄托于头尾裁剪。