把 Agent 运行时、工具执行和状态存储拆开看，Qoni 承担运行时比较自然；工具执行到底放平台还是自建回调，取决于超时控制权、重试策略和内网可达性；状态存储则按生命周期选择平台侧或自建库。没有一种归属能覆盖所有工具，建议先用一个最小工具在两条路径上各跑一遍，用日志和页面记录实际表现，再决定每个工具的落位。

工具执行归属不宜一刀切。平台内置执行适合公网可达、超时和重试由平台托管、不想额外维护服务的场景；自建回调适合需要访问内网、要自行控制超时阈值与重试细节、并且能接受维护回调服务的场景。可以先在 Qoni 侧配置一个测试 Agent，对同一工具分别走平台内置和自建回调，记录端到端耗时、失败信息原文和重试次数，再按记录结果分配。风险边界：平台侧超时和重试参数可能不可调，自建回调需要处理鉴权和网络放行，两者都要以控制台页面和实际日志为准。

列出工具调用的两种执行归属

在 Qoni 上，工具调用通常有两种落位：平台内置执行和自建回调。先把它们的前置条件、网络要求和鉴权方式摆出来，再判断具体工具适合哪种。

如果工具只查询公网接口、不需要接触内网，平台内置执行通常更省事；如果工具要连内网数据库、内部 API 或需要自定义超时重试，自建回调路径更合适。下面逐项对比超时、重试和错误返回。

逐项对比超时、重试与错误返回的表现

超时阈值、重试次数和错误信息粒度，不能凭推测，需要在 Qoni 控制台工具配置页和自建回调服务日志中确认。建议按下面表格逐项记录实测值，不要用默认值替代。

错误信息粒度通常不同：平台内置执行返回的是平台封装后的错误摘要，便于 Agent 识别但可能丢失原始堆栈；自建回调可以返回原始 HTTP 状态码和业务错误体，但需要在回调服务里自己保证错误格式统一。记录时直接复制原文，不要改写。

为需要内网访问的工具保留自建回调路径

工具需要访问内网数据库、内部管理接口或只能在私有子网调用的服务时，通常不要让 Qoni 平台直接连内网，而是加一层自建回调服务做中转。回调地址一般配置在 Qoni 工具配置页的“回调 URL”或“Webhook URL”字段；鉴权头在工具配置的 Header 区域填写；网络侧需要在防火墙或安全组放行 Qoni 平台出口 IP 到回调服务的入站端口。

下面是一个通用的回调接入骨架，替换掉地址、令牌和校验逻辑即可：

# Qoni 工具配置页（示例字段名）
回调地址: https://your-callback.example.com/qoni/tool
鉴权头:
  Authorization: Bearer {QONI_CALLBACK_TOKEN}
  X-Qoni-Timestamp: {timestamp}
  X-Qoni-Signature: sha256={hmac}

# 回调服务侧处理骨架
POST /qoni/tool
1. 读取 Header 中的 Authorization 和 X-Qoni-Signature
2. 用共享密钥校验签名和时间戳窗口
3. 解析 body 中的 tool、args
4. 访问内网资源并返回 JSON
5. 记录请求日志，包含 request_id、耗时、错误原文

白名单放行项通常包括：源地址为 Qoni 平台出口 IP 或 IP 段，目标端口为回调服务监听端口（常见 443），协议 TCP。如果 Qoni 提供出口 IP 列表，建议直接加入防火墙白名单；如果出口 IP 不固定，可以改用带鉴权的网关或只暴露回调路径，不要开放整个内网。

固定输入分别跑两条路径并记录数据

选一个无副作用的工具，例如回显参数或只读查询，准备同一组固定输入。在 Qoni 侧分别创建平台内置工具和自建回调工具，各跑若干次（建议至少 5 次），逐次记录端到端耗时、失败信息原文和重试次数。端到端耗时从发起调用开始，到收到最终响应结束；失败信息原文直接从平台日志或回调服务访问日志复制；重试次数记录平台侧和回调侧各自实际发生的重试。

记录时不要填入预估数字，只填实际观察到的值。若某次调用成功，失败信息原文留空；若平台侧没有暴露重试次数，写“平台未显示”并附上日志行。跑完两条路径后，对比超时触发点、错误可读性和重试是否带来额外副作用，再决定该工具放在哪一侧。

写出运行时、工具、状态三部分的归属表

把上面的记录整理成一张归属表，作为后续新增工具和调整配置的依据。组件、执行位置、关键配置项、失败兜底动作四列，按实际环境填写。

这张表不需要一次定死。新增工具时先判断它是否需要内网访问、超时和重试是否要自己控制，再对照已有记录选择执行位置。每次调整后，用同一组固定输入再跑一遍两条路径，确认配置变化没有引入新的超时或鉴权问题。