Agent 状态

本页定义 Holon 中 Agent 状态、生命周期和运行时投影的当前契约。契约基于下方 最后复核日期所对应的实现和测试进行验证。

Last verified: 2026-07-24 against src/types.rs AgentState, AgentStatus, AgentIdentityView, AgentSchedulingPosture, AgentPostureProjection, ClosureDecision, ContinuationResolution, RuntimePosture, and AgentSummary; src/storage/mod.rs agent_posture_projection; src/runtime/lifecycle.rs agent_summary; src/runtime/closure.rs closure derivation; and src/tool/tools/get_agent.rs.

源 RFC

• Agent 状态模型与运行时投影
• Agent 生命周期控制姿态
• Agent 控制平面模型
• Agent Profile 模型
• Agent 初始化与模板
• Agent 删除生命周期

权威记录与投影

Agent 状态派生自权威运行时记录，而不是存成单个不透明的状态字段。关键区别是：

AgentSummary 是展示投影，不是调度决策的事实来源。调度器必须从队列、 WorkItem、任务和等待状态派生姿态，而不能读取摘要字段。

当前实现锚点：

• RuntimeHandle::agent_summary 在读取时，从当前 AgentState、身份视图、 模型状态、执行快照、活跃等待、子 Agent、外部触发器和 AppStorage::agent_posture_projection 组装出 AgentSummary。
• GetAgent 直接返回组装好的 AgentSummary；它不写入生命周期、调度或等待状态。
• /agents/list 和 /agents/{agent_id} 走同一条运行时摘要/列表投影路径。 AgentListEntry 是紧凑的列表投影，不是调度器输入。
• AppStorage::agent_posture_projection 从持久化/运行时记录派生出对外暴露的 AgentSchedulingPosture。任何对调度敏感的路径都不应把 AgentSummary.scheduling_posture 读回来当作权威。

Agent 生命周期状态（AgentStatus）

                ┌─────────────┐
                │   Booting   │
                └──────┬──────┘
                       │ daemon_start / Start
                       ▼
                ┌─────────────┐
         ┌─────►│  AwakeIdle  │◄─────────────┐
         │      └──────┬──────┘              │
         │             │ turn starts         │
         │             ▼                     │
         │      ┌──────────────┐             │
         │      │ AwakeRunning │             │
         │      └──────┬───────┘             │
         │             │ turn closure        │
         │             ▼                     │
         │      ┌─────────────┐     ┌────────┴──────┐
         ├──────│    Asleep    │────►│  AwaitingTask │
         │      └─────────────┘     └────────┬──────┘
         │         wake / resume              │ task result
         │                                    │
         └────────────────────────────────────┘

                          Stop ──► ┌──────────┐
                                   │  Stopped  │
                                   └──────────┘

关键契约：

• Asleep 是运行时姿态，只在调度器于轮次 closure 后接受休息时到达。 它不是权威的“空闲”声明。
• WaitFor 在让出前记录显式等待状态；当 WorkItem 或 Agent 等待任务、外部 或操作者输入时，它是首选路径。
• Asleep 的 Agent 可以有 runnable 的 WorkItem。Asleep 不表示空闲或无事可做。
• AwaitingTask 是当前运行时、TUI、daemon 和等待投影使用的过渡生命周期标签， 用于非终态任务（命令、子 Agent）阻塞后续模型重入的情形。它日后可能并入 AwakeIdle 加任务等待调度姿态，但在迁移发生前仍是当前契约。
• Stopped 是硬生命周期边界。调度器不会为已停止的 Agent 启动新轮次。 已停止的 Agent 会释放运行时拥有的执行资源。
• 状态转换经由调度器拥有的辅助函数；任何模块都不应绕过调度器执行器直接修改 AgentState.status。

调度姿态（AgentSchedulingPosture）

调度器从当前状态派生出调度姿态。这是投影，不是存储状态。当前归约到 Agent 级的投影按以下优先级判定：

关键契约：

• 姿态派生自队列深度、WorkItem 就绪状态、等待状态、任务阻塞状态和外部触发器。
• 姿态是快照派生值，不作为持久状态保存。
• 已停止的生命周期先于瞬时的运行、队列、工作或等待事实，赢得对外投影（Stopped）。
• 队列和可运行工作优先于被动休眠姿态。有入队输入或有可运行 WorkItem 的 Asleep Agent 会投影为 HasQueuedInput 或 HasRunnableWork，而不是 Idle。
• WorkItem 级的 WaitingTimer 和 WaitingSystem 仍是不同的调度器等待状态， 但归约后的 Agent 级姿态目前把它们报告为 Blocked；调度器的空闲边界决策仍会 检查 WorkItem 等待状态，以发出定时器或系统 tick 动作。
• AgentSummary.scheduling_posture 暴露这一投影；使用者不应把它当作权威调度输入。

Closure 与延续

每轮结束时，closure 决策决定下一个姿态：

等待中的 Agent 被重新激活时，ContinuationResolution 记录：

Closure 推导与展示姿态相互独立。它使用调度器投影事实和当前轮次事实来选择 ClosureOutcome、WaitingReason 和 RuntimePosture。当前实现中：

• 显式操作者等待在 closure 原因上优先于其他等待条件；
• 阻塞任务只是元数据，除非有当前工作等待表示它；
• 活跃的工作项或 Agent 等待意图映射为外部等待；
• 定时器映射为定时器等待；
• 可运行工作可以阻止无关的 Agent 级等待意图成为 closure 原因。

面向用户的投影（AgentSummary）

AgentSummary 是由 GetAgent 和 GET /api/agents/{agent_id} 返回的稳定投影。 它包含：

• identity — Agent 身份徽标和 profile
• agent — 核心 AgentState，含状态、待处理计数、轮次索引
• scheduling_posture — 派生姿态快照
• lifecycle — 生命周期提示（非权威）
• model — 当前模型选择
• token_usage — token 用量摘要
• closure — 最近一次 closure 决策
• execution — 执行快照（run id、cwd、workspace）
• active_children — 可见的子 Agent 摘要
• active_wait_conditions — 当前等待状态
• active_external_triggers — 已配置的外部 ingress 能力

关键契约：

• AgentSummary 在读取时从权威记录组装。
• 新增字段保持保守；不要把 AgentSummary 当作内部状态的堆放处。
• 模型通过 GetAgent 收到 AgentSummary 作为展示信息，而不是调度指令。
• API 使用者不得依赖摘要字段顺序或默认/空字段是否出现。

v0.38.0 身份迁移遗留

AgentVisibility、AgentOwnership、PrivateChild 和 PublicNamed 仅描述 v0.38.0 的迁移面。它们不是当前的公开身份契约，不得用于选择创建或委派行为。 当前调用方使用 CreateAgent 创建可寻址 Agent，使用 InvokeAgent 做父级监督的 委派执行。

生命周期控制

Agent 执行生命周期控制是 Start / Stop：

• Start 把 Agent 交给调度器。它不直接启动模型轮次；由调度器决定 Agent 应保持空闲还是处理入队输入。
• Stop 中止当前运行，释放运行时拥有的执行资源，并把 Agent 标记为不可运行。 入队消息和持久记录会被保留。
• 没有 Pause / Resume。契约就是 Stop + Start。

验证结论

本页对照 issue #1367 中列出的 RFC 和实现区域进行了验证。

已知缺口

• AgentStatus 仍包含过渡状态（Booting、AwaitingTask），随着调度器模型成熟 它们可能被合并。若 AwaitingTask 最终完全并入 AwakeIdle + 任务阻塞，见后续跟进。
• AgentLifecycleHint 携带生命周期投递提示，例如是否接受外部消息，以及可选的 操作者指引。已废弃的 Pause/Resume 投影字段不属于契约。
• AgentSummary 含一些契约尚未固化的字段（recent_operator_notifications、 recent_brief_count）。
• AgentStatus::Asleep 仍是生命周期/展示投影，但调度器的空闲边界决策会先检查 等待和工作事实，再把已休眠的 Agent 当作空闲。
• AgentStatus::AwaitingTask 在代码中仍是过渡状态，尽管它不在长期目标状态集 （agent-lifecycle-control-posture.md）中。
• AgentSchedulingPosture::Stopped 覆盖已停止的 Agent；archived 只作为 serde 别名保留，与之前“当前未使用”的规范说法相反。