代理 (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-4.1",
  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-4.1-mini" });
const advancedModel = new ChatOpenAI({ model: "gpt-4.1" });

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-4.1-mini", // Base model (used when 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: "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: "gpt-4.1",
  tools: [search, getWeather],
});

如果提供了空工具列表，代理将由没有工具调用功能的单个 LLM 节点组成。

动态工具

使用动态工具，代理可用的工具集是在运行时修改的，而不是全部预先定义的。并非每个工具都适合每种情况。太多的工具可能会压倒模型（过载上下文）并增加错误；太少则限制了能力。动态工具选择使得能够根据身份验证状态、用户权限、功能标志或对话阶段调整可用的工具集。有两种方法，取决于工具是否提前已知：

过滤预注册工具
运行时工具注册

当所有可能的工具在代理创建时已知时，您可以预注册它们，并根据状态、权限或上下文动态过滤向模型公开的工具。

状态
Store
运行时上下文

仅在某些对话里程碑后启用高级工具：

import { createMiddleware, tool } from "langchain";
import { createDeepAgent } from "deepagents";

const stateBasedTools = createMiddleware({
    name: "StateBasedTools",
    wrapModelCall: (request, handler) => {
        // Read from State: check authentication and conversation length
        const state = request.state as typeof request.state & {
            authenticated?: boolean;
        };
        const isAuthenticated = state.authenticated ?? false;
        const messageCount = state.messages.length;

        let filteredTools = request.tools;

        // Only enable sensitive tools after authentication
        if (!isAuthenticated) {
            filteredTools = request.tools.filter(
                (t: any) => typeof t.name === "string" && t.name.startsWith("public_"),
            );
        } else if (messageCount < 5) {
            filteredTools = request.tools.filter(
                (t: any) => typeof t.name === "string" && t.name !== "advanced_search",
            );
        }

        return handler({ ...request, tools: filteredTools });
    },
});

const agent = await createDeepAgent({
    model: "claude-sonnet-4-20250514",
    tools: tools,
    middleware: [stateBasedTools] as any,
});

基于 Store 中的用户首选项或功能标志过滤工具：

import { createMiddleware } from "langchain";
import { createDeepAgent } from "deepagents";
import * as z from "zod";
import {
InMemoryStore,
} from "@langchain/langgraph";


const contextSchema = z.object({
userId: z.string(),
});

const storeBasedTools = createMiddleware({
name: "StoreBasedTools",
contextSchema,
wrapModelCall: async (request, handler) => {
    const userId =
    (request.runtime?.context as { userId?: string } | undefined)?.userId ??
    "user-123";

    // Read from Store: get user's enabled features
    const runtimeStore = request.runtime?.store as InMemoryStore | undefined;
    const rawFlags = (await runtimeStore?.get(
    ["features"],
    userId as string
    )) as unknown;
    const featureFlags = rawFlags as FeatureFlags | undefined;

    let filteredTools = request.tools;

    if (featureFlags) {
    const enabledFeatures = featureFlags.enabledTools || [];
    filteredTools = request.tools.filter((t) =>
        enabledFeatures.includes(t.name as string)
    );
    }

    return handler({ ...request, tools: filteredTools });
},
});

const agent = await createDeepAgent({
model: "claude-sonnet-4-20250514",
backend: backendFactory,
store,
checkpointer,
tools,
middleware: [storeBasedTools] as any,
});

基于运行时上下文中的用户权限过滤工具：

import * as z from "zod";
import { createMiddleware } from "langchain";
import { createDeepAgent } from "deepagents";

const contextSchema = z.object({
userRole: z.string(),
});

const contextBasedTools = createMiddleware({
name: "ContextBasedTools",
contextSchema,
wrapModelCall: (request, handler) => {
    // Read from Runtime Context: get user role
    const userRole = request.runtime.context.userRole;

    let filteredTools = request.tools;

    if (userRole === "admin") {
    // Admins get all tools
    } else if (userRole === "editor") {
    filteredTools = request.tools.filter(t => t.name !== "delete_data");
    } else {
    filteredTools = request.tools.filter(
        (t) => (t.name as string).startsWith("read_")
    );
    }

    return handler({ ...request, tools: filteredTools });
},
});

const agent = await createDeepAgent({
model: "claude-sonnet-4-20250514",
store,
checkpointer,
tools,
middleware: [contextBasedTools] as any,
});

这种方法最适合：

所有可能的工具在编译/启动时已知
您希望基于权限、功能标志或对话状态进行过滤
工具是静态的，但其可用性是动态的

参阅动态选择工具以获取更多示例。

当工具在运行时被发现或创建（例如，从 MCP 服务器加载、基于用户数据生成或从远程注册表获取）时，您需要注册工具并动态处理其执行。这需要两个中间件钩子：

wrap_model_call - 将动态工具添加到请求中
wrap_tool_call - 处理动态添加工具的执行

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

// A tool that will be added dynamically at runtime
const calculateTip = tool(
  ({ billAmount, tipPercentage = 20 }) => {
    const tip = billAmount * (tipPercentage / 100);
    return `Tip: $${tip.toFixed(2)}, Total: $${\(billAmount + tip).toFixed(2)}`;
  },
  {
    name: "calculate_tip",
    description: "Calculate the tip amount for a bill",
    schema: z.object({
      billAmount: z.number().describe("The bill amount"),
      tipPercentage: z.number().default(20).describe("Tip percentage"),
    }),
  }
);

const dynamicToolMiddleware = createMiddleware({
  name: "DynamicToolMiddleware",
  wrapModelCall: (request, handler) => {
    // Add dynamic tool to the request
    // This could be loaded from an MCP server, database, etc.
    return handler({
      ...request,
      tools: [...request.tools, calculateTip],
    });
  },
  wrapToolCall: (request, handler) => {
    // Handle execution of the dynamic tool
    if (request.toolCall.name === "calculate_tip") {
      return handler({ ...request, tool: calculateTip });
    }
    return handler(request);
  },
});

const agent = createAgent({
  model: "gpt-4o",
  tools: [getWeather], // Only static tools registered here
  middleware: [dynamicToolMiddleware],
});

// The agent can now use both getWeather AND calculateTip
const result = await agent.invoke({
  messages: [{ role: "user", content: "Calculate a 20% tip on 5" }],
});

这种方法最适合：

工具在运行时被发现（例如，从 MCP 服务器）
工具是基于用户数据或配置动态生成的
您正在与外部工具注册表集成

wrap_tool_call 钩子对于运行时注册的工具是必需的，因为代理需要知道如何执行原始工具列表中没有的工具。没有它，代理将不知道如何调用动态添加的工具。

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

工具错误处理

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

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

const handleToolErrors = createMiddleware({
  name: "HandleToolErrors",
  wrapToolCall: async (request, handler) => {
    try {
      return await 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: "gpt-4.1",
  tools: [
    /* ... */
  ],
  middleware: [handleToolErrors],
});

当工具失败时，代理将返回带有自定义错误消息的 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...

系统提示词

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

const agent = createAgent({
  model,
  tools,
  systemPrompt: "You are a helpful assistant. Be concise and accurate.",
});

当未提供 systemPrompt 时，代理将直接从消息中推断其任务。 systemPrompt 参数接受 string 或 SystemMessage。使用 SystemMessage 可以更好地控制提示结构，这对于像 Anthropic 的提示缓存这样的提供商特定功能非常有用：

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

const literaryAgent = createAgent({
  model: "anthropic:claude-sonnet-4-5",
  systemPrompt: new SystemMessage({
    content: [
      {
        type: "text",
        text: "You are an AI assistant tasked with analyzing literary works.",
      },
      {
        type: "text",
        text: "<the entire contents of 'Pride and Prejudice'>",
        cache_control: { type: "ephemeral" }
      }
    ]
  })
});

const result = await literaryAgent.invoke({
  messages: [new HumanMessage("Analyze the major themes in 'Pride and Prejudice'.")]
});

带有 { type: "ephemeral" } 的 cache_control 字段告诉 Anthropic 缓存该内容块，从而减少使用相同系统提示的重复请求的延迟和成本。

动态系统提示词

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

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

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

const agent = createAgent({
  model: "gpt-4.1",
  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" } }
);

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

名称

为代理设置一个可选的 name。在将代理作为子图添加到多代理系统中时，这将用作节点标识符：

const agent = createAgent({
  model,
  tools,
  name: "research_assistant",
});

代理名称首选 snake_case（例如 research_assistant 而不是 Research Assistant）。一些模型提供商会拒绝包含空格或特殊字符的名称并报错。仅使用字母数字字符、下划线和连字符可确保跨所有提供商的兼容性。工具名称也是如此。

调用

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

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

有关从代理流式传输步骤和/或令牌的信息，请参阅流式传输指南。否则，代理遵循 LangGraph Graph API 并支持所有相关方法，如 stream 和 invoke。

使用 LangSmith 跟踪、调试和评估您的代理。

高级概念

结构化输出

在某些情况下，您可能希望代理以特定格式返回输出。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: "gpt-4.1",
  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 { z } from "zod/v4";
import { StateSchema, MessagesValue } from "@langchain/langgraph";
import { createAgent } from "langchain";

const CustomAgentState = new StateSchema({
  messages: MessagesValue,
  userPreferences: z.record(z.string(), z.string()),
});

const customAgent = createAgent({
  model: "gpt-4.1",
  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 上编辑此页面或提交问题。

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

Get started

Core components

Middleware

Advanced usage

Agent development

Deploy with LangSmith

核心组件

模型

静态模型

动态模型

工具

静态工具

动态工具

工具错误处理

ReAct 循环中的工具使用

系统提示词

动态系统提示词

名称

调用

高级概念

结构化输出

记忆

流式传输

中间件

Get started

Core components

Middleware

Advanced usage

Agent development

Deploy with LangSmith

​核心组件

​模型

​静态模型

​动态模型

​工具

​静态工具

​动态工具

​工具错误处理

​ReAct 循环中的工具使用

​系统提示词

​动态系统提示词

​名称

​调用

​高级概念

​结构化输出

​记忆

​流式传输

​中间件

核心组件

模型

静态模型

动态模型

工具

静态工具

动态工具

工具错误处理

ReAct 循环中的工具使用

系统提示词

动态系统提示词

名称

调用

高级概念

结构化输出

记忆

流式传输

中间件