定义固定的读写操作
准备一个你控制的测试服务:验证路径接受 Bearer key;读接口返回已知测试报告;写接口保存 reference 和 text,并能按 reference 查证实际写入。返回值必须是 JSON。下面是配置模板,保存为 http-tool.json,先替换占位 base_url 并实现相应接口;这些路径不是 Hexagon 自带服务。.. 段。
adapter 注入 Authorization: Bearer 和稳定调用 idempotency-key,不提供自定义 header 映射。服务收到该 header 不代表它真的实现了去重,示例因此保留 replay=never;只有上游确实以该键去重并验证契约后才考虑 idempotency_key 策略。即便 GET 也不应仅凭方法名认定没有副作用。
审查参数映射与重放契约
read_report 的 {"id":"report-1"} 会成为固定 /reports/read 路径的查询参数。数字或对象参数被 JSON 编码为查询值,不展开为路径片段。save_report 的 {"reference":"request-1","text":"Reviewed"} 会成为 JSON 请求体。映射步骤不会将任意参数插入上游 host 或认证头。
当前 broker 中,结果未知的已派发 GET 即使配置 replay: never 仍可能重试。GET 的可重放判定独立于非 GET 的 replay 策略。因此只用 GET 暴露确实可安全重复的读取,不要将改变状态的接口映射为 GET 后期待 replay: never 阻止重复。POST 只有在上游确实支持稳定调用键、重试保持相同结果时才使用 idempotency_key;没有该契约的写入保留 never。
连接验证可能从小型 JSON 响应提取经过过滤的账户/scope 展示元数据。缺失时保持未知;显示 scope 不替代选定操作策略,也不批准写入。验证端点成功同样不证明每个操作路径都获准访问。
创建、验证、启用与绑定
以下示例使用本地管理客户端,凭据由私有环境提供;hosted 初始化见自托管。保存返回 ID 后复用。tools: {reports: connection_id},选择支持 Tools 的 Harness,完成 Session 预检与创建。默认必需 Tool 在初始化时要求授权;optional_tools 不会绕过授权或审批。
让第一轮只调用 read_report 并核对真实报告内容;第二轮调用 save_report,审批界面检查 reference 与 text 后才允许写入。approval=true 控制调用审批,与连接是否已有凭据是两个状态。验证拒绝时上游没有写入,再用授权的专用测试记录检查批准后只有一次写入。参见审批。
响应、错误和未知结果
当前单次请求超时 20 秒,不跟随重定向;401/403 进入鉴权错误路径。结果必须可解析为 JSON,响应文本超过 1048576 个 JavaScript 字符单元会失败。这是当前实现检查,不是字节级下载上限承诺。 调用可能已在远端写入,但响应丢失或解析失败。因此任务报错不证明没有副作用。Tool 调用记录保存请求 hash 和实际执行策略,未知结果进入对账;不要给相同业务操作生成新 reference 再试一次。 用 tool_calls / toolCalls 查看原调用,在远端按 reference 核对后用 resolve_tool_call / resolveToolCall 记录 completed 或 failed 和证据。解析结论不会再发送远端请求;仍未知时保留等待或取消 Run,不能编造成功。连接后续修改不能改变原调用的重放资格。完整流程见对账。按业务 reference 验证写入
使用专用报告标识,例如hexagon-acceptance-001。reference 标识业务记录,Tool call ID 标识一次平台调用,两者都应保留。以下是供受控服务执行的验收步骤,不是本次文档更新的执行结果。
如果服务无法按 reference 查询或区分重复写入,就还不能完成这项对账证明。请求失败不能证明“没有写入”,也不要对生产数据执行这项故障测试。GET 另有前文说明的可重复安全要求。直接受保护 HTTP 绑定不经过 ToolBroker 审批,不能替代这里的批准写入测试。