主题
Agent 任务执行链路方案
1. 方案摘要
本方案把一次 Agent 任务定义为可追踪、可取消、可续跑的持久化生命周期。入口请求先完成身份、租户和触发判断，再取得 Chat ownership，固化 Agent/Model 快照，进入串行 Session 执行，最后发布事件并保存终态。
2. 设计目标与非目标
设计目标
- 保证同一会话任务串行，避免并发写入破坏上下文。
- 让取消、继续输入、工具调用和恢复都拥有持久化状态。
- 把模型、工具、Prompt 和文件上下文固化到可审计的任务快照。
非目标
- 不把模型 Provider 的重试算法当作任务状态机。
- 不允许通过重复用户消息模拟恢复。
- 不在任务链路中直接修改全局租户配置。
3. 架构范围与视图
一次任务如何从入口变成可恢复、可观测、可持久化的 Agent 执行？
本图聚焦单次任务生命周期，不展开各入口平台协议和多副本失联算法。
图中绿色实线表示当前能力，紫色虚线表示规划或待完善能力。图片用于建立空间关系，本文正文定义方案语义、边界和落地规则。
4. 组件与责任边界
| 组件 | 责任 |
|---|---|
| 身份与租户 | 确定用户、租户、Agent 与 chatId。 |
| Chat / Task | 创建或读取 Chat，记录 task 状态和 ownership。 |
| Dispatcher | 统一路由、内容过滤、bind 解析和预检。 |
| Ledger / Trigger | 去重入站消息并判断是否触发 Agent。 |
| Session | 串行化同一会话任务并维护 SDK session。 |
| AgentRunner | 组装 prompt、workspace、model、tool 和 sandbox 选项。 |
| Claude Agent SDK | 执行 query，产生消息、工具和终态事件。 |
| EventBus / Reply | 把进度和结果推送到 Web、IM 或 OpenAPI。 |
组件之间只通过明确的输入、输出和生命周期契约协作。上层可以编排下层能力，但不能绕过下层的权限、租户和状态边界直接读写内部对象。
5. 核心设计决策
- Ledger / Trigger 负责去重和触发判定，Dispatcher 负责统一路由和预检。
- Session 是同一 Chat 的串行执行边界，AgentRunner 是一次 query 的执行边界。
- 所有终态写入携带 ownership guard，旧执行者不能覆盖新 owner。
这些决策共同保证：入口可以替换、执行可以迁移、状态可以恢复，而不会改变用户可见的任务和会话语义。
6. 关键流程与时序
主流程
- 解析身份与租户
- 创建 / 读取 Chat
- Dispatcher + Ledger + Trigger
- 取得 Session 和 owner guard
- 固化 Agent / Model 快照
- AgentRunner 调用 query
- 处理工具与继续输入
- 发布流式事件
- 保存终态、用量与归档
- 释放 Session
流程解释
流程中的每一步都应产生可追踪的上下文：租户、Agent、Chat、Task、运行副本和结果引用。过程事件用于向用户反馈进度，终态写入和结果归档必须在事实源更新后再对外确认。
7. 数据、一致性与状态管理
- Chat、Task、Session id、终态和用量写入以数据库为准。
- Agent、Model、Skill、Tool 和配置在任务开始时形成快照。
- 流式事件可以丢失或重放，但不能改变任务终态。
当前专题的关键约束
- 配置热更新不改写进行中任务快照。
- 同一会话的运行任务由会话队列控制。
- 终态和 session id 写入必须符合 ownership 约束。
8. 异常、恢复与安全边界
- 预检失败不启动 Agent query，并保留可解释的拒绝原因。
- 工具失败、模型失败和用户取消分别记录，不把不同原因混成普通错误。
- Runtime 直接关停造成的最后一个工具调用中断可由恢复流程续写；更早的拒绝语义继续有效。
异常处理遵循“先阻止错误扩散，再保留可恢复状态，最后由明确的补偿动作完成收口”。任何重试都必须具备幂等条件，任何恢复都必须重新校验租户、权限、版本和 ownership。
9. 部署与扩展边界
- 任务执行可以在组合角色或 Runtime 副本完成。
- Gateway 只负责入口和派发，不消费 Runtime 内存中的 pending tool。
部署形态可以变化，但不能把本地内存、临时文件或单副本事件队列当作跨副本事实源。需要横向扩展的能力应先明确共享状态、路由键、健康状态和故障补偿方式。
10. 当前能力与演进计划
当前已落地
- 取消、继续输入、工具结果续跑和异常终态
- 任务 ownership guard 与持久化终态
规划或待完善
- 本专题暂未列出独立规划项。
演进方向
- 补充任务级重试预算、工具幂等键和长任务 checkpoint。
- 在不改变 Chat/Task 状态机的前提下增加新的 Agent Runner。
11. 方案验收要点
- 重复入站不会产生重复任务。
- 同一 Chat 同时只有一个有效执行 owner。
- 恢复后续写原 assistant 消息，不新增用户消息。
验收时应同时检查正常链路、重复操作、空态或拒绝态、依赖不可用和副本切换，不能只验证图中最短路径。