快速入门

本指南将引导你使用文件系统工具和子代理功能创建你的第一个深度代理。你将构建一个能够进行研究并撰写报告的研究型代理。

正在使用 AI 编程助手？

安装 LangChain 文档 MCP 服务器，让你的代理可以访问最新的 LangChain 文档和示例。
安装 LangChain Skills 以提升你的代理在 LangChain 生态任务上的表现。

前提条件

在开始之前，请确保你已从模型提供商（例如 Gemini、Anthropic、OpenAI）处获取了一个 API 密钥。

Deep Agents 需要一个支持工具调用的模型。有关如何配置你的模型，请参见自定义。

第一步：安装依赖

npm install deepagents langchain @langchain/core

yarn add deepagents langchain @langchain/core

pnpm add deepagents langchain @langchain/core

Google、OpenAI 和 Anthropic 都提供内置的网页搜索工具：无需额外包或 API 密钥。如果你使用其他提供商或更喜欢使用 Tavily 进行搜索，请同时安装 Tavily 包：

npm install @langchain/tavily

第二步：设置你的 API 密钥

export GOOGLE_API_KEY="your-api-key"

export OPENAI_API_KEY="your-api-key"

export ANTHROPIC_API_KEY="your-api-key"

export OPENROUTER_API_KEY="your-api-key"
export TAVILY_API_KEY="your-tavily-api-key"

export FIREWORKS_API_KEY="your-api-key"
export TAVILY_API_KEY="your-tavily-api-key"

export BASETEN_API_KEY="your-api-key"
export TAVILY_API_KEY="your-tavily-api-key"

# 本地：Ollama 必须在你的机器上运行
# 云端：为托管推理设置你的 Ollama API 密钥
export OLLAMA_API_KEY="your-api-key"
export TAVILY_API_KEY="your-tavily-api-key"

# 为你的提供商设置 API 密钥
export <PROVIDER>_API_KEY="your-api-key"
export TAVILY_API_KEY="your-tavily-api-key"

Deep Agents 可与任何 LangChain 聊天模型配合使用。请为你的提供商设置 API 密钥。

使用 LangSmith 网关LangSmith 网关通过 LangSmith 路由大多数主要提供商。你可以使用自己的提供商密钥，或使用网关额度来访问模型，无需提供商密钥。

第三步：创建一个搜索工具

Google、OpenAI 和 Anthropic 提供内置的网页搜索工具，在服务器端运行：无需额外包或 API 密钥。直接将一个提供商工具字典传递给 create_deep_agent。

提供商搜索（推荐）
Tavily（适用于任何提供商）

// Google 内置搜索功能——无需额外安装或配置 API 密钥
const internetSearch = { google_search: {} };

// OpenAI 内置网页搜索功能——无需额外安装或配置 API 密钥
const internetSearch = { type: "web_search_preview" };

// Anthropic 内置网页搜索功能——无需额外安装或配置 API 密钥
const internetSearch = { type: "web_search_20250305", name: "web_search" };

import { tool } from "langchain";
import { TavilySearch } from "@langchain/tavily";
import { z } from "zod";

const internetSearch = tool(
  async ({
    query,
    maxResults = 5,
    topic = "general",
    includeRawContent = false,
  }: {
    query: string;
    maxResults?: number;
    topic?: "general" | "news" | "finance";
    includeRawContent?: boolean;
  }) => {
    const tavilySearch = new TavilySearch({
      maxResults,
      tavilyApiKey: process.env.TAVILY_API_KEY,
      includeRawContent,
      topic,
    });
    return await tavilySearch._call({ query });
  },
  {
    name: "internet_search",
    description: "Run a web search",
    schema: z.object({
      query: z.string().describe("The search query"),
      maxResults: z
        .number()
        .optional()
        .default(5)
        .describe("Maximum number of results to return"),
      topic: z
        .enum(["general", "news", "finance"])
        .optional()
        .default("general")
        .describe("Search topic category"),
      includeRawContent: z
        .boolean()
        .optional()
        .default(false)
        .describe("Whether to include raw content"),
    }),
  },
);

第四步：创建一个深度代理

将你的搜索工具和模型传递给 create_deep_agent。传递一个格式为 provider:model 的 model 字符串，或一个初始化的模型实例。有关所有提供商，请参阅支持的模型，以及经过测试的建议模型。

import { createDeepAgent } from "deepagents";

// 系统提示，引导代理成为专家研究员
const researchInstructions = `你是一名专家研究员。你的工作是进行彻底研究，然后撰写一份精炼的报告。

你可以使用互联网搜索工具作为获取信息的主要手段。

## \`internet_search\`

使用此工具为给定查询运行互联网搜索。你可以指定返回结果的最大数量、主题以及是否应包含原始内容。
`;

const agent = createDeepAgent({
  model: "google-genai:gemini-3.6-flash",
  tools: [internetSearch],
  systemPrompt: researchInstructions,
});

import { createDeepAgent } from "deepagents";

// 系统提示，引导代理成为专家研究员
const researchInstructions = `你是一名专家研究员。你的工作是进行彻底研究，然后撰写一份精炼的报告。

你可以使用互联网搜索工具作为获取信息的主要手段。

## \`internet_search\`

使用此工具为给定查询运行互联网搜索。你可以指定返回结果的最大数量、主题以及是否应包含原始内容。
`;

const agent = createDeepAgent({
  model: "openai:gpt-5.5",
  tools: [internetSearch],
  systemPrompt: researchInstructions,
});

import { createDeepAgent } from "deepagents";

// 系统提示，引导代理成为专家研究员
const researchInstructions = `你是一名专家研究员。你的工作是进行彻底研究，然后撰写一份精炼的报告。

你可以使用互联网搜索工具作为获取信息的主要手段。

## \`internet_search\`

使用此工具为给定查询运行互联网搜索。你可以指定返回结果的最大数量、主题以及是否应包含原始内容。
`;

const agent = createDeepAgent({
  model: "anthropic:claude-sonnet-4-6",
  tools: [internetSearch],
  systemPrompt: researchInstructions,
});

import { createDeepAgent } from "deepagents";

// 系统提示，引导代理成为专家研究员
const researchInstructions = `你是一名专家研究员。你的工作是进行彻底研究，然后撰写一份精炼的报告。

你可以使用互联网搜索工具作为获取信息的主要手段。

## \`internet_search\`

使用此工具为给定查询运行互联网搜索。你可以指定返回结果的最大数量、主题以及是否应包含原始内容。
`;

const agent = createDeepAgent({
  model: "openrouter:openrouter:z-ai/glm-5.2",
  tools: [internetSearch],
  systemPrompt: researchInstructions,
});

import { createDeepAgent } from "deepagents";

// 系统提示，引导代理成为专家研究员
const researchInstructions = `你是一名专家研究员。你的工作是进行彻底研究，然后撰写一份精炼的报告。

你可以使用互联网搜索工具作为获取信息的主要手段。

## \`internet_search\`

使用此工具为给定查询运行互联网搜索。你可以指定返回结果的最大数量、主题以及是否应包含原始内容。
`;

const agent = createDeepAgent({
  model: "fireworks:accounts/fireworks/models/glm-5p2",
  tools: [internetSearch],
  systemPrompt: researchInstructions,
});

import { createDeepAgent } from "deepagents";

// 系统提示，引导代理成为专家研究员
const researchInstructions = `你是一名专家研究员。你的工作是进行彻底研究，然后撰写一份精炼的报告。

你可以使用互联网搜索工具作为获取信息的主要手段。

## \`internet_search\`

使用此工具为给定查询运行互联网搜索。你可以指定返回结果的最大数量、主题以及是否应包含原始内容。
`;

const agent = createDeepAgent({
  model: "baseten:zai-org/GLM-5.2",
  tools: [internetSearch],
  systemPrompt: researchInstructions,
});

import { createDeepAgent } from "deepagents";

// 系统提示，引导代理成为专家研究员
const researchInstructions = `你是一名专家研究员。你的工作是进行彻底研究，然后撰写一份精炼的报告。

你可以使用互联网搜索工具作为获取信息的主要手段。

## \`internet_search\`

使用此工具为给定查询运行互联网搜索。你可以指定返回结果的最大数量、主题以及是否应包含原始内容。
`;

const agent = createDeepAgent({
  model: "ollama:north-mini-code-1.0",
  tools: [internetSearch],
  systemPrompt: researchInstructions,
});

第五步：设置 LangSmith 跟踪

LangSmith 为你提供对代理执行过程的可见性，允许你查看工具调用、子代理委托和 LLM 响应。在 smith.langchain.com 注册，创建一个 API 密钥，并设置以下环境变量：

export LANGSMITH_TRACING=true
export LANGSMITH_API_KEY="your-langsmith-api-key"

第六步：运行代理

const result = await agent.invoke({
  messages: [{ role: "user", content: "What is langgraph?" }],
});

// Print the agent's response
console.log(result.messages[result.messages.length - 1].content);

它是如何工作的？

你的深度代理会自动：

进行研究，通过调用 internet_search 工具来收集信息。
管理上下文，使用文件系统工具（write_file, read_file）来卸载大型搜索结果。
按需生成子代理，将复杂的子任务委托给专门的子代理。
综合报告，将研究结果编译成一个连贯的响应。

要添加使用 write_todos 的结构化任务规划，请通过 TodoListMiddleware 选择加入。请参阅任务规划。

示例

有关你可以使用 Deep Agents 构建的代理、模式和应用，请参见示例。

流式传输

Deep Agents 内置流式传输功能，使用 LangGraph 实现实时更新代理执行过程。这允许你逐步观察输出，并检查和调试代理及子代理的工作，例如工具调用、工具结果和 LLM 响应。

后续步骤

现在你已经构建了你的第一个深度代理：

自定义你的代理：了解自定义选项，包括自定义系统提示词、工具和子代理。
添加长期记忆：启用跨对话的持久化记忆。
部署到生产环境：使用托管深度代理在 LangSmith 中创建、运行和操作深度代理。
测试与评估：使用 LangSmith 评估来运行自动化测试，并根据数据集衡量你的代理性能。

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

Deployment

Execution environment

Context management

Delegation

Steering

Frontend

Protocols

前提条件

第一步：安装依赖

第二步：设置你的 API 密钥

第三步：创建一个搜索工具

第四步：创建一个深度代理

第五步：设置 LangSmith 跟踪

第六步：运行代理

它是如何工作的？

示例

流式传输

后续步骤

​前提条件

​第一步：安装依赖

​第二步：设置你的 API 密钥

​第三步：创建一个搜索工具

​第四步：创建一个深度代理

​第五步：设置 LangSmith 跟踪

​第六步：运行代理

​它是如何工作的？

​示例

​流式传输

​后续步骤

前提条件

第一步：安装依赖

第二步：设置你的 API 密钥

第三步：创建一个搜索工具

第四步：创建一个深度代理

第五步：设置 LangSmith 跟踪

第六步：运行代理

它是如何工作的？

示例

流式传输

后续步骤