您的位置: 首页> AI模型

手搓 AI Agent：从零构建能自动写代码、跑命令的“数字员工”

匿名上传

发布时间:2026-02-28 17:00:01

一、为什么我们需要“手搓”Agent？

在 LangChain、AutoGen 等框架层出不穷的今天，为什么还要坚持“手搓”？

因为框架封装了细节，也屏蔽了灵魂。

当你调用 agent.run() 时，你看到的只是一个结果。你看不见大模型是如何决定调用工具的，看不见工具执行失败后它是如何“反思”的，更看不见那个让 AI 从“聊天机器人”进化为“智能体”的核心引擎——ReAct 循环（Reasoning + Acting） 。

手搓 Agent 的意义在于：

掌控力：完全控制工具的边界、错误处理逻辑和上下文传递机制。
理解深度：亲手实现 while 循环中的消息流转，才能真正理解 Agent 的“思考”过程。
定制化：你可以轻松加入日志染色、执行沙箱、权限控制等企业级需求，而不受框架限制。

今天，我们就用不到 200 行核心代码，揭开 AI Agent 的神秘面纱。

二、核心架构：赋予 AI“手脚”与“大脑”

一个完整的 Agent 系统由三部分组成：

大脑（LLM） ：负责推理、规划和决策。
手脚（Tools） ：负责执行具体操作（读写文件、运行命令）。
神经系统（Loop） ：负责连接大脑与手脚，形成“感知 - 决策 - 行动”的闭环。

1. 打造“手脚”：定义原生工具

在 Node.js 环境中，最强大的能力莫过于操作文件系统和执行 Shell 命令。我们利用 node:fs/promises 和 node:child_process 模块，结合 LangChain 的 tool 函数，定义了四个核心工具。

关键设计点：

Zod Schema 校验：每个工具都通过 Zod 定义严格的输入参数 schema。这不仅防止了 AI 生成错误的参数格式，还为 LLM 提供了清晰的“工具说明书”。
防御性编程：所有文件操作都包裹在 try-catch 中。AI 可能会尝试读取不存在的文件，或者写入权限不足的目录，工具必须优雅地返回错误信息，而不是让进程崩溃。
自动创建目录：在 write_file 工具中，我们使用了 fs.mkdir(dir, { recursive: true })。这意味着 AI 可以直接写入 /src/components/Button.tsx，即使中间目录不存在，系统也会自动创建。这对代码生成场景至关重要。

// 核心逻辑示意：写入文件工具
const writeFileTool = tool(
  async ({ filePath, content }) => {
    const dir = path.dirname(filePath);
    // 递归创建目录，确保路径存在
    await fs.mkdir(dir, { recursive: true });
    await fs.writeFile(filePath, content, 'utf-8');
    return `文件写入成功: ${filePath}`;
  },
  {
    name: 'write_file',
    description: '向指定路径写入文件内容，自动创建目录',
    schema: z.object({
      filePath: z.string().describe('文件路径'),
      content: z.string().describe('要写入的文件内容'),
    }),
  }
);

️ 避坑指南：命令执行工具的陷阱

在实现 execute_command 时，初学者常犯两个致命错误：

直接 process.exit：如果命令执行失败（如 npm install 报错），直接退出进程会导致 Agent 死亡。正确的做法是将错误输出作为字符串返回给 LLM，让它自行分析并尝试修复。
忽略工作目录：很多命令依赖于当前路径。我们通过 workingDirectory 参数显式指定 cwd，并在 System Prompt 中严厉禁止 AI 在命令中混用 cd，避免了路径混乱。

2. 激活“大脑”：绑定工具与上下文

有了工具，如何让大模型知道它们的存在？

LangChain 提供了 model.bindTools(tools) 方法。这行代码看似简单，实则完成了复杂的“神经连接”：

它将工具的元数据（名称、描述、参数 Schema）注入到模型的 System Prompt 中。
它修改了模型的输出解析器，使其能够识别并生成特殊的 tool_calls 结构，而不仅仅是普通文本。

const modelWithTools = model.bindTools(tools);

此时，modelWithTools 不再是一个普通的聊天模型，而是一个随时准备调用工具的智能体代理。

三、灵魂引擎：手写 ReAct 循环

这是整个 Agent 最核心的部分。如果没有这个循环，AI 只能调用一次工具就停止，无法完成多步骤任务。

我们在 runAgentWithTools 函数中实现了一个经典的 ReAct 循环：

for (let i = 0; i < maxIterations; i++) {
  // 1. 思考 (Reasoning)
  const response = await modelWithTools.invoke(messages);
  messages.push(response);

  // 2. 判断是否结束
  if (!response.tool_calls || response.tool_calls.length === 0) {
    return response.content; // 没有工具调用，说明任务完成，返回最终回复
  }

  // 3. 行动 (Acting) & 观察 (Observation)
  for (const toolCall of response.tool_calls) {
    const toolResult = await foundTool.invoke(toolCall.args);
    // 将工具执行结果作为“观察”反馈给模型
    messages.push(new ToolMessage(toolResult, toolCall.id));
  }
}

循环的三个阶段详解：

思考 (Reasoning) ：
模型接收当前的 messages 数组（包含用户指令、历史对话、之前的工具执行结果）。它分析现状，决定下一步该做什么。如果需要工具，它会输出一个包含 tool_calls 的消息。
行动 (Acting) ：
主程序检测到 tool_calls，遍历每一个调用，找到对应的工具函数并执行。这是 AI 真正“动手”的时刻——文件被创建，命令被运行。
观察 (Observation) ：
工具执行完毕后，返回结果（无论是成功的内容还是失败的报错）。我们将这些结果封装成 ToolMessage，再次推入 messages 数组。
关键点：这一步相当于把“眼睛”看到的结果喂回给“大脑”。模型看到报错信息后，会在下一轮循环中调整策略（例如：“安装失败了，可能是源的问题，我换个源再试一次”）。

这个循环不断迭代，直到模型认为任务完成（不再调用工具）或达到最大迭代次数。

四、实战演练：从 0 到 1 开发 React 应用

理论讲得再多，不如看它干点实事。我们给 Agent 下达了一个复杂指令：

Agent 的执行流实录：

第一轮思考：
- 决策：需要先创建项目骨架。
- 行动：调用 execute_command，执行 pnpm create vite react-todo-app --template react-ts。
- 观察：命令成功，目录 react-todo-app 已创建。
第二轮思考：
- 决策：进入项目目录安装依赖。注意，这里它严格遵守了规则，使用 workingDirectory: "react-todo-app" 参数，而没有在命令里写 cd。
- 行动：调用 execute_command，执行 pnpm install。
- 观察：依赖安装完成。
第三轮思考：
- 决策：需要修改 src/App.tsx 实现业务逻辑。
- 行动：先调用 read_file 读取原有代码（了解结构），然后调用 write_file 写入包含完整逻辑（State 管理、LocalStorage、筛选逻辑）的新代码。
- 观察：文件写入成功。
第四轮思考：
- 决策：添加 CSS 样式和动画。
- 行动：调用 write_file 修改 App.css，加入渐变背景、卡片阴影和 Keyframes 动画。
- 观察：样式更新成功。
第五轮思考：
- 决策：验证项目结构并启动。
- 行动：调用 list_directory 确认文件无误，最后调用 execute_command 执行 pnpm run dev。
- 观察：服务器启动成功，输出 Localhost 地址。
最终回复：
- 模型检测到无需更多操作，输出：“React TodoList 应用已创建并启动，访问查看。功能包含...（简述）”。