智能体 - Docs by LangChain

智能体将语言模型与工具结合，创建能够推理任务、决定使用哪些工具并迭代地解决问题的系统。 createAgent() 提供了一个生产就绪的智能体实现。 LLM 智能体在循环中运行工具以实现目标。智能体运行直到满足停止条件——即当模型输出最终结果或达到迭代限制时。

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

使用 LangSmith 追踪此循环的每一步、调试工具调用并评估智能体输出。按照追踪快速入门进行设置。

核心组件

模型

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

静态模型

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

import { createAgent } from "langchain";

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

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

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

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

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-5.4-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: "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-5.4",
  tools: [search, getWeather],
});

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

动态工具

使用动态工具时，智能体可用的工具集在运行时修改，而不是全部预先定义。并非每个工具都适用于每种情况。过多的工具可能会使模型不堪重负（上下文过载）并增加错误；过少则限制能力。动态工具选择支持根据认证状态、用户权限、功能标志或对话阶段调整可用的工具集。根据工具是否预先已知，有两种方法：

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

当所有可能的工具在智能体创建时已知时，你可以预先注册它们，并根据状态、权限或上下文动态过滤暴露给模型的工具。

状态
存储
运行时上下文

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

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

const stateBasedTools = createMiddleware({
    name: "StateBasedTools",
    wrapModelCall: (request, handler) => {
        // 从状态读取：检查认证和对话长度
        const state = request.state as typeof request.state & {
            authenticated?: boolean;
        };
        const isAuthenticated = state.authenticated ?? false;
        const messageCount = state.messages.length;

        let filteredTools = request.tools;

        // 仅在认证后启用敏感工具
        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,
});

根据存储中的用户偏好或功能标志过滤工具：

import { createMiddleware } from "langchain";
import { createDeepAgent, StoreBackend } 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";

    // 从存储读取：获取用户启用的功能
    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: new StoreBackend(),
  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) => {
    // 从运行时上下文读取：获取用户角色
    const userRole = request.runtime.context.userRole;

    let filteredTools = request.tools;

    if (userRole === "admin") {
      // 管理员获取所有工具
    } 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";

// 将在运行时动态添加的工具
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) => {
    // 将动态工具添加到请求中
    // 这可以从 MCP 服务器、数据库等加载
    return handler({
      ...request,
      tools: [...request.tools, calculateTip],
    });
  },
  wrapToolCall: (request, handler) => {
    // 处理动态工具的执行
    if (request.toolCall.name === "calculate_tip") {
      return handler({ ...request, tool: calculateTip });
    }
    return handler(request);
  },
});

const agent = createAgent({
  model: "gpt-4o",
  tools: [getWeather], // 这里只注册静态工具
  middleware: [dynamicToolMiddleware],
});

// 智能体现在可以同时使用 getWeather 和 calculateTip
const result = await agent.invoke({
  messages: [{ role: "user", content: "Calculate a 20% tip on $85" }],
});

此方法最适合以下场景：

工具在运行时被发现（例如，来自 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 new ToolMessage({
        content: `Tool error: Please check your input and try again. (${error})`,
        tool_call_id: request.toolCall.id!,
      });
    }
  },
});

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

当工具失败时，智能体将返回一个带有自定义错误消息的 ToolMessage。

ReAct 循环中的工具使用

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

ReAct 循环示例

提示词： 识别当前最受欢迎的无线耳机并验证库存情况。

================================ 人类消息 =================================

找到目前最受欢迎的无线耳机并检查是否有库存

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

================================== AI 消息 ==================================
Tool Calls:
  search_products (call_abc123)
 Call ID: call_abc123
  Args:
    query: wireless headphones

================================= 工具消息 =================================

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

推理：“我需要确认排名第一的产品的库存情况才能回答。”
行动：调用 check_inventory("WH-1000XM5")

================================== AI 消息 ==================================
Tool Calls:
  check_inventory (call_def456)
 Call ID: call_def456
  Args:
    product_id: WH-1000XM5

================================= 工具消息 =================================

Product WH-1000XM5: 10 units in stock

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

================================== AI 消息 ==================================

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: "google_genai:gemini-3.1-pro-preview",
  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'.")]
});

cache_control 字段的 { type: "ephemeral" } 值告诉 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-5.4",
  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;
    }),
  ],
});

// 系统提示词将根据上下文动态设置
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?" }],
})

有关从智能体流式传输步骤和/或 Token，请参阅流式输出指南。此外，智能体遵循 LangGraph 图 API 并支持所有相关方法，如 stream 和 invoke。

高级概念

结构化输出

在某些情况下，你可能希望智能体以特定格式返回输出。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-5.4",
  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-5.4",
  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) {
  // 每个块包含该时刻的完整状态
  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 等钩子，请参阅中间件。

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

在 GitHub 上编辑此页面或提交 Issue。

Documentation Index

​核心组件

​模型

​静态模型

​动态模型

​工具

​静态工具

​动态工具

​工具错误处理

​ReAct 循环中的工具使用

​系统提示词

​动态系统提示词

​名称

​调用

​高级概念

​结构化输出

​记忆

​流式输出

​中间件

核心组件

模型

静态模型

动态模型

工具

静态工具

动态工具

工具错误处理

ReAct 循环中的工具使用

系统提示词

动态系统提示词

名称

调用

高级概念

结构化输出

记忆

流式输出

中间件