智能体

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

createAgent() 使用 LangGraph 构建了一个基于图的智能体运行时。图由节点（步骤）和边（连接）组成，这些节点和边定义了您的智能体如何处理信息。智能体通过这个图移动，执行节点，如模型节点（调用模型）、工具节点（执行工具）或中间件。了解有关图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) => {
    // Choose model based on conversation complexity
    const messageCount = request.messages.length;

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

const agent = createAgent({
  model: "gpt-4o-mini", // Base model (used when 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: "Search for information",
    schema: z.object({
      query: z.string().describe("The query to search for"),
    }),
  }
);

const getWeather = tool(
  ({ location }) => `Weather in ${location}: Sunny, 72°F`,
  {
    name: "get_weather",
    description: "Get weather information for a location",
    schema: z.object({
      location: z.string().describe("The location to get weather for"),
    }),
  }
);

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 a custom error message to the model
      return new ToolMessage({
        content: `Tool error: Please check your input and try again. (${error})`,
        tool_call_id: request.toolCall.id!,
      });
    }
  },
});

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

智能体在工具失败时将返回一个包含自定义错误信息的 @[ToolMessage]。

ReAct循环中的工具使用

智能体遵循ReAct（“推理+行动”）模式，在针对工具调用的简短推理步骤和将结果观察输入后续决策之间交替，直到它们能够提供一个最终答案。

Example of ReAct loop

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

================================ 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: "You are a helpful assistant. Be concise and accurate.",
});

当未提供 @[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 = "You are a helpful assistant.";

      if (userRole === "expert") {
        return `${basePrompt} Provide detailed technical responses.`;
      } else if (userRole === "beginner") {
        return `${basePrompt} Explain concepts simply and avoid jargon.`;
      }
      return basePrompt;
    }),
  ],
});

// The system prompt will be set dynamically based on context
const result = await agent.invoke(
  { messages: [{ role: "user", content: "Explain machine learning" }] },
  { context: { userRole: "expert" } }
);

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

调用

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

await agent.invoke({
  messages: [{ role: "user", content: "What's the weather in San Francisco?" }],
})

有关从智能体流式传输步骤和/或标记，请参阅流式传输指南。否则，智能体遵循 LangGraph 图 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: "Extract contact info from: John Doe, john@example.com, (555) 123-4567",
    },
  ],
});

console.log(result.structuredResponse);
// {
//   name: 'John Doe',
//   email: 'john@example.com',
//   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: "Search for AI news and summarize the findings"
    }],
  },
  { streamMode: "values" }
);

for await (const chunk of stream) {
  // Each chunk contains the full state at that point
  const latestMessage = chunk.messages.at(-1);
  if (latestMessage?.content) {
    console.log(`Agent: ${latestMessage.content}`);
  } else if (latestMessage?.tool_calls) {
    const toolCallNames = latestMessage.tool_calls.map((tc) => tc.name);
    console.log(`Calling tools: ${toolCallNames.join(", ")}`);
  }
}

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

中间件

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

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

中间件可以无缝集成到智能体的执行图中，让您能够在关键点拦截和修改数据流，而无需更改核心智能体逻辑。

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

在GitHub上编辑此页面的源代码。

通过MCP将这些文档编程连接到Claude、VSCode等，以获取实时答案。

LangChain v1.0

开始使用

核心组件

高级用法

生产环境使用

核心组件

模型

静态模型

动态模型

工具

定义工具

工具错误处理

ReAct循环中的工具使用

系统提示

动态系统提示

调用

高级概念

结构化输出

记忆

流媒体

中间件

LangChain v1.0

开始使用

核心组件

高级用法

生产环境使用

​核心组件

​模型

​静态模型

​动态模型

​工具

​定义工具

​工具错误处理

​ReAct循环中的工具使用

​系统提示

​动态系统提示

​调用

​高级概念

​结构化输出

​记忆

​流媒体

​中间件

核心组件

模型

静态模型

动态模型

工具

定义工具

工具错误处理

ReAct循环中的工具使用

系统提示

动态系统提示

调用

高级概念

结构化输出

记忆

流媒体

中间件