快速上手

光说不练

前三章学了概念和模式，但还没有真正跑过一行代码。是时候动手了。

开始之前

项目初始化

三步创建项目并安装依赖

# 创建项目目录
$ mkdir calculator-agent && cd calculator-agent
$ npm init -y

# 安装核心依赖
$ npm install @langchain/langgraph @langchain/core @langchain/deepseek zod

# 安装 TypeScript（如果还没装）
$ npm install -D typescript tsx

📄 完整代码：04_env_setup.ts

定义工具

用 tool() + zod 创建三个数学工具

import { ChatDeepSeek } from "@langchain/deepseek";
import { tool } from "@langchain/core/tools";
import * as z from "zod";

const model = new ChatDeepSeek({
  model: "deepseek-chat",
  temperature: 0,
});

// 加法工具
const add = tool(({ a, b }) => a + b, {
  name: "add",
  description: "Add two numbers",
  schema: z.object({
    a: z.number().describe("First number"),
    b: z.number().describe("Second number"),
  }),
});

// 乘法工具
const multiply = tool(({ a, b }) => a * b, {
  name: "multiply",
  description: "Multiply two numbers",
  schema: z.object({
    a: z.number().describe("First number"),
    b: z.number().describe("Second number"),
  }),
});

// 除法工具
const divide = tool(({ a, b }) => a / b, {
  name: "divide",
  description: "Divide two numbers",
  schema: z.object({
    a: z.number().describe("First number"),
    b: z.number().describe("Second number"),
  }),
});

// 按名称索引工具，绑定到模型
const toolsByName = { [add.name]: add, [multiply.name]: multiply, [divide.name]: divide };
const tools = Object.values(toolsByName);
const modelWithTools = model.bindTools(tools);

📄 完整代码：04_tool_definition.ts

定义状态

MessagesValue 追踪对话，ReducedValue 追踪调用次数

import {
  StateGraph, StateSchema, MessagesValue, ReducedValue,
  GraphNode, ConditionalEdgeRouter, START, END,
} from "@langchain/langgraph";

const MessagesState = new StateSchema({
  // 消息历史 — 内置追加 reducer，新消息自动拼到末尾
  messages: MessagesValue,
  // LLM 调用计数 — 自定义 reducer，每次 +1
  llmCalls: new ReducedValue(
    z.number().default(0),
    { reducer: (x, y) => x + y }
  ),
});

模型节点

调用 LLM，把回复追加到消息历史

import { SystemMessage } from "@langchain/core/messages";

const llmCall: GraphNode<typeof MessagesState> = async (state) => {
  const response = await modelWithTools.invoke([
    new SystemMessage(
      "You are a helpful assistant tasked with performing arithmetic on a set of inputs."
    ),
    ...state.messages,
  ]);
  return {
    messages: [response],  // MessagesValue 自动追加
    llmCalls: 1,            // ReducedValue 累加 +1
  };
};

工具节点

执行模型请求的工具调用，把结果追加到消息历史

import { AIMessage, ToolMessage } from "@langchain/core/messages";

const toolNode: GraphNode<typeof MessagesState> = async (state) => {
  const lastMessage = state.messages.at(-1);

  // 安全检查：最后一条必须是 AI 消息
  if (lastMessage == null || !AIMessage.isInstance(lastMessage)) {
    return { messages: [] };
  }

  // 逐个执行工具调用
  const result: ToolMessage[] = [];
  for (const toolCall of lastMessage.tool_calls ?? []) {
    const tool = toolsByName[toolCall.name];
    const observation = await tool.invoke(toolCall);
    result.push(observation);
  }

  return { messages: result };
};

结束判断

条件边：模型还要调工具吗？

const shouldContinue: ConditionalEdgeRouter<
  typeof MessagesState, "toolNode"
> = (state) => {
  const lastMessage = state.messages.at(-1);

  // 不是 AI 消息 → 结束
  if (!lastMessage || !AIMessage.isInstance(lastMessage)) {
    return END;
  }

  // AI 请求了工具调用 → 去执行工具
  if (lastMessage.tool_calls?.length) {
    return "toolNode";
  }

  // AI 没有请求工具 → 回复用户，结束
  return END;
};

组装智能体

把所有零件拼成一个完整的图

const agent = new StateGraph(MessagesState)
  .addNode("llmCall", llmCall)
  .addNode("toolNode", toolNode)
  .addEdge(START, "llmCall")
  .addConditionalEdges("llmCall", shouldContinue, ["toolNode", END])
  .addEdge("toolNode", "llmCall")
  .compile();

📄 完整代码：04_calculator_agent.ts

运行测试

用一句话启动智能体

import { HumanMessage } from "@langchain/core/messages";

const result = await agent.invoke({
  messages: [new HumanMessage("Add 3 and 4.")],
});

// 打印完整的消息历史
for (const message of result.messages) {
  console.log(`[${message.type}]: ${message.text}`);
}

# 预期输出：
[human]: Add 3 and 4.
[ai]: [调用 add 工具, a=3, b=4]
[tool]: 7
[ai]: The answer is 7.
# llmCalls: 2（模型被调用了两次）

排错指南

动手练习

给计算器智能体加上减法和乘方

• 添加 subtract 工具（a - b）和 power 工具（a ^ b）
• 把它们注册到 toolsByName 并绑定到模型
• 测试 "What is 2 to the power of 10?"，确认智能体能正确调用 power 工具

参考答案

// 减法工具
const subtract = tool(({ a, b }) => a - b, {
  name: "subtract",
  description: "Subtract b from a",
  schema: z.object({
    a: z.number().describe("First number"),
    b: z.number().describe("Second number"),
  }),
});

// 乘方工具
const power = tool(({ a, b }) => Math.pow(a, b), {
  name: "power",
  description: "Raise a to the power of b",
  schema: z.object({
    a: z.number().describe("Base"),
    b: z.number().describe("Exponent"),
  }),
});

// 更新工具注册
const toolsByName = {
  [add.name]: add,
  [multiply.name]: multiply,
  [divide.name]: divide,
  [subtract.name]: subtract,
  [power.name]: power,
};
const modelWithTools = model.bindTools(Object.values(toolsByName));

本章回顾

延伸阅读