# Agent 轮次与步骤生命周期
[English](agent-lifecycle.md) | 中文
此时序图是 [architecture.md](architecture.md#default-loop-lifecycle) 的配套图示。持久的回放事实保存在 `session/event` 中，实时控制与状态则保存在 `agent/*` 中。
```mermaid
sequenceDiagram
participant User
participant Agent
participant Driver
participant Hooks as hook listeners
participant Prompt as ctx.systemPrompt
participant LLM as ctx.llm
participant Tools as ctx.tools
participant Session
participant SDK as UI or SDK listener
User->>Agent: followup(content)
Agent-->>SDK: agent/inbox/spliced
Agent-->>SDK: agent/inbox/inserted { message }
Agent->>Driver: queued work wakes driver
Driver-->>SDK: agent/status running
Note over Agent,Driver: claim pending next-step input plus one queued prompt
Driver-->>SDK: agent/inbox/spliced pure deletion
Driver-->>SDK: agent/inbox/claimed { message, turn } per message
Driver->>Hooks: agent/pre-step waterfall
Hooks-->>Driver: authoritative reject or enter(messages)
alt proposed step rejected or pre-step failed
Driver-->>Driver: claimed batch stays removed, no turn opens
else enter proposed step
Driver->>Session: turn/start
Driver->>Session: step/start
Driver->>Session: user/message per entered message
Driver->>Prompt: system-prompt/assemble waterfall
Driver->>LLM: agent/request waterfall, then llm/stream waterfall
LLM-->>Driver: StreamChunk*
Driver->>Session: assistant/chunk*
Session-->>SDK: session/event assistant/chunk*
alt final adapter or terminal in-band request failure
Driver->>Session: step/end
Driver->>Hooks: agent/request-error waterfall
Hooks-->>Driver: return retry action or preserve the original error
else model request succeeded
Driver->>Session: assistant/message
Driver->>Tools: classify pending call by executionMode
loop barriers and bounded rolling pool, reclassify before start
opt call starts
Driver->>Session: tool/call
Driver->>Tools: ordered pre, concurrent execute
Tools-->>Session: tool-owned events when applicable
end
opt next model-order result ready
Driver->>Tools: ordered post
Driver->>Session: tool/result
end
end
Driver->>Session: step/end
opt natural stop and next-step inbox empty
Driver->>Hooks: agent/turn-stopping serial terminal checkpoint
end
opt next-step input is pending
Driver-->>Driver: claim pending next-step input
Driver-->>SDK: agent/inbox/claimed { message, turn } per message
Driver->>Hooks: agent/pre-step waterfall
Hooks-->>Driver: authoritative reject or enter(messages)
end
end
Driver->>Session: turn/end
end
Driver-->>SDK: agent/status idle
```
`assistant/message` 事件会记录每次成功的提供方调用，包括返回空内容或以 `max-tokens` 结束的调用。空内容不会进入派生历史，但该持久事件仍会保留用量，并通过 `sourceEventSeqs` 精确列出对应的 `assistant/chunk` 事件，包括显式空列表。
`dsh-compact-basic` 在派生请求之前通过 `agent/pre-step` 处理压力，而 `agent/request-error` 仅用于规范的上下文溢出。任一触发条件满足后，系统都会先执行可选的工具结果剪枝，再选择摘要。恢复发生在失败步骤结束之后、失败轮次结束之前；只有当剪枝或摘要生成推进了 surface replacement generation 时，系统才会开启一个全新的重试轮次，否则仍以原始请求错误为准。
以返回的 `agent/pre-step` 决策为准；通过包装 `next()` 的监听器会保留下游消息，除非有意替换这些消息。steering（中途引导）和注入的上下文在后续的认领操作取得其下一步骤批次后，会经过同一 waterfall（瀑布式事件）。
需要可回放 transcript（文本记录）数据的 SDK 用户应当消费 `session/event`；`agent/*` 是用于队列与状态、提示词拦截、请求构造、steering、继续执行和错误处理的实时协调接口。
维护模式：英文源文件包含人工维护的 Mermaid 时序图，并由生成器写出；本中文文件作为经评审对侧通过双语配对维护。确切的事件签名位于生成的 Cordis 目录中。