异步任务与可靠回执
持续的业务工作留在产品队列或服务中,HostAnAgent 保存 Agent Run、工具等待、确认与结果关联。仅登记 binding、连接执行器或收到 accepted 并不表示业务已经完成。
| 产品工具语义 | 最终回执什么时候发 | Agent 能据此说什么 |
|---|---|---|
completion:生成并返回资产 |
资产实际生成或确认失败后 | 资产已完成、失败或取消 |
submission:提交业务任务 |
产品已可靠接受并返回任务 ID 后 | 任务已提交;后续查询/取消由产品另提供工具 |
先以产品身份确认资源 ACL 和参数摘要,使用稳定 executor ID 领取 tool call。产品在副作用前持久保存 tool_call_id、业务幂等键和 assignment;收到 accepted 的明确确认后才执行。运行中按协议提交 progress,业务结果确定后先持久化 final receipt,再投递平台。重启时优先补投已有回执或查询同一业务任务,不能再次创建任务。执行协议。
业务队列、生成服务、文件下载、资产授权、任务查询和收费由产品维护。长任务要在浏览器关闭后继续时,必须有产品后端持续处理,或让重连执行器按稳定业务任务 ID 查询已有结果。下载链接过期后重新校验权限,不能将长期有效资产 URL 放进 Agent 历史。停止 Agent Run 不自动停止产品队列任务。
端到端测试至少覆盖双执行器竞争、接受/最终回执响应丢失、进程重启、迟到结果、用户权限变化、重复请求以及业务取消。官方持久回执示例是单进程参考;多进程产品需要自己的事务 outbox、锁和清理策略。真实 SitRep/AIAniGen 业务适配仍由对应产品仓库验证。
平台 wait
对 submission 型产品工具,Agent 可以同批调用 wait 再查询已知任务 ID 的状态。duration_ms 必填,为 1000–30000 毫秒,Agent 自主选择;reason 可选。等待期限从该工具实际分派时开始持久保存,释放 Worker 槽位;重启按原期限恢复,同一批工具仍串行,批次结束前不额外调用模型。等待计入 Run 总时限和工具次数,超出剩余总时长会报错,不静默缩短。
成功返回 requested_ms、实际 waited_ms、observation_scope="elapsed_time_only" 和 target_status_observed=false,仅证明已经经过时间。排队会令实际时间更长,业务是否完成须查询产品权威状态。completion 型工具继续等待最终回执,本身不需要额外 wait;等待用户回复也不使用此工具。停止 Run 不会自动取消产品任务。
平台调用标记 execution_owner="platform",状态为 platform_waiting 或 platform_running;接入方不要对它 claim、执行 handler 或回传 receipt,服务端会拒绝。公开 0.2.4 包已验证可读取新字段及这些状态,不会自动执行平台 handler;0.2.5 提供对应的中文展示、配置类型及 ToolRunner 平台调用隔离。参见平台标准工具配置。