1.1 双入口设计#

1
agentLoop()        → 新对话开始，添加新消息到上下文
2
agentLoopContinue() → 从现有上下文继续，用于重试场景

记忆口诀：一个入口两种模式 —— 新建或继续

1.2 双层循环架构#

1
外层循环 (while true)
2
├── 处理 follow-up messages(循环后的额外消息)
3
└── 内层循环 (while hasMoreToolCalls || pendingMessages)
4
    ├── 处理 steering messages(转向消息)
5
    ├── 流式获取 assistant 响应
6
    ├── 执行工具调用
7
    └── 检查终止条件

记忆口诀：外层管消息队列，内层管执行流程

1.3 三种消息注入机制#

1.4 工具执行两种模式#

1
// 并行执行(默认)
2
executeToolCallsParallel() → Promise.all() 同时执行
3

4
// 串行执行
5
executeToolCallsSequential() → for...of 顺序执行

触发条件：

• config.toolExecution === "sequential"
• 任一工具的 executionMode === "sequential"

1.5 工具执行三阶段#

1
prepareToolCall()
2
├── 参数验证
3
├── beforeToolCall 钩子
4
└── 返回 prepared/immediate
5

6
executePreparedToolCall()
7
├── tool.execute()
8
└── 发送 partial update 事件
9

10
finalizeExecutedToolCall()
11
├── afterToolCall 钩子
12
└── 修改/增强结果

问题 1：重试时如何保持上下文？#

场景：LLM 返回错误，需要重试但不能丢失已执行的工具结果。

抽象：状态连续性问题 —— 如何在不重新开始的情况下继续执行？

解决原则：

• 分离”新建”和”继续”两种入口
• 继续时验证最后一消息不是 assistant(必须是 user 或 toolResult)
• 保持 context.messages 不变，只追加新消息

问题 2：流式响应如何实时更新？#

场景：LLM 流式返回 token，需要实时显示进度。

抽象：部分状态管理 —— 如何在数据不完整时管理状态？

解决原则：

• 使用 partial message 表示不完整状态
• 每次事件到来时替换 context.messages[-1]
• 区分 message_start(初始)、message_update(增量)、message_end(完整)

1
// 关键模式：就地更新
2
context.messages[context.messages.length - 1] = partialMessage;

问题 3：工具调用何时并行、何时串行？#

场景：读取文件的工具可以并行，但创建 git commit 的工具需要串行。

抽象：依赖关系建模 —— 如何表达工具间的依赖？

解决原则：

• 工具级别配置 executionMode
• 混合模式检测：任一 sequential → 全部串行
• 保持结果顺序与调用顺序一致

问题 4：如何在循环中注入外部指令？#

场景：用户在 agent 执行过程中输入新指令，需要改变方向。

抽象：控制流中断 —— 如何在不可中断的操作中注入控制？

解决原则：

• Steering messages：在每个 turn 之前检查，用于改变方向
• Follow-up messages：在循环结束时检查，用于延续任务
• 分离”注入点”和”执行点”

1
// 注入点设计
2
pendingMessages = (await config.getSteeringMessages?.()) || [];
3
// 执行点设计
4
for (const message of pendingMessages) {
5
    currentContext.messages.push(message);
6
}

问题 5：API Key 过期怎么办？#

场景：长时间运行的 agent，API key 可能中途过期。

抽象：凭证生命周期管理 —— 动态资源获取。

解决原则：

• 每次调用前通过 getApiKey() 动态获取
• 回退机制：resolvedApiKey = await getApiKey() || config.apiKey

开场：一句话概括#

“Agent Loop 是一个事件驱动的对话循环，它管理 LLM 和工具之间的交互，通过双层循环处理用户干预，通过三阶段执行保证工具调用的可控性。“

核心架构图(手绘风格)#

1
用户输入
2
   │
3
   ▼
4
┌─────────────────────────────────┐
5
│  agentLoop / agentLoopContinue  │
6
└─────────────────────────────────┘
7
   │
8
   ▼
9
┌─────────────────────────────────┐
10
│  外层循环：follow-up 消息检查     │◄────────┐
11
└─────────────────────────────────┘         │
12
   │                                        │
13
   ▼                                        │
14
┌─────────────────────────────────┐         │
15
│  内层循环：工具调用执行           │         │
16
│  ├─ steering messages 注入      │         │
17
│  ├─ 流式 assistant 响应          │         │
18
│  ├─ 工具执行(并行/串行)          │         │
19
│  └─ 终止条件检查                  │         │
20
└─────────────────────────────────┘         │
21
   │                                        │
22
   ▼                                        │
23
有 follow-up？ ───── 是 ────────────────────┘
24
   │
25
   否
26
   ▼
27
 结束

面试高频问题#

1
prepare    → 验证 + 钩子干预(可以阻止执行)
2
execute    → 真正执行 + 实时更新
3
finalize   → 结果增强(可以修改返回内容)

1
// 两种路径
2
case "start":
3
    context.messages.push(partial);  // 添加占位
4
case "done":
5
    context.messages[-1] = final;    // 替换为完整

4.1 事件流模式#

定义：将异步操作建模为事件序列，消费者通过事件类型响应。

好处：

• UI 可以细粒度响应
• 易于测试和调试
• 支持中间状态持久化

4.2 钩子链模式#

定义：在操作前后插入自定义逻辑。

钩子点：

• beforeToolCall：权限检查、参数修改、阻止执行
• afterToolCall：结果修改、日志、清理
• prepareNextTurn：上下文压缩、模型切换
• transformContext：消息过滤、重排序

4.3 延迟执行模式#

定义：将异步操作表示为函数，按需执行。

好处：

• 统一处理立即结果和异步操作
• 支持并行优化
• 保持顺序一致性

卡片 1：双入口#

• agentLoop：新建对话
• agentLoopContinue：继续对话(最后一消息必须是 user/toolResult)

卡片 2：双层循环#

• 外层：follow-up 消息(延续任务)
• 内层：toolCalls + steering 消息(自主执行)

卡片 3：三阶段工具执行#

• prepare：验证 + 钩子(可阻止)
• execute：执行 + 实时更新
• finalize：结果增强

卡片 4：三种消息注入#

• prompts：启动时
• steering：每 turn 前
• follow-up：循环结束时

卡片 5：两种工具执行#

• parallel：Promise.all(默认)
• sequential：for…of(工具配置或全局配置)