跳转到主要内容
Hexagon 有两个不同入口:让 Harness 发现并调用命名操作的 HTTP Tool,以及让 Sandbox 代码通过委托访问地址请求 API 的受保护 HTTP 连接。先按调用方式选择,不能把两者的审批和调用记录混为一谈。

定义固定的读写操作

准备一个你控制的测试服务:验证路径接受 Bearer key;读接口返回已知测试报告;写接口保存 reference 和 text,并能按 reference 查证实际写入。返回值必须是 JSON。下面是配置模板,保存为 http-tool.json,先替换占位 base_url 并实现相应接口;这些路径不是 Hexagon 自带服务。
每个操作固定 path 和 GET/POST。GET 参数进入 query,字符串原样传递,其他值 JSON 编码;POST 参数作为 JSON body。不能由 Agent 参数指定任意 URL、header、HTTP 方法或路径模板。input_schema 必须是受支持的同步 object JSON Schema,建议禁止额外字段。路径不接受 query、fragment、反斜杠、双斜杠开头或 .. 段。 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 后复用。
验证会请求固定 verify_path,不能让验证路径执行写入。验证成功不证明每个业务操作都可调用。随后按 Tools 绑定把连接 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 审批,不能替代这里的批准写入测试。

如果需要 guest 直接调用 API

使用 kind=http/provider=http,config 包含 endpoint、authentication 和 access.rules。例如:
这个入口支持 bearer 或指定 header,可信后端注入原始凭据;要求公共 HTTPS 上游,规则是精确路径与方法。Session 通过 connections 绑定,guest 从 HEXAGON_CONNECTIONS 读取 base_url 与委托 headers。通用 HTTP 验证只检查结构和 header 安全,不远程认证。该通道没有 ToolBroker 的自动审批或逐 Tool 对账状态,需要写审批的操作应使用前面的 Agent Tool 入口。 原始 key 不进入新 Harness 调用;委托 token 仍然有权限,不能打印、放入模型上下文或产物。不要把委托保护理解成可任意调用上游全部 API。见凭据边界和Secret 契约。 本页核对了两类 adapter 和执行契约,没有新执行测试服务。完整验收应分别证明读结果、批准前零写入、批准后一次写入、丢失响应不重复写入、guest 不含原始 key、双 SDK 与资源清理,不能由文档示例推断这些测试已通过。 依据:HTTP Tool、受保护 HTTP 策略、Tool 对账契约。 下一步:审批、清理与对账、凭据边界。