快速入门

本快速入门将向你展示如何在几分钟内创建一个功能齐全的 AI 代理。

使用 AI 编码助手？

安装 LangChain 文档 MCP 服务器，让你的代理能够访问最新的 LangChain 文档和示例。
安装 LangChain Skills，以提高你的代理在 LangChain 生态系统任务中的性能。

安装依赖项

安装以下软件包以便跟随学习：

npm install deepagents langchain @langchain/core
# Requires Node.js 22+

pnpm add deepagents langchain @langchain/core
# Requires Node.js 22+

yarn add deepagents langchain @langchain/core
# Requires Node.js 22+

bun add deepagents langchain @langchain/core
# Requires Bun v1.0.0+

设置 API 密钥

从任何受支持的模型提供商（例如 Google Gemini 或 OpenAI）获取 API 密钥。设置 API 密钥，例如：

export OPENAI_API_KEY="your-api-key"

export GOOGLE_API_KEY="your-api-key"

export ANTHROPIC_API_KEY="your-api-key"

export OPENROUTER_API_KEY="your-api-key"

export FIREWORKS_API_KEY="your-api-key"

export BASETEN_API_KEY="your-api-key"

# Local: Ollama must be running (https://ollama.com)
# Cloud: Set your Ollama API key for hosted inference
export OLLAMA_API_KEY="your-api-key"

export AZURE_OPENAI_API_KEY="your-api-key"
export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com"
export AZURE_OPENAI_DEPLOYMENT_NAME="your-deployment"

export AWS_ACCESS_KEY_ID="your-access-key"
export AWS_SECRET_ACCESS_KEY="your-secret-key"
export AWS_REGION="us-east-1"

export HUGGINGFACEHUB_API_TOKEN="hf_..."

使用 LangSmith 网关LangSmith 网关通过 LangSmith 路由大多数主要提供商。你可以使用自己的提供商密钥，或者使用网关额度在没有提供商密钥的情况下访问模型。

构建一个基础代理

首先创建一个简单的代理，它可以回答问题和调用工具。此示例中的代理使用选定的语言模型、一个基本天气函数作为工具，以及一个简单的提示来指导其行为：

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

const getWeather = tool(
  (input) => `It's always sunny in ${input.city}!`,
  {
    name: "get_weather",
    description: "Get the weather for a given city",
    schema: z.object({
      city: z.string().describe("The city to get the weather for"),
    }),
  }
);

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

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

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

const getWeather = tool(
  (input) => `It's always sunny in ${input.city}!`,
  {
    name: "get_weather",
    description: "Get the weather for a given city",
    schema: z.object({
      city: z.string().describe("The city to get the weather for"),
    }),
  }
);

const agent = createAgent({
  model: "google-genai:gemini-2.5-flash-lite",
  tools: [getWeather],
});

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

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

const getWeather = tool(
  (input) => `It's always sunny in ${input.city}!`,
  {
    name: "get_weather",
    description: "Get the weather for a given city",
    schema: z.object({
      city: z.string().describe("The city to get the weather for"),
    }),
  }
);

const agent = createAgent({
  model: "claude-sonnet-4-6",
  tools: [getWeather],
});

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

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

const getWeather = tool(
  (input) => `It's always sunny in ${input.city}!`,
  {
    name: "get_weather",
    description: "Get the weather for a given city",
    schema: z.object({
      city: z.string().describe("The city to get the weather for"),
    }),
  }
);

const agent = createAgent({
  model: "openrouter:anthropic/claude-sonnet-4-6",
  tools: [getWeather],
});

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

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

const getWeather = tool(
  (input) => `It's always sunny in ${input.city}!`,
  {
    name: "get_weather",
    description: "Get the weather for a given city",
    schema: z.object({
      city: z.string().describe("The city to get the weather for"),
    }),
  }
);

const agent = createAgent({
  model: "fireworks:accounts/fireworks/models/qwen3p5-397b-a17b",
  tools: [getWeather],
});

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

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

const getWeather = tool(
  (input) => `It's always sunny in ${input.city}!`,
  {
    name: "get_weather",
    description: "Get the weather for a given city",
    schema: z.object({
      city: z.string().describe("The city to get the weather for"),
    }),
  }
);

const agent = createAgent({
  model: "baseten:zai-org/GLM-5.2",
  tools: [getWeather],
});

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

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

const getWeather = tool(
  (input) => `It's always sunny in ${input.city}!`,
  {
    name: "get_weather",
    description: "Get the weather for a given city",
    schema: z.object({
      city: z.string().describe("The city to get the weather for"),
    }),
  }
);

const agent = createAgent({
  model: "ollama:devstral-2",
  tools: [getWeather],
});

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

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

const getWeather = tool(
  (input) => `It's always sunny in ${input.city}!`,
  {
    name: "get_weather",
    description: "Get the weather for a given city",
    schema: z.object({
      city: z.string().describe("The city to get the weather for"),
    }),
  }
);

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

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

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

const getWeather = tool(
  (input) => `It's always sunny in ${input.city}!`,
  {
    name: "get_weather",
    description: "Get the weather for a given city",
    schema: z.object({
      city: z.string().describe("The city to get the weather for"),
    }),
  }
);

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

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

当你运行代码并提示代理告诉你旧金山的天气时，代理会利用该输入及其可用的上下文。代理理解你是在询问旧金山市的天气，因此使用提供的城市名称调用天气工具。

你可以通过更改模型名称并设置相应的 API 密钥来使用任何受支持的模型。使用 LangSmith 跟踪代理内部发生的情况。请按照跟踪快速入门进行设置。我们建议你还设置 LangSmith Engine，它可以监控你的跟踪信息、检测问题并提出修复建议。

构建一个真实世界的代理

在下面的示例中，你将构建一个可以回答有关文本文件问题的研究代理。在此过程中，你将探索以下概念：

用于改善代理行为的详细系统提示
与外部数据集成的创建工具
用于获得一致响应的模型配置
用于类似聊天交互的对话记忆
内置功能的深度代理
测试你的代理

定义系统提示

系统提示定义了你的代理的角色和行为。请保持其具体且可操作：

const SYSTEM_PROMPT = `You are a literary data assistant.

## Capabilities

- \`fetch_text_from_url\`: loads document text from a URL into the conversation.
Do not guess line counts or positions—ground them in tool results from the saved file.`;

创建工具

工具允许模型通过调用你定义的函数与外部系统交互。工具可以依赖于运行时上下文，也可以与代理记忆交互。此示例使用一个工具从给定 URL 加载文档：

import { tool } from "@langchain/core/tools";
import { createAgent, initChatModel } from "langchain";
import { z } from "zod";

const fetchTextFromUrl = tool(
    async ({ url }: { url: string }): Promise<string> => {
        const controller = new AbortController();
        const timeoutId = setTimeout(() => controller.abort(), 120_000);
        try {
            const resp = await fetch(url, {
                headers: {
                "User-Agent": "Mozilla/5.0 (compatible; quickstart-research/1.0)",
                },
                signal: controller.signal,
            });
            if (!resp.ok) {
                return `Fetch failed: HTTP ${resp.status} ${resp.statusText}`;
            }
            return await resp.text();
        } catch (e) {
            const msg = e instanceof Error ? e.message : String(e);
            return `Fetch failed: ${msg}`;
        } finally {
            clearTimeout(timeoutId);
        }
    },
    {
        name: "fetch_text_from_url",
        description: "Fetch the document from a URL.",
        schema: z.object({ url: z.string().url() }),
    },
);

Zod 是一个用于验证和解析预定义模式的库。你可以使用它来定义工具的输入模式，以确保代理仅使用正确的参数调用该工具。或者，你可以将 schema 属性定义为 JSON schema 对象。请注意，JSON 模式在运行时不会被验证。

示例：使用 JSON schema 作为工具输入

import { tool } from "@langchain/core/tools";

const fetchTextFromUrl = tool(
async ({ url }: { url: string }): Promise<string> => {
    const controller = new AbortController();
    const timeoutId = setTimeout(() => controller.abort(), 120_000);
    try {
    const resp = await fetch(url, {
        headers: {
        "User-Agent": "Mozilla/5.0 (compatible; quickstart-research/1.0)",
        },
        signal: controller.signal,
    });
    if (!resp.ok) {
        return `Fetch failed: HTTP ${resp.status} ${resp.statusText}`;
    }
    return await resp.text();
    } catch (e) {
    const msg = e instanceof Error ? e.message : String(e);
    return `Fetch failed: ${msg}`;
    } finally {
    clearTimeout(timeoutId);
    }
},
{
    name: "fetch_text_from_url",
    description: "Fetch the document from a URL.",
    schema: {
    type: "object",
    properties: {
        url: {
        type: "string",
        description: "The URL of the document to fetch.",
        format: "uri",
        },
    },
    required: ["url"],
    },
},
);

配置你的模型

为你的用例设置合适的语言模型参数。例如：

import { initChatModel } from "langchain";

const model = await initChatModel("gpt-5.5", {
  temperature: 0.5,
  timeout: 300,
  maxTokens: 25000,
});

import { initChatModel } from "langchain";

const model = await initChatModel("gemini-3.1-pro-preview", {
  modelProvider: "google-genai",
  temperature: 0.5,
  timeout: 600_000,
  maxTokens: 25000,
});

import { initChatModel } from "langchain";

const model = await initChatModel("claude-sonnet-4-6", {
  temperature: 0.5,
  timeout: 300,
  maxTokens: 25000,
});

import { initChatModel } from "langchain";

const model = await initChatModel("openrouter:anthropic/claude-sonnet-4-6", {
  temperature: 0.5,
  timeout: 300,
  maxTokens: 25000,
});

import { initChatModel } from "langchain";

const model = await initChatModel(
  "fireworks:accounts/fireworks/models/qwen3p5-397b-a17b",
  { temperature: 0.5, timeout: 300, maxTokens: 25000 }
);

import { initChatModel } from "langchain";

const model = await initChatModel("baseten:zai-org/GLM-5.2", {
  temperature: 0.5,
  timeout: 300,
  maxTokens: 25000,
});

import { initChatModel } from "langchain";

const model = await initChatModel("ollama:devstral-2", {
  temperature: 0.5,
  timeout: 300,
  maxTokens: 25000,
});

import { initChatModel } from "langchain";

const model = await initChatModel("azure_openai:gpt-5.5", {
  temperature: 0.5,
  timeout: 300,
  maxTokens: 25000,
});

import { initChatModel } from "langchain";

const model = await initChatModel("bedrock:gpt-5.5", {
  temperature: 0.5,
  timeout: 300,
  maxTokens: 25000,
});

根据所选的模型和提供商，初始化参数可能会有所不同；请参考其参考页面了解详细信息。

添加记忆

向你的代理添加记忆以在交互过程中维持状态。这允许代理记住以前的对话和上下文。

import { MemorySaver } from "@langchain/langgraph";

const checkpointer = new MemorySaver();

在生产环境中，请使用将消息历史保存到数据库的持久化检查点器。请参阅添加和管理记忆了解更多详情。

创建并运行代理

现在，使用所有组件组装你的代理并运行它。创建代理有两个不同的框架：LangChain 代理和深度代理。 LangChain 和深度代理都为你提供了对工具、记忆等的精细控制。两者的主要区别在于，深度代理内置了一系列常用的功能，如规划、文件系统工具和子代理。当你希望以最小的设置获得最大能力时，请使用深度代理；当你需要精细控制时，请选择 LangChain 代理。

由于代码调用模型时使用了《了不起的盖茨比》的完整文本，因此会消耗大量 token。你可以在下一步中查看示例输出。

让我们两者都尝试一下：

async function main() {
    const agent = createAgent({
        model,
        tools: [fetchTextFromUrl],
        systemPrompt: SYSTEM_PROMPT,
        checkpointer,
    });

    const deepAgent = createDeepAgent({
        model,
        tools: [fetchTextFromUrl],
        systemPrompt: SYSTEM_PROMPT,
        checkpointer,
    });

    const content = `Project Gutenberg hosts a full plain-text copy of F. Scott Fitzgerald's The Great Gatsby.
    URL: https://www.gutenberg.org/files/64317/64317-0.txt

    Answer as much as you can:

    1) How many lines in the complete Gutenberg file contain the substring \`Gatsby\` (count lines, not occurrences within a line, each line ends with a line break).
    2) The 1-based line number of the first line in the file that contains \`Daisy\`.
    3) A two-sentence neutral synopsis.

    Do your best on (1) and (2). If at any point you realize you cannot **verify** an exact answer with
    your available tools and reasoning, do not fabricate numbers: use \`null\` for that field and spell out
    the limitation in \`how_you_computed_counts\`. If you encounter any errors please report what the error was and what the error message was.`;

    const agentResult = await agent.invoke(
        { messages: [{ role: "user", content }] },
        { configurable: { thread_id: "great-gatsby-lc" } },
    );
    const deepAgentResult = await deepAgent.invoke(
        { messages: [{ role: "user", content }] },
        { configurable: { thread_id: "great-gatsby-da" } },
    );

    const agentMessages = agentResult.messages;
    const deepMessages = deepAgentResult.messages;
    console.log(agentMessages[agentMessages.length - 1]!.content_blocks);
    console.log("\n");
    console.log(deepMessages[deepMessages.length - 1]!.content_blocks);
}

main().catch((err) => {
    console.error(err);
    process.exitCode = 1;
});

Show 完整示例代码

import { MemorySaver } from "@langchain/langgraph";
import { createDeepAgent } from "deepagents";
import { tool } from "@langchain/core/tools";
import { createAgent, initChatModel } from "langchain";
import { z } from "zod";
const SYSTEM_PROMPT = `You are a literary data assistant.

## Capabilities

- \`fetch_text_from_url\`: loads document text from a URL into the conversation.
Do not guess line counts or positions—ground them in tool results from the saved file.`;

const fetchTextFromUrl = tool(
    async ({ url }: { url: string }): Promise<string> => {
        const controller = new AbortController();
        const timeoutId = setTimeout(() => controller.abort(), 120_000);
        try {
            const resp = await fetch(url, {
                headers: {
                    "User-Agent": "Mozilla/5.0 (compatible; quickstart-research/1.0)",
                },
                signal: controller.signal,
            });
            if (!resp.ok) {
                return `Fetch failed: HTTP ${resp.status} ${resp.statusText}`;
            }
            return await resp.text();
        } catch (e) {
            const msg = e instanceof Error ? e.message : String(e);
            return `Fetch failed: ${msg}`;
        } finally {
           clearTimeout(timeoutId);
        }
    },
    {
        name: "fetch_text_from_url",
        description: "Fetch the document from a URL.",
        schema: z.object({ url: z.string().url() }),
    },
);

const model = await initChatModel("gemini-3.1-pro-preview", {
    modelProvider: "google-genai",
    temperature: 0.5,
    timeout: 600_000,
    maxTokens: 25000,
    streaming: true,
});

const checkpointer = new MemorySaver();

async function main() {
    const agent = createAgent({
        model,
        tools: [fetchTextFromUrl],
        systemPrompt: SYSTEM_PROMPT,
        checkpointer,
    });

    const deepAgent = createDeepAgent({
        model,
        tools: [fetchTextFromUrl],
        systemPrompt: SYSTEM_PROMPT,
        checkpointer,
    });

    const content = `Project Gutenberg hosts a full plain-text copy of F. Scott Fitzgerald's The Great Gatsby.
    URL: https://www.gutenberg.org/files/64317/64317-0.txt

    Answer as much as you can:

    1) How many lines in the complete Gutenberg file contain the substring \`Gatsby\` (count lines, not occurrences within a line, each line ends with a line break).
    2) The 1-based line number of the first line in the file that contains \`Daisy\`.
    3) A two-sentence neutral synopsis.

    Do your best on (1) and (2). If at any point you realize you cannot **verify** an exact answer with
    your available tools and reasoning, do not fabricate numbers: use \`null\` for that field and spell out
    the limitation in \`how_you_computed_counts\`. If you encounter any errors please report what the error was and what the error message was.`;

    const agentResult = await agent.invoke(
        { messages: [{ role: "user", content }] },
        { configurable: { thread_id: "great-gatsby-lc" } },
    );
    const deepAgentResult = await deepAgent.invoke(
        { messages: [{ role: "user", content }] },
        { configurable: { thread_id: "great-gatsby-da" } },
    );

    const agentMessages = agentResult.messages;
    const deepMessages = deepAgentResult.messages;
    console.log(agentMessages[agentMessages.length - 1]!.content_blocks);
    console.log("\n");
    console.log(deepMessages[deepMessages.length - 1]!.content_blocks);
}

main().catch((err) => {
    console.error(err);
    process.exitCode = 1;
});

查看结果

结果会根据模型和执行情况而有所不同。

LangChain agents
深度代理

**1) 包含 `Gatsby` 的行数：** `null`

**2) 第一个包含 `Daisy` 的行：** `null`

**3) 概要：**
《了不起的盖茨比》讲述了神秘的百万富翁杰·盖茨比的故事，以及他对于与前情人黛西·布坎南重逢的执念，故事由他的邻居尼克·卡拉威叙述。小说以20世纪20年代的纽约长岛为背景，探讨了财富、阶级以及美国梦的不可捉摸性。

**如何计算的数量：**
我成功使用 `fetch_text_from_url` 工具获取了电子书的完整文本。但是，由于我无法访问代码执行环境（如 Python）或文本处理工具（如 `grep`），我无法确定性地按换行符拆分文本、遍历数千行并验证确切的行号或匹配计数。LLM 无法在其上下文窗口内可靠地对大量文本执行精确的行计数或索引，除非借助外部计算工具。根据指示，我没有编造或猜测数字，而是对确切的计数和位置输出了 `null`。

基于直接从 Gutenberg URL 获取并使用文件系统搜索工具分析的文本，以下是对您问题的回答：

**1) 包含子字符串 `Gatsby` 的行数**
**258** 行包含精确的子字符串 `Gatsby`。

**2) 第一个包含 `Daisy` 的行**
文件中第一个包含精确子字符串 `Daisy` 的行是第 **181** 行。
*(供参考，该行内容为：“Buchanans. Daisy was my second cousin once removed, and I’d known Tom”)*

**3) 两句话的中立概要**
*《了不起的盖茨比》讲述了20世纪20年代纽约长岛，神秘的百万富翁杰·盖茨比执迷于与他的旧情人黛西·布坎南重逢的故事。故事由尼克·卡拉威叙述，他目睹了盖茨比不懈野心的悲惨后果以及那个时代富有精英阶层肤浅的物质主义。*

***

**计数是如何计算的：**
从 URL 获取文档时，文件太大，标准输出无法容纳，系统自动将其保存到本地文件系统（`/large_tool_results/x246ax2x`）。然后，我使用 `grep` 工具在保存的文件中搜索精确的文字子字符串 `Gatsby` 和 `Daisy`。`grep` 工具返回了每一行匹配项及其从 1 开始的行号。我手动计算了返回的 `Gatsby` 行的确切数量（总计 258 行），并识别出返回的 `Daisy` 的第一个行号（是 181）。我还验证了没有遗漏任何大写变体（`GATSBY` 或 `DAISY`）。在此过程中未遇到任何错误。

如果你查看两个选项卡上的输出，你会注意到 LangChain 代理提供了答案，但这些是估计值。该代理缺乏回答这个问题的工具。你也可能会遇到提示过长的错误。另一方面，深度代理可以：

使用内置的 write_todos 工具来规划其方法，分解研究任务。
通过调用 fetch_text_from_url 工具来加载文件，收集信息。
使用文件系统工具（grep 和 read_file）来管理上下文。
根据需要生成子代理，将复杂的子任务委托给专门的子代理。

对于 LangChain 代理，你必须实现更多功能才能获得类似水平的服务，并且可以根据需要随时进行自定义。

跟踪代理调用

你使用 LangChain 构建的大多数有趣的应用程序都会多次调用 LLM。随着这些应用程序变得更加复杂，能够检查代理内部究竟发生了什么变得非常重要。最好的方法是使用 LangSmith。注册一个 LangSmith 账户并设置以下内容以开始记录跟踪信息：

export LANGSMITH_TRACING="true"
export LANGSMITH_API_KEY="..."

设置完成后，再次运行你的脚本，然后在 LangSmith 上检查你的代理调用期间发生了什么。

要了解有关使用 LangSmith 跟踪你的代理的更多信息，请参阅 LangSmith 文档。我们建议你还设置 LangSmith Engine，它可以监控你的跟踪信息、检测问题并提出修复建议。

后续步骤

你现在拥有了可以：

理解上下文并记住对话
智能地使用工具
以一致的格式提供结构化响应
通过上下文处理用户特定信息
在交互过程中维护对话状态
规划、研究和综合（仅深度代理）

请继续：

LangChain 代理：添加和管理记忆，部署到生产环境
深度代理：自定义选项，持久记忆，部署到生产环境

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

Edit this page on GitHub or file an issue.

Get started

Core components

Middleware

Frontend

Advanced usage

Agent development

Production

安装依赖项

设置 API 密钥

构建一个基础代理

构建一个真实世界的代理

跟踪代理调用

后续步骤

​安装依赖项

​设置 API 密钥

​构建一个基础代理

​构建一个真实世界的代理

​跟踪代理调用

​后续步骤

安装依赖项

设置 API 密钥

构建一个基础代理

构建一个真实世界的代理

跟踪代理调用

后续步骤