Agents 智能体

代理将语言模型与工具相结合，创建能够推理任务、决定使用哪些工具并迭代式寻找解决方案的系统。 createAgent() 提供了一个生产就绪的代理实现。 LLM 代理通过循环运行工具来实现目标。代理会持续运行，直到满足停止条件——即模型发出最终输出或达到迭代限制。

createAgent() 使用 LangGraph 构建基于图的代理运行时。图由节点（步骤）和边（连接）组成，定义了代理处理信息的方式。代理在此图中移动，执行诸如模型节点（调用模型）、工具节点（执行工具）或中间件等节点。了解更多关于 Graph API 的信息。

核心组件

模型

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

静态模型

静态模型在创建代理时配置一次，并在整个执行过程中保持不变。这是最常见且直接的方法。从初始化静态模型：

import { createAgent } from "langchain";

const agent = createAgent({
  model: "openai: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 和其他提供者特定设置时，请使用它们。参考 API 参考查看模型上可用的参数和方法。

动态模型

动态模型根据当前的状态和在选择。这实现了复杂的路由逻辑和成本优化。要使用动态模型，创建带有 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] as const,
});

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

有关模型配置的详细信息，请参阅模型。有关动态模型选择模式，请参阅中间件中的动态模型。

工具

工具赋予代理执行操作的能力。代理通过以下方式超越了简单的仅模型工具绑定：

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

更多信息，请参阅工具。

定义工具

向代理传递一个工具列表。

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: "openai:gpt-4o",
  tools: [search, getWeather],
});

如果提供了空的工具列表，代理将仅包含一个没有工具调用能力的 LLM 节点。

工具错误处理

要自定义工具错误的处理方式，在自定义中间件中使用 wrapToolCall 钩子：

import { createAgent, createMiddleware, ToolMessage } from "langchain";

const handleToolErrors = createMiddleware({
  name: "HandleToolErrors",
  wrapToolCall: (request, handler) => {
    try {
      return handler(request);
    } catch (error) {
      // 向模型返回自定义错误消息
      return new ToolMessage({
        content: `工具错误：请检查您的输入并重试。（${error}）`,
        tool_call_id: request.toolCall.id!,
      });
    }
  },
});

const agent = createAgent({
  model: "openai:gpt-4o",
  tools: [
    /* ... */
  ],
  middleware: [handleToolErrors] as const,
});

当工具失败时，代理将返回一个带有自定义错误消息的 @[ToolMessage]。

ReAct 循环中的工具使用

代理遵循 ReAct（“推理 + 行动”）模式，在简短推理步骤与针对性工具调用之间交替进行，并将结果观察反馈到后续决策中，直到能够给出最终答案。

ReAct 循环示例

提示：识别当前最流行的无线耳机并验证其可用性。

================================ Human Message =================================

Find the most popular wireless headphones right now and check if they're in stock

推理：“流行度是时间敏感的，我需要使用提供的搜索工具。”
行动：调用 search_products("wireless headphones")

================================== Ai Message ==================================
Tool Calls:
  search_products (call_abc123)
 Call ID: call_abc123
  Args:
    query: wireless headphones

================================= Tool Message =================================

Found 5 products matching "wireless headphones". Top 5 results: WH-1000XM5, ...

推理：“在回答之前，我需要确认排名第一的商品的可用性。”
行动：调用 check_inventory("WH-1000XM5")

================================== Ai Message ==================================
Tool Calls:
  check_inventory (call_def456)
 Call ID: call_def456
  Args:
    product_id: WH-1000XM5

================================= Tool Message =================================

Product WH-1000XM5: 10 units in stock

推理：“我有了最流行的型号及其库存状态。现在可以回答用户的问题了。”
行动：生成最终答案

================================== Ai Message ==================================

I found wireless headphones (model WH-1000XM5) with 10 units in stock...

要了解有关工具的更多信息，请参阅工具。

系统提示

您可以通过提供提示来塑造代理处理任务的方式。@[system_prompt] 参数可以作为字符串提供：

const agent = createAgent({
  model,
  tools,
  systemPrompt: "你是一个乐于助人的助手。请简洁准确。",
});

当没有提供 @[system_prompt] 时，代理将直接从消息推断其任务。

动态系统提示

对于需要根据运行时上下文或代理状态修改系统提示的更高级用例，您可以使用中间件。

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

const contextSchema = z.object({
  userRole: z.enum(["expert", "beginner"]),
});

const agent = createAgent({
  model: "openai:gpt-4o",
  tools: [/* ... */],
  contextSchema,
  middleware: [
    dynamicSystemPromptMiddleware<z.infer<typeof contextSchema>>((state, runtime) => {
      const userRole = runtime.context.userRole || "user";
      const basePrompt = "你是一个乐于助人的助手。";

      if (userRole === "expert") {
        return `${basePrompt} 提供详细的技术响应。`;
      } else if (userRole === "beginner") {
        return `${basePrompt} 简单地解释概念，避免使用行话。`;
      }
      return basePrompt;
    }),
  ],
});

// 系统提示将根据上下文动态设置
const result = await agent.invoke(
  { messages: [{ role: "user", content: "解释机器学习" }] },
  { context: { userRole: "expert" } }
);

有关消息类型和格式的更多详细信息，请参阅消息。有关全面的中间件文档，请参阅中间件。

调用

您可以通过向其 State 传递更新来调用代理。所有代理在其状态中都包含一个消息序列；要调用代理，请传递一条新消息：

await agent.invoke({
  messages: [{ role: "user", content: "旧金山的天气怎么样？" }],
})

要从代理流式传输步骤和/或令牌，请参阅流式传输指南。除此之外，代理遵循 LangGraph 的 Graph API 并支持所有相关方法。

高级概念

结构化输出

在某些情况下，您可能希望代理以特定格式返回输出。LangChain 通过 responseFormat 参数提供了一种简单、通用的方法来实现这一点。

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

const ContactInfo = z.object({
  name: z.string(),
  email: z.string(),
  phone: z.string(),
});

const agent = createAgent({
  model: "openai:gpt-4o",
  responseFormat: ContactInfo,
});

const result = await agent.invoke({
  messages: [
    {
      role: "user",
      content: "从以下内容提取联系信息：John Doe, [email protected], (555) 123-4567",
    },
  ],
});

console.log(result.structuredResponse);
// {
//   name: 'John Doe',
//   email: '[email protected]',
//   phone: '(555) 123-4567'
// }

要了解结构化输出，请参阅结构化输出。

记忆

代理通过消息状态自动维护对话历史记录。您还可以配置代理使用自定义状态模式来记住对话过程中的附加信息。存储在状态中的信息可以看作是代理的短期记忆：

import * as z from "zod";
import { MessagesZodState } from "@langchain/langgraph";
import { createAgent, type BaseMessage } from "langchain";

const customAgentState = z.object({
  messages: MessagesZodState.shape.messages,
  userPreferences: z.record(z.string(), z.string()),
});

const CustomAgentState = createAgent({
  model: "openai:gpt-4o",
  tools: [],
  stateSchema: customAgentState,
});

要了解更多关于记忆的信息，请参阅记忆。有关实现跨会话持久化的长期记忆的信息，请参阅长期记忆。

流式传输

我们已经看到可以使用 invoke 调用代理以获取最终响应。如果代理执行多个步骤，这可能需要一段时间。为了显示中间进度，我们可以在消息发生时将其流式传输回来。

const stream = await agent.stream(
  {
    messages: [{
      role: "user",
      content: "搜索 AI 新闻并总结发现"
    }],
  },
  { streamMode: "values" }
);

for await (const chunk of stream) {
  // 每个块包含该时间点的完整状态
  const latestMessage = chunk.messages.at(-1);
  if (latestMessage?.content) {
    console.log(`代理: ${latestMessage.content}`);
  } else if (latestMessage?.tool_calls) {
    const toolCallNames = latestMessage.tool_calls.map((tc) => tc.name);
    console.log(`调用工具: ${toolCallNames.join(", ")}`);
  }
}

有关流式传输的更多详细信息，请参阅流式传输。

中间件

中间件提供了强大的扩展性，用于在执行的不同阶段自定义代理行为。您可以使用中间件来：

在调用模型之前处理状态（例如，消息修剪、上下文注入）
修改或验证模型的响应（例如，防护栏、内容过滤）
使用自定义逻辑处理工具执行错误
基于状态或上下文实现动态模型选择
添加自定义日志记录、监控或分析

中间件无缝集成到代理的执行图中，允许您在关键点拦截和修改数据流，而无需更改核心代理逻辑。

有关包括 beforeModel、afterModel 和 wrapToolCall 等钩子的全面中间件文档，请参阅中间件。

Edit the source of this page on GitHub.

Connect these docs programmatically to Claude, VSCode, and more via MCP for real-time answers.

LangChain v1.0

开始

Core components

高级用法

Use in production

核心组件

模型

静态模型

动态模型

工具

定义工具

工具错误处理

ReAct 循环中的工具使用

系统提示

动态系统提示

调用

高级概念

结构化输出

记忆

流式传输

中间件

LangChain v1.0

开始

Core components

高级用法

Use in production

​核心组件

​模型

​静态模型

​动态模型

​工具

​定义工具

​工具错误处理

​ReAct 循环中的工具使用

​系统提示

​动态系统提示

​调用

​高级概念

​结构化输出

​记忆

​流式传输

​中间件

核心组件

模型

静态模型

动态模型

工具

定义工具

工具错误处理

ReAct 循环中的工具使用

系统提示

动态系统提示

调用

高级概念

结构化输出

记忆

流式传输

中间件