第 7 课：实现 Agent Loop，让工具调用进入多轮任务流程

前言

第 6 课把 ToolExecutor 封装出来以后，工具调用这条线已经比第 5 课清楚很多了。

但第 6 课还有一个限制：它仍然是“一次模型调用 + 一次工具执行 + 一次最终回答”。这对简单问题够用，比如查一个知识库条目，或者直接创建一个工单。

真正的 Agent 任务往往不是一步完成的。

比如用户说：

先查一下 RAG 检索效果不好怎么办，然后基于查询结果帮我创建一个中优先级工单。

这里至少有两步：先查知识库，再根据查询结果创建工单。模型要看见第一步的工具结果，才能决定第二步怎么做。

这就是第 7 课要解决的问题：实现一个基础 Agent Loop。

本节源码目录在这里：

https://github.com/zhaomin6666/agent-demo/tree/main/src/lessons/lesson07-agent-loop

本节要解决什么问题

第 6 课的流程是固定的：

调用模型
  ↓
执行 tool_calls
  ↓
再次调用模型
  ↓
输出最终回答

第 7 课把它改成循环：

调用模型
  ↓
如果有 tool_calls，执行工具
  ↓
把 ToolMessage 放回 messages
  ↓
继续调用模型
  ↓
直到模型不再返回 tool_calls

这就是 Agent Loop 的最小形态。

它让模型不只是调用一次工具，而是可以围绕任务连续判断下一步。模型每一轮看到的上下文都会增加：用户输入、前一次模型的工具调用、工具执行结果，以及前面所有轮次的消息。

这一课还有一个变化：开始拆目录

第 7 课不只是写循环，还开始把前几课堆在 index.ts 里的代码拆开。

目录结构变成这样：

lesson07-agent-loop/
  agent/
    agent-loop.ts
  data/
    knowledge-docs.ts
  executor/
    tool-executor.ts
  model/
    create-model.ts
  tools/
    create-ticket.tool.ts
    search-knowledge-base.tool.ts
    index.ts
  index.ts
  README.md
  output.txt

这个变化很实际。前几课单文件是为了学习方便，所有东西摊在一起，看流程最清楚。但继续往后做 LangGraph、RAG、API、前端和 Memory，单文件肯定撑不住。

从这一课开始，代码开始有一点真实项目的样子：

agent 负责编排
executor 负责工具执行
tools 负责具体工具
model 负责模型创建
data 负责模拟数据
index.ts 负责组装和运行

这种拆法对 Java 后端开发者很友好，基本能对应到熟悉的分层。

工具和执行器沿用上一课，但有一个细节变化

这一课没有新增工具，仍然是：

search_knowledge_base：查询企业 AI 知识库
create_ticket：创建技术支持工单

ToolExecutor 也基本沿用第 6 课，只是移动到 executor/tool-executor.ts。

更关键的变化在 create_ticket 的工具描述上，这一课多加了一句：

如果用户要求先查询知识库再创建工单，应先等待知识库查询结果，再调用本工具。

这句话看起来不起眼，但对 Agent Loop 很重要。

工具描述不是给开发者看的普通注释，而是模型选择工具时会读到的上下文。现在我们希望模型在多步任务里先查再建工单，就需要在系统提示和工具描述里同时给它这个方向。

这也提醒我一件事：Agent 的控制流不只写在 TypeScript 代码里，也写在 Prompt 和 tool description 里。两边都要设计。

AgentLoop 的输入和返回结果

第 7 课新增的核心类是 AgentLoop。

它先定义了几个类型：

export type AgentLoopOptions = {
  maxIterations: number;
};

export type AgentLoopStopReason = "final_answer" | "max_iterations";

export type AgentLoopResult = {
  finalMessage: AIMessage;
  messages: BaseMessage[];
  iterations: number;
  stopReason: AgentLoopStopReason;
  toolExecutionRecords: ToolExecutionRecord[];
};

这里我最关注两个字段：stopReason 和 toolExecutionRecords。

stopReason 说明 Agent 为什么停下来。是模型已经给出最终回答，还是达到最大轮次被强制停止。

toolExecutionRecords 则把所有轮次的工具执行记录汇总起来。第 6 课只记录一次工具执行，第 7 课开始记录整个循环过程。后面如果做 Trace，这个字段会很自然地演进成一条执行轨迹。

Agent Loop 主体逻辑

核心循环在 agent/agent-loop.ts：

for (let iteration = 1; iteration <= this.options.maxIterations; iteration++) {
  const aiMessage = await this.modelWithTools.invoke(messages);

  messages.push(aiMessage);

  const toolCalls = aiMessage.tool_calls ?? [];

  if (toolCalls.length === 0) {
    return {
      finalMessage: aiMessage,
      messages,
      iterations: iteration,
      stopReason: "final_answer",
      toolExecutionRecords,
    };
  }

  const executionResult = await this.toolExecutor.execute(toolCalls);

  toolExecutionRecords.push(...executionResult.records);

  messages.push(...executionResult.messages);
}

这段代码不复杂，但把 Agent 的基本形态写出来了。

每一轮都做同一件事：

让模型看当前 messages
如果模型要调用工具，就执行工具
把工具结果放回 messages
进入下一轮

什么时候结束？

模型不再返回 tool_calls

这时说明模型认为工具结果已经足够，开始输出最终回答。

为什么必须有 maxIterations

只要有循环，就必须有退出保护。

Agent Loop 尤其需要这个保护，因为模型可能反复调用同一个工具。比如第一轮查知识库，第二轮又查同样的关键词，第三轮还继续查。没有最大轮次限制，程序就可能一直跑下去。

第 7 课在创建 AgentLoop 时传入：

const agentLoop = new AgentLoop(modelWithTools, toolExecutor, {
  maxIterations: 5,
});

如果超过最大轮次，代码会构造一个兜底的 AIMessage：

const finalMessage = new AIMessage({
  content:
    "已达到最大工具调用轮次。为避免 Agent 陷入循环，本次流程已停止。请简化问题或稍后重试。",
});

这个设计并不复杂，但很有必要。

在后端系统里，重试要有最大次数，轮询要有超时，任务队列要有失败状态。Agent Loop 也是一样，不能因为多了模型就允许无限循环。

入口文件只负责组装

拆分目录后，index.ts 变得很轻。省略前面课程已经讲过的模型创建部分，核心组装大概是这样：

const modelWithTools = model.bindTools(tools) as ToolCallingModel;

const toolExecutor = new ToolExecutor(tools);

const agentLoop = new AgentLoop(modelWithTools, toolExecutor, {
  maxIterations: 5,
});

然后准备三组输入逐个运行。

这就是我更喜欢的结构：入口文件负责把依赖组装起来，真正的业务流程放在 AgentLoop，工具执行放在 ToolExecutor，具体工具放在 tools/。

这种结构后面也更容易迁移到 API 服务里。命令行入口可以换成 HTTP Controller，但 AgentLoop 和 ToolExecutor 不需要跟着重写。

NodeNext 下相对导入要写 .js

第 7 课拆目录后，出现了一个很容易踩的小坑：本地相对导入要加 .js 后缀。

比如源码文件是：

agent/agent-loop.ts

导入时要写：

import { AgentLoop } from "./agent/agent-loop.js";

而不是：

import { AgentLoop } from "./agent/agent-loop";

原因是项目使用 NodeNext / Node16 这类 ESM 解析规则。TypeScript 源码虽然是 .ts，但运行时看的是编译后的 .js 文件。

这个点和 Agent 本身关系不大，但实际写 TypeScript ESM 项目时会经常遇到。第 7 课正好借着模块拆分把这个规则固定下来：本地相对路径加 .js，第三方包不加。

运行结果

本节目录存在 output.txt，记录了三组真实运行结果。

第一组：查询数据源接入

输入是：

我们的企业知识库支持哪些数据源接入？

第 1 轮，模型调用 search_knowledge_base，参数是：

{
  "query": "数据源接入"
}

工具执行成功，但结果为空：

{
  "query": "数据源接入",
  "count": 0,
  "results": []
}

第 2 轮，模型不再调用工具，而是给出最终回答。停止原因是：

final_answer

循环轮次是 2。

这个结果说明 Agent Loop 已经生效：第一轮工具调用，第二轮基于工具结果回答。只是检索仍然没有命中，这还是简单字符串匹配的问题。

第二组：先查 RAG，再创建工单

这组是本节最重要的测试：

先查一下 RAG 检索效果不好怎么办，然后基于查询结果帮我创建一个中优先级工单。

第 1 轮，模型调用 search_knowledge_base：

{
  "query": "RAG 检索效果不好怎么办"
}

这次工具命中了 doc-002，返回内容是：

如果 RAG 检索效果不好，可以从文档切分、Embedding 模型、召回数量、关键词补充、重排序、Prompt 约束等方面优化。

第 2 轮，模型看到了知识库结果，又调用 create_ticket：

{
  "title": "RAG 检索效果优化问题反馈",
  "description": "用户反馈 RAG 检索效果不佳，建议从文档切分、Embedding 模型、召回数量、关键词补充、重排序、Prompt 约束等方面进行优化。请相关团队评估并处理。",
  "priority": "medium"
}

第 3 轮，模型不再返回 tool_calls，而是输出最终回答：已经查询知识库并创建工单，同时整理了知识库建议和工单信息。

这一组完整跑出了多步任务：

第 1 轮：查询知识库
第 2 轮：基于查询结果创建工单
第 3 轮：输出最终回答

这就是第 7 课最想验证的能力。

第三组：PDF 搜索问题创建高优先级工单

输入是：

知识库搜索 PDF 内容经常搜不到，帮我创建一个高优先级工单。

有意思的是，模型没有在第一轮直接创建工单，而是先调用了 search_knowledge_base，查询 "PDF 搜索"，结果为空。

第 2 轮，模型才调用 create_ticket，创建高优先级工单，标题是“知识库搜索 PDF 内容经常搜不到”，优先级为 high。

第 3 轮，模型输出最终回答，停止原因同样是 final_answer。

这个结果说明，当前系统提示和工具描述已经让模型倾向于“先查知识库，再做操作”。这在某些场景是好事，但也提醒我：Agent 的行为会受到 Prompt 强烈影响。用户只是说“帮我创建工单”，模型仍然可能先查一次知识库。后面如果要更精细控制，就不能只靠提示词，还要在编排层做明确策略。

第 7 课和第 6 课的区别

第 6 课的重点是工具执行器：

如何统一执行 tool_calls？
如何处理工具不存在？
如何记录工具执行日志？

第 7 课的重点是流程编排：

模型什么时候继续调用工具？
什么时候停止？
如何避免死循环？
多轮工具执行记录怎么汇总？
代码结构怎么拆到可维护？

换句话说，第 6 课解决的是执行层，第 7 课开始解决编排层。

这两层分开以后，后续引入 LangGraph 会顺很多。因为 LangGraph 要管理的本来就是节点、状态和条件边，而我们现在已经手写出了最小版：

LLM 调用
  ↓
判断 tool_calls
  ↓
ToolExecutor
  ↓
继续 LLM 调用

和 LangGraph 的关系

第 7 课还没有用 LangGraph，但其实已经在手写 LangGraph 会帮我们管理的东西。

现在的循环可以想象成两个节点：

llm_node：调用模型，生成 AIMessage
tool_node：执行工具，生成 ToolMessage

中间有一个条件判断：

如果 AIMessage 有 tool_calls -> 去 tool_node
如果没有 tool_calls -> 结束

这就是后面状态图的雏形。

我现在更能理解为什么课程没有一上来就用 LangGraph。先手写一次循环，会知道状态图到底在抽象什么。否则直接看 StateGraph、节点和边，很容易只是记住框架写法，不知道底层流程为什么需要这样拆。

Java 后端视角理解

从 Java 后端视角看，第 7 课可以类比成一个任务编排服务：

index.ts       -> Controller / 启动入口
AgentLoop      -> AgentService / 编排服务
ToolExecutor   -> ToolExecutorService
tools          -> ToolHandler
data           -> Repository / 模拟数据源
model          -> ModelClient 配置

AgentLoop.run 像一个带最大重试次数的业务流程：

while iteration <= maxIterations:
  调用模型
  如果没有工具调用，返回最终结果
  如果有工具调用，执行工具并追加上下文

这和普通后端里的状态机、审批流、任务编排有点像。区别是每一步下一步做什么，不完全由代码里的固定分支决定，而是由模型根据当前上下文和工具描述生成 tool_calls。

这就是 Agent 有意思也麻烦的地方：流程有工程边界，但中间多了一层模型决策。

这一课暴露出的后续问题

第 7 课已经能跑多步任务，但还只是入门版本。

我觉得后面至少还有几个问题要继续补。

第一，重复工具调用检测。现在系统提示里写了不要重复使用相同参数调用同一个工具，但代码层还没有硬检测。真实项目里最好记录 toolName + args，如果重复多次就强制停止。

第二，高风险工具确认。创建工单风险不高，但如果是删除数据、提交审批、付款、改权限，就不能让 Agent Loop 直接执行。后面需要 Human-in-the-loop。

第三，状态持久化。现在 messages 和工具执行记录都在内存里。真实服务里要考虑会话 ID、用户 ID、请求 ID、流程中断和恢复。

第四，工具策略。第三组输出里，模型先查知识库再建工单，这不一定永远符合业务预期。以后可能需要显式路由策略，而不是只靠 Prompt。

TypeScript Tips

这一课主要有几个工程写法值得记。

import { AgentLoop, type ToolCallingModel } ... 里，type 表示只导入类型，不导入运行时代码。拆模块后这种写法会更常见。

model.bindTools(tools) as ToolCallingModel 是一次类型断言。这里是告诉 TypeScript：绑定工具后的模型符合我们定义的 invoke(messages) 接口。

构造函数里的参数属性写法也很简洁：

constructor(
  private readonly modelWithTools: ToolCallingModel,
  private readonly toolExecutor: ToolExecutor,
  private readonly options: AgentLoopOptions,
) {}

它等价于先声明字段，再在构造函数里赋值。熟悉 Java 的话，可以把它看成构造函数注入依赖。

还有前面提到的 .js 后缀规则。只要项目继续用 NodeNext，本地相对导入就要保持这个习惯。

本节总结

第 7 课做了两个升级。

第一个升级是流程上：从单次 Tool Calling 变成 Agent Loop。模型可以先调用工具，拿到结果后再决定下一步，直到不再返回 tool_calls。

第二个升级是结构上：从单文件 demo 拆成 agent、executor、tools、model、data。这让代码开始接近真实工程，而不是只为一节课演示服务。

真实输出里，第二组输入完整跑出了三轮流程：先查 RAG 优化建议，再创建中优先级工单，最后总结回答。看到这里，我对 Agent Loop 的理解就比只看概念清楚很多。

下一课会进入 LangGraph，把这一课手写的循环改造成状态图。到那时，AgentLoop 里的循环、停止条件、工具节点和消息状态，都会变成更显式的图结构。