智能体 (Agents)

智能体将语言模型与工具结合起来，创建能够推理任务、决定使用哪些工具并迭代地解决问题的系统。

createAgent() 提供了一个生产就绪的智能体实现。

LLM 智能体在循环中运行工具以实现目标。智能体运行直到满足停止条件 - 即当模型发出最终输出或达到迭代限制时。

核心组件

模型

模型是智能体的推理引擎。它可以通过多种方式指定，支持静态和动态模型选择。

静态模型

静态模型在创建智能体时配置一次，在整个执行过程中保持不变。这是最常见和直接的方法。

从模型标识符字符串初始化静态模型：

import { createAgent } from "langchain";

const agent = createAgent({
  model: "gpt-5",
  tools: []
});

模型标识符字符串使用格式 provider:model（例如 "openai:gpt-5"）。你可能需要对模型配置有更多控制，在这种情况下可以使用提供商包直接初始化模型实例：

import { createAgent } from "langchain";
import { ChatOpenAI } from "@langchain/openai";

const model = new ChatOpenAI({
  model: "gpt-4o",
  temperature: 0.1,
  maxTokens: 1000,
  timeout: 30
});

const agent = createAgent({
  model,
  tools: []
});

模型实例让你完全控制配置。当你需要设置特定参数如 temperature、max_tokens、timeouts，或配置 API 密钥、base_url 和其他提供商特定设置时使用它们。

动态模型

动态模型在运行时根据当前状态和上下文选择。这启用了复杂的路由逻辑和成本优化。

要使用动态模型，创建带有 wrapModelCall 的中间件来修改请求中的模型：

import { ChatOpenAI } from "@langchain/openai";
import { createAgent, createMiddleware } from "langchain";

const basicModel = new ChatOpenAI({ model: "gpt-4o-mini" });
const advancedModel = new ChatOpenAI({ model: "gpt-4o" });

const dynamicModelSelection = createMiddleware({
  name: "DynamicModelSelection",
  wrapModelCall: (request, handler) => {
    // 根据对话复杂度选择模型
    const messageCount = request.messages.length;

    return handler({
        ...request,
        model: messageCount > 10 ? advancedModel : basicModel,
    });
  },
});

const agent = createAgent({
  model: "gpt-4o-mini", // 基础模型（当 messageCount ≤ 10 时使用）
  tools,
  middleware: [dynamicModelSelection],
});

有关中间件和高级模式的更多详情，请参阅中间件文档。

工具

工具赋予智能体采取行动的能力。智能体通过以下方式超越简单的仅模型工具绑定：

• 按顺序进行多次工具调用（由单个提示触发）
• 在适当时并行调用工具
• 根据之前的结果动态选择工具
• 工具重试逻辑和错误处理
• 跨工具调用的状态持久化

有关更多信息，请参阅工具。

定义工具

将工具列表传递给智能体。

import * as z from "zod";
import { createAgent, tool } from "langchain";

const search = tool(
  ({ query }) => `Results for: ${query}`,
  {
    name: "search",
    description: "搜索信息",
    schema: z.object({
      query: z.string().describe("要搜索的查询"),
    }),
  }
);

const getWeather = tool(
  ({ location }) => `Weather in ${location}: Sunny, 72°F`,
  {
    name: "get_weather",
    description: "获取某个位置的天气信息",
    schema: z.object({
      location: z.string().describe("要获取天气的位置"),
    }),
  }
);

const agent = createAgent({
  model: "gpt-4o",
  tools: [search, getWeather],
});

如果提供空的工具列表，智能体将只包含一个没有工具调用能力的单个 LLM 节点。

工具错误处理

要自定义如何处理工具错误，请在自定义中间件中使用 wrapToolCall 钩子：

import { createMiddleware } from "langchain";

const errorHandlingMiddleware = createMiddleware({
  name: "ErrorHandling",
  wrapToolCall: async (request, handler) => {
    try {
      return await handler(request);
    } catch (error) {
      // 自定义错误处理逻辑
      return {
        content: `工具执行失败: ${error.message}`,
        isError: true,
      };
    }
  },
});

系统提示词

使用 prompt 参数为智能体提供指令和上下文：

const agent = createAgent({
  model: "gpt-4o",
  tools: [search, getWeather],
  prompt: "你是一个有帮助的助手。回答时要简洁明了。",
});

运行智能体

invoke

使用 invoke 运行智能体并获取最终结果：

const result = await agent.invoke({
  messages: [{ role: "user", content: "东京的天气怎么样？" }]
});

console.log(result.messages);

流式输出

使用 stream 获取实时更新：

const stream = await agent.stream({
  messages: [{ role: "user", content: "搜索最新的 AI 新闻" }]
});

for await (const event of stream) {
  console.log(event);
}

有关流式输出的更多详情，请参阅流式输出。

配置

迭代限制

控制智能体可以运行的最大迭代次数：

const agent = createAgent({
  model: "gpt-4o",
  tools,
  maxIterations: 10, // 默认为 25
});

递归限制

设置图遍历的最大步数：

const result = await agent.invoke(
  { messages },
  { recursionLimit: 50 }
);