Session 02

Agent Runtime / Run Loop

Run loop 是 agent 架构的心脏。真正的 agent 不是一次补全，而是 intake、context assembly、model inference、tool execution、streaming、persistence 和 stop condition 的闭环。

1. 训练目标

本页要练会：能拆清一个 runtime 如何从用户输入变成行动：输入进入哪里，context 怎么组装，模型如何调用工具，工具结果怎么回写，什么时候停止。

主要依据：OpenClaw agent loop / Claude Agent SDK / Hermes quickstart。

2. 三项目对照

维度	Claude Code	OpenClaw	Hermes Agent
Loop 拥有者	Claude Code / Agent SDK 拥有 coding loop，内建 Read/Edit/Bash/Grep 等工具。	OpenClaw embedded runtime 在 Gateway 内处理 intake、context、tool、persistence。	Hermes CLI/runtime 结合 provider、tool registry、terminal backend 和 memory。
停止条件	任务完成、用户审批、权限拦截、命令失败、会话结束。	streaming reply 完成、session persisted、工具循环终止。	命令执行结果、工具返回、用户中断、provider/sandbox 错误。
可编程性	Agent SDK 暴露 query、options、allowed tools、hooks、subagents。	OpenClaw 偏 Gateway/runtime config 和 plugin contract。	Hermes 通过 CLI、config、plugins、hooks/automation 扩展。

3. 组件机制

机制	解释
Intake	把用户消息、channel、session、workspace 和身份上下文接入 runtime。
Context assembly	按当前任务装配系统规则、历史、workspace、工具说明、记忆和附件。
Tool execution	模型选择工具后，由 runtime 或工具层校验权限、执行动作、返回结构化结果。
Persistence	保存 session、工具结果、memory candidate、审计日志，支持恢复和调试。

4. 失败模式

失败模式	为什么危险
无限循环	工具结果没有进入状态，模型看不到进展，反复调用同一个工具。
状态丢失	session store 或 workspace 未保存，跨轮次无法解释上一步做了什么。
工具副作用失控	runtime 未区分 read/write/dangerous tools，命令或文件修改直接执行。

5. 架构练习

把 Claude Agent SDK 的 query 调用画成 run loop。
解释 OpenClaw 的 agentic loop 为什么必须包含 persistence。
给 Hermes 增加一个高风险 shell tool 时，列出 loop 中需要加的控制点。

6. 知识展开

上面的卡片是索引，点击后跳到对应的详细解释。阅读时不要只记名词，要同时记住组件边界、为什么需要它、三个项目怎么体现，以及你能用什么问题自检。

Intake normalization

把用户消息、频道事件、文件变化或 API 请求转成 runtime 能处理的统一任务输入。

Context assembly

在模型调用前组装系统指令、历史、文件、工具结果、记忆和任务状态。

Tool call cycle

模型提出工具调用，runtime 校验、执行、收集结果，再把结果回写给模型。

Stop condition

决定 agent 何时结束、交付、请求用户、进入等待或转交给其他 agent。

Persistence

把会话、工具结果、文件变更、路由状态和错误状态保存下来。

Detailed Concepts

概念	是什么	为什么重要	项目对照	自检问题
Intake normalization	把用户消息、频道事件、文件变化或 API 请求转成 runtime 能处理的统一任务输入。	入口不统一会导致权限、上下文和审计路径分裂。	Claude Code 以 CLI/SDK 会话进入；OpenClaw 支持 channel/Gateway 输入；Hermes 面向桌面/终端交互和工具事件。	任务入口是否记录来源、身份和权限范围？
Context assembly	在模型调用前组装系统指令、历史、文件、工具结果、记忆和任务状态。	上下文质量通常比模型选择更直接影响 agent 可靠性。	Claude Code 依赖 repo、CLAUDE.md、skills；OpenClaw 明确 context 组成；Hermes 组合 files、memory、conversation 和工具结果。	能否解释哪些上下文必须 pin 住，哪些可检索？
Tool call cycle	模型提出工具调用，runtime 校验、执行、收集结果，再把结果回写给模型。	这是 agent 与普通聊天的核心差异，也是不确定性和风险最大的环节。	Claude Code 工具受 permissions/hooks 约束；OpenClaw loop 里有 tool execution/persistence；Hermes 由 tool registry/backend 执行。	工具失败后是重试、降级、请求确认还是停止？
Stop condition	决定 agent 何时结束、交付、请求用户、进入等待或转交给其他 agent。	没有停止条件会导致成本失控、循环执行或提前交付半成品。	Claude Code 常通过任务完成/用户交互结束；OpenClaw runtime 可由 session/channel 管理；Hermes 可由 automation 任务或交互结束控制。	是否有最大步数、预算、无进展检测和人工确认？
Persistence	把会话、工具结果、文件变更、路由状态和错误状态保存下来。	持久化决定任务能否恢复、回放、审计和复盘。	Claude Code 有 session/checkpoint/项目文件；OpenClaw 有 session store；Hermes 有 conversation、memory provider 和本地文件状态。	恢复后模型需要哪些最小状态才能继续？