AI Agent 框架搭建指南：ReAct 模式与工具调用

常用模板：

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

{tools}

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 [{tool_names}]
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!

Question: {input}
Thought:{agent_scratchpad}

搭建一个 ReAct 框架

简单的 ReAct

先对各组件进行硬编码。我们为大模型提供一个 get_word_length 工具（Tool），使用 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

注意！这里只是简单在用大模型调试 prompt，get_word_length 工具并没有具体的代码实现也没有运行。之所以能算出结果都是靠大模型自身的推理能力！

Agent

Agent 相当于整体框架的思维推理系统，通常由大模型、Prompt 提供支持。不同的智能体有不同的推理提示风格、不同的输入方式以及不同的解析输出方式，依赖于用户对应用的自定义，说白了就是对大模型进行一层封装更方便管理。

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

这里我使用的是 OpenAI 的 GPT-3.5-turbo 模型。

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
  }
}

Agent Inputs 代理输入

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

Agent Outputs 代理输出

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

对大模型的输入可以是普通的 Prompt 字符串；也可以是键值对，结合 Prompt Template 拼接出最终的 Prompt 字符串。我们这里使用 ReAct 框架，每次输入的 Prompt 都有固定的模板 Template（见上文 ReAct 的模板）。因此需要一个填充模板的函数，我们简单约定变量按 {var} 的格式插入，用正则表达式将字符串替换。

function fillPromptTemplate(promptTemplate: string, inputs: promptInputs) {
  let res = promptTemplate

  for (const [key, val] of Object.entries(inputs))
    res = res.replaceAll(new RegExp(`{\\s*${key}\\s*}`, 'g'), val)

  return res
}

Action

AgentAction 代理行动

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

AgentFinish 代理完成

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

Intermediate Steps 中间步骤

这些代表先前的代理操作以及当前代理运行的相应输出。这些对于传递到未来的迭代非常重要，因此代理知道它已经完成了哪些工作。其类型为 List[Tuple[AgentAction, Any]]。请注意，观察目前保留为 Any 类型，以实现最大程度的灵活性。实际上，这通常是一个字符串。

Tool

在 Prompt 中描述工具

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
}

工具类有 name 和 description 两个属性，通过 getSchema 函数返回对该工具的文本描述。这里我们先简单地将两个描述信息拼接一下，为 Agent 提供 4 个算数工具。

注意！这里只是简单在用大模型调试 prompt，这几个工具并没有具体的代码实现也没有运行。之所以能算出结果都是靠大模型自身的推理能力！（简单的加减乘除即使没有外部工具他也能做到）

1. Addition Tool: A tool for adding two numbers
2. Subtraction Tool: A tool for subtracting two numbers
3. Division Tool: A tool for dividing two numbers
4. Multiplication Tool: A tool for multiplying two numbers

简单地运行一个应用算术题：

尽管 Agent 经过多步思考成功解决了这个问题，但有个小 bug，在第二步中，Agent 调用乘法工具传入了 3 个参数。如果我们实现工具的时候函数只接受两个参数这里就会报错。

出现这个问题是因为我们提供的工具描述还不够准确，不仅要提供工具的名字和功能描述，最好的就是将函数的声明也带上。因为我们的函数代码本身是硬编码的，要尽一切可能降低大模型输出的随机性，严格按我们的要求输出。

为工具函数生成函数声明

方案一：手动 Copy

一个笨办法就是直接 copy 自己写的函数声明，硬编码到工具的 description 中。

按两下 cv 键还是很快的。缺点就是 1. 不够灵活，修改函数声明时需要把硬编码的字符串也更改 2. 万一写的是宽松类型的代码（js、python），还得自己想函数声明。

例如对于 call 函数，直接把这个复制下来放到 description 中就行了。

方案二：AI 自动生成

根据'大模型不收敛'定理——当你想为大模型做一件事时，先想想这件事本身是不是也能让大模型做。我们也可以让大模型为工具函数生成函数声明。

使用下面的 prompt：

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

同理也可以帮助生成函数功能描述。

请用一两句话描述下面{language}代码的功能：
{code}

该方案的优缺点和方案一相同。主要针对宽松类型的代码，省了点脑子。

方案三：zod 自动生成

Zod 是一个以 TypeScript 为首的模式声明和验证库，弥补了 TypeScript 无法在运行时进行校验的问题。

依靠 zod 的一些插件，我们可以直接将 zod 定义的类型对象转换成类型声明字符串。

• zod-to-ts: Generate TypeScript definitions from Zod schemas.
• zod-to-json-schema
• zod-to-openapi: Generate full OpenAPI (Swagger) docs from Zod, including schemas, endpoints & parameters.

根据自己应用联调的需求选择即可。

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

将函数声明加入 Prompt 后，可以看到 Agent 学会了多次进行乘法，符合我们的函数声明。

如果大模型实在是笨的学不会传入正确数量的参数，那就只能将我们的工具函数修改为兼容动态参数的形式了。

Executor

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

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

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

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

1. 根据之前已经完成的所有步骤（一个步骤包括 ReAct 框架中的 Thought、Action、Observation）和 目标（用户的问题）规划出接下来的 Action（使用什么工具 以及 工具的输入）。
2. 检测是否已经达成目标，即 Action 是不是 ActionFinish。是的话就返回结果，不是的话说明还有行动要完成。
3. 根据 Action，执行具体的工具，等待工具返回结果。工具返回的结果就是这一轮步骤的 Observation。
4. 保存当前步骤到记忆上下文，如此反复。

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

    const steps: AgentStep[] = []
    let iterations = 0

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

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

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

      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: '',
    }
  }

运行

这里我们为大模型提供了加减乘除四个工具（按理来说这四个工具不需要实际的函数大模型也可以执行 hhhh，但本质上是不一样的）我们可以看到大模型最后成功迭代出了计算结果为 9336 元。

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', async () => {
    const res = await executor.call({ input: '一种减速机的价格是 750 元，一家企业需要购买 12 台。每台减速机运行一小时的电费是 0.5 元，企业每天运行这些减速机 8 小时。请计算企业购买及一周运行这些减速机的总花费。' })
    expect(res).toMatchInlineSnapshot(`
      {
        "log": "Final Answer: The total cost of purchasing and operating the gearboxes for a week is 9336 yuan.",
        "returnValues": {
          "output": "The total cost of purchasing and operating the gearboxes for a week is 9336 yuan.",
        },
      }
    `)
  }, { timeout: 50000 })
})

可改进的地方

处理代理选择不存在的工具的情况

加入更复杂的记忆 Memory 系统

多个 Agent 合作

更复杂的工具，在一个 Action 中调用多个工具

处理工具错误的情况

处理代理生成无法解析为工具调用的输出的情况

所有级别（代理决策、工具调用）的日志记录和可观察性到标准输出

最佳实践与总结

在实际生产环境中构建 Agent 框架时，除了上述基础组件外，还需要考虑安全性与稳定性。

首先，工具调用必须经过严格的权限校验，防止恶意 Prompt 注入导致意外执行敏感操作。其次，Memory 系统的设计应支持增量更新和过期清理，避免上下文窗口溢出。此外，建议引入重试机制和超时控制，当工具调用失败时能够自动降级或提示用户。

最后，Agent 的可观测性至关重要。开发者应记录每一步的 Thought、Action 和 Observation，以便在出现问题时进行调试和分析。通过完善的日志系统，可以快速定位是 Prompt 设计问题、工具实现问题还是模型推理偏差。

综上所述，AI Agent 框架的搭建是一个系统工程，需要平衡模型的推理能力与外部工具的执行力。通过 ReAct 等框架的结合，我们可以构建出既具备逻辑推理能力又能与真实世界交互的智能体。随着技术的演进，未来 Agent 将更加智能化，能够自主规划复杂任务并协作解决问题。