从零搭建 AI Agent 框架：原理、ReAct 与实现

3. 搭建一个 ReAct 框架

3.1 简单的 ReAct 实现

先对各组件进行硬编码。我们为大模型提供一个 get_word_length 工具，使用 ReAct 框架看看它能否解决一些基本问题。

System Prompt：

Answer the following questions as best you can. You have access to the following tools:

get_word_length(word: str) -> int:
    """Returns the length of a word."""

Use the following format:
Question: the input question you must answer
Thought: you should always think about what to do
Action: the action to take, should be one of [get_word_length]
Action Input: the input to the action
Observation: the result of the action
... (this Thought/Action/Action Input/Observation can repeat N times)
Thought: I now know the final answer
Final Answer: the final answer to the original input question

Begin!

User Input：

Question: How many letters in the word educa

注意：在实际调试阶段，如果工具未具体实现，大模型可能依靠自身推理能力估算结果。但在生产环境中，必须确保工具的真实可用性。

3.2 Agent 类设计

Agent 相当于整体框架的思维推理系统，通常由大模型、Prompt 提供支持。不同的智能体有不同的推理提示风格、不同的输入方式以及不同的解析输出方式。

这里提到的 Agent 其实就是大模型本身，我们在框架中最好将大模型的 API 进行面向对象的封装，方便与框架中其他组件交互。

interface LLMSingleActionAgentParams {
  llm: AzureLLM;
  tools?: StructuredTool[];
  stop?: string[];
}

class LLMSingleActionAgent {
  llm: AzureLLM;
  tools: StructuredTool[];
  stop: string[];
  private _prompt: string = '{input}';

  constructor({ llm, tools = [], stop = [] }: LLMSingleActionAgentParams) {
    this.llm = llm;
    this.tools = tools;
    if (stop.length > 4) {
      throw new Error('up to 4 stop sequences');
    }
    this.stop = stop;
  }

  setPrompt(prompt: string): void {
    this._prompt = prompt;
  }

  async plan(steps: any[], input: string): Promise<any> {
    // 实际实现需调用 LLM API
    return {};
  }
}

3.2.1 Agent Inputs 代理输入

对大模型的输入可以是普通的 Prompt 字符串；也可以是键值对，结合 Prompt Template 拼接出最终的 Prompt 字符串。

3.2.2 Agent Outputs 代理输出

输出是要执行的下一个操作或要发送给用户的最终响应（AgentAction 或 AgentFinish）。

我们需要填充模板的函数，约定变量按 {var} 的格式插入，用正则表达式将字符串替换：

function fillPromptTemplate(promptTemplate: string, inputs: Record<string, any>): string {
  let res = promptTemplate;
  for (const [key, val] of Object.entries(inputs)) {
    res = res.replaceAll(new RegExp(`\\{\\s*${key}\\s*}`, 'g'), val);
  }
  return res;
}

3.3 Action 定义

3.3.1 AgentAction 代理行动

这是一个数据类，表示代理应采取的操作。它有一个 tool 属性（这是应该调用的工具的名称）和一个 tool_input 属性（该工具的输入）。

3.3.2 AgentFinish 代理完成

这表示代理准备好返回给用户时的最终结果。它包含一个 return_values 键值映射，其中包含最终的代理输出。通常，这包含 output 键，其中包含代理响应的字符串。

3.3.3 Intermediate Steps 中间步骤

这些代表先前的代理操作以及当前代理运行的相应输出。这些对于传递到未来的迭代非常重要，因此代理知道它已经完成了哪些工作。其类型为 List<Tuple[AgentAction, Any]>。

4. 工具（Tool）管理

4.1 在 Prompt 中描述工具

工具类有 name 和 description 两个属性，通过 getSchema 函数返回对该工具的文本描述。

export abstract class StructuredTool {
  name: string;
  description: string;

  constructor(name: string, description: string) {
    this.name = name;
    this.description = description;
  }

  abstract call(arg: string, config?: Record<string, any>): Promise<string>;

  getSchema(): string {
    return `${this.declaration} | ${this.name} | ${this.description}`;
  }

  abstract get declaration(): string;
}

为了降低大模型输出的随机性，不仅要提供工具的名字和功能描述，最好的就是将函数的声明也带上。

4.2 为工具函数生成函数声明

方案一：手动 Copy

直接 copy 自己写的函数声明，硬编码到工具的 description 中。缺点是不够灵活，修改函数声明时需要把硬编码的字符串也更改。

方案二：AI 自动生成

根据"大模型不收敛"定理，我们可以让大模型为工具函数生成函数声明。

Prompt 示例：

请为下面的{language}代码生成函数声明：
{code}

方案三：Zod 自动生成

Zod 是一个以 TypeScript 为首的模式声明和验证库，弥补了 TypeScript 无法在运行时进行校验的问题。依靠 Zod 的一些插件，我们可以直接将 Zod 定义的类型对象转换成类型声明字符串。

优点是非常灵活，且支持运行时。唯一的缺点是需要学习 Zod 的用法。

将函数声明加入 Prompt 后，可以看到 Agent 学会了多次进行乘法，符合我们的函数声明。如果大模型实在无法传入正确数量的参数，可以将工具函数修改为兼容动态参数的形式。

5. 执行器（Executor）

代理执行器 executor 是 Agent 的运行时，可以理解为 AI Agent 的大脑，它协调各个组件并指导操作。这实际上是调用代理，执行它选择的操作，将操作输出传递回代理，然后重复。

class AgentExecutor {
  agent: LLMSingleActionAgent;
  tools: StructuredTool[] = [];
  maxIterations: number = 15;

  constructor(agent: LLMSingleActionAgent) {
    this.agent = agent;
  }

  addTool(tools: StructuredTool | StructuredTool[]): void {
    const _tools = Array.isArray(tools) ? tools : [tools];
    this.tools.push(..._tools);
  }

  async call(input: Record<string, any>): Promise<any> {
    const toolsByName = Object.fromEntries(
      this.tools.map(t => [t.name, t]),
    );

    const steps: any[] = [];
    let iterations = 0;

    while (this.shouldContinue(iterations)) {
      const output = await this.agent.plan(steps, input.input);
      console.log(iterations, output);

      // Check if the agent has finished
      if ('returnValues' in output) {
        return output;
      }

      const actions = Array.isArray(output)
        ? output
        : [output];

      const newSteps = await Promise.all(
        actions.map(async (action) => {
          const tool = toolsByName[action.tool];

          if (!tool) {
            throw new Error(`${action.tool} is not a valid tool, try another one.`);
          }

          const observation = await tool.call(action.toolInput);
          return { action, observation: observation ?? '' };
        }),
      );

      steps.push(...newSteps);
      iterations++;
    }

    return {
      returnValues: { output: 'Agent stopped due to max iterations.' },
      log: '',
    };
  }

  private shouldContinue(iterations: number): boolean {
    return iterations < this.maxIterations;
  }
}

最关键的就是 executor 的执行循环了，executor 会始终进行如下事件循环直到目标被解决了或者思考迭代次数超过了最大次数：

1. 根据之前已经完成的所有步骤和目标规划出接下来的 Action。
2. 检测是否已经达成目标，即 Action 是不是 AgentFinish。是的话就返回结果，不是的话说明还有行动要完成。
3. 根据 Action，执行具体的工具，等待工具返回结果。工具返回的结果就是这一轮步骤的 Observation。
4. 保存当前步骤到记忆上下文，如此反复。

6. 运行测试

这里我们为大模型提供了加减乘除四个工具。我们可以看到大模型最后成功迭代出了计算结果。

describe('agent', () => {
  const llm = new AzureLLM({
    apiKey: Config.apiKey,
    model: Config.model,
  });
  const agent = new LLMSingleActionAgent({ llm });
  agent.setPrompt(REACT_PROMPT);
  agent.addStop(agent.observationPrefix);
  agent.addTool([
    new AdditionTool(),
    new SubtractionTool(),
    new DivisionTool(),
    new MultiplicationTool()
  ]);

  const executor = new AgentExecutor(agent);
  executor.addTool([
    new AdditionTool(),
    new SubtractionTool(),
    new DivisionTool(),
    new MultiplicationTool()
  ]);

  it('test calculation', async () => {
    const res = await executor.call({ 
      input: '一种减速机的价格是 750 元，一家企业需要购买 12 台。每台减速机运行一小时的电费是 0.5 元，企业每天运行这些减速机 8 小时。请计算企业购买及一周运行这些减速机的总花费。' 
    });
    expect(res.returnValues.output).toContain('9336');
  }, { timeout: 50000 });
});

7. 可改进的方向

虽然基础框架已搭建完成，但在生产环境中还需要考虑以下优化点：

1. 工具不存在处理：增强异常捕获，当代理选择不存在的工具时，应引导其重新选择而非直接报错崩溃。
2. 记忆系统：加入更复杂的 Memory 系统，支持向量数据库检索，以便处理长上下文任务。
3. 多 Agent 协作：支持多个 Agent 合作，分工处理不同子任务。
4. 并行工具调用：在一个 Action 中尝试调用多个工具，提高效率。
5. 错误恢复：处理工具调用失败的情况，增加重试机制。
6. 输出解析：处理代理生成无法解析为工具调用的输出的情况，增加容错逻辑。
7. 日志与可观测性：所有级别（代理决策、工具调用）的日志记录和可观察性应输出到标准输出或监控平台，便于调试。

8. 总结

本文详细讲解了如何从零搭建一个基于 ReAct 模式的 AI Agent 框架。通过拆解 Planning、Memory、Tool 三大核心组件，并结合 CoT 推理方法，实现了具备自主规划能力的智能体。代码部分展示了如何使用 TypeScript 封装 Agent 和 Executor，以及如何规范工具定义以减少幻觉。掌握这些技术有助于开发者构建更强大的自动化应用，应对复杂的业务场景。