尚拙
Search K

Appearance

快速起步 ​

在几分钟内构建你的第一个 deep agent

本指南将带领你使用文件系统工具和子智能体能力创建第一个 deep agent。你将构建一个能够进行深入调研并撰写报告的研究型智能体。

构建 Deep Agents 研究快速起步案例：在工作目录中按照 Deep Agents 快速起步指引构建一个研究智能体。

步骤 1：阅读指南 ​

检测项目使用的是 Python 还是 TypeScript/JavaScript。根据对应的页面进行操作，并将其作为包名、模型字符串、搜索工具配置和代码的准确来源：

步骤 2：安装依赖 ​

使用当前项目已有的包管理器安装 deepagents（在 TypeScript 中还包括 langchain / @langchain/core）。仅在用户未选择使用 Google、OpenAI 或 Anthropic 内置的提供商搜索工具时，才添加 Tavily。

步骤 3：配置模型凭据 ​

检查受支持的提供商 API 密钥（例如 GOOGLE_API_KEY、OPENAI_API_KEY 或 ANTHROPIC_API_KEY）。如果尚未设置，请询问用户要使用哪家提供商，然后暂停等待他们在 Shell 或 .env 文件中设置密钥。请勿虚构、硬编码或提交 API 密钥。如果需要 Tavily，同样要求设置 TAVILY_API_KEY。

步骤 4：实现研究智能体 ​

按顺序执行以下快速起步步骤：

  1. 创建网络搜索工具（所选模型支持时优先使用提供商内置搜索工具；否则使用 Tavily）。
  2. 调用 create_deep_agent，传入搜索工具、指南中推荐的 provider:model 字符串（或已初始化的模型实例）以及页面上展示的研究系统提示词。
  3. （可选）提示用户自行设置 LANGSMITH_TRACING=true 和 LANGSMITH_API_KEY 以启用 LangSmith 追踪。
  4. 针对指南中的示例调研问题运行智能体，并打印最终响应。

规则 ​

  • 紧扣本快速起步的范围。不要混入 Managed Deep Agents 部署、评测或不相关的框架。
  • 只要可用，优先使用提供商内置的网络搜索；仅在需要时使用 Tavily。
  • 当凭证、提供商选择或项目约定不明确时，主动询问而不是凭空猜测。

TIP

正在使用 AI 编码助手？

  • 安装 LangChain 文档 MCP 服务器，让你的智能体能够访问最新的 LangChain 文档和示例。

    连接 LangChain 文档 MCP 服务器

    将两个 LangChain 文档 MCP 服务器连接到编码智能体，以便其查阅当前的 LangChain、LangGraph 和 LangSmith 文档及 API 参考。

    需添加的服务器：

    检测当前使用的智能体或编辑器（Claude Code、Cursor、Codex CLI、Claude Desktop、Deep Agents Code、VS Code、Antigravity 或其他兼容 MCP 的客户端）。参考 https://docs.langchain.com/use-these-docs.md 进行匹配配置：

    • Claude Code：针对每个服务器执行 claude mcp add --transport http（默认项目级作用域；仅在需要全局访问时使用 --scope user）。
    • Codex CLI：使用每个服务器的 URL 执行 codex mcp add。
    • Cursor、Deep Agents Code、VS Code 或 Antigravity：使用对应客户端所示字段将两项合并到 MCP 设置 JSON 中。
    • Claude Desktop：在 Settings > Connectors 下添加这两个 URL。

    请勿伪造备用 MCP URL。配置完成后，确认两个服务器均已列出且可正常访问。

  • 安装 LangChain Skills，以提高智能体在 LangChain 生态系统任务上的表现。

    安装 LangChain Skills

    为编码智能体安装 LangChain Skills，以提升其在 LangChain、LangGraph 和 Deep Agents 任务上的执行能力。

    使用来自 https://github.com/langchain-ai/langchain-skills 的 Agent Skills 安装器：

    bash
    npx skills add langchain-ai/langchain-skills --skill '*' --yes

    如果需要全局安装，请使用：

    bash
    npx skills add langchain-ai/langchain-skills --skill '*' --yes --global

    检测所使用的智能体或编辑器。如果使用 Claude Code 且偏好插件形式，请按照该仓库 README 中的市场安装指引操作（先 /plugin marketplace add 再 /plugin install）。请勿虚构替代技能包名称或安装 URL。安装完成后，确认技能对智能体可用。

前置准备 ​

在开始之前，请确保你拥有来自模型提供商（如 Gemini、Anthropic、OpenAI）的 API 密钥。

NOTE

Deep Agents 需要支持工具调用（tool calling）的模型。关于如何配置模型，请参阅自定义。

步骤 1：安装依赖 ​

bash
npm install deepagents langchain @langchain/core
bash
yarn add deepagents langchain @langchain/core
bash
pnpm add deepagents langchain @langchain/core

NOTE

Google、OpenAI 和 Anthropic 均提供内置的网络搜索工具：无需额外安装软件包或 API 密钥。如果你使用其他提供商或更偏好 Tavily 进行搜索，也请安装 Tavily 依赖包：

bash
npm install @langchain/tavily

步骤 2：设置 API 密钥 ​

Google

bash
export GOOGLE_API_KEY="your-api-key"

OpenAI

bash
export OPENAI_API_KEY="your-api-key"

Anthropic

bash
export ANTHROPIC_API_KEY="your-api-key"

OpenRouter

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

Fireworks

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

Baseten

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

Ollama

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

其他提供商

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

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

TIP

使用 LangSmith Gateway

LangSmith Gateway 可以将大部分主流提供商通过 LangSmith 进行统一路由。你可以自带提供商密钥，或使用 Gateway Credits 在无需提供商密钥的情况下访问模型。

步骤 3：创建搜索工具 ​

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

提供商内置搜索（推荐）

ts
import { createDeepAgent } from "deepagents";

// Google 内置搜索 — 无需额外安装或 API 密钥
const internetSearch = { googleSearch: {} };
ts
import { createDeepAgent } from "deepagents";

// OpenAI 内置网络搜索 — 无需额外安装或 API 密钥
const internetSearch = { type: "web_search_preview" };
ts
import { createDeepAgent } from "deepagents";

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

Tavily（支持任何提供商）

ts
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: "执行网络搜索",
    schema: z.object({
      query: z.string().describe("搜索查询语句"),
      maxResults: z
        .number()
        .optional()
        .default(5)
        .describe("返回的最大结果数"),
      topic: z
        .enum(["general", "news", "finance"])
        .optional()
        .default("general")
        .describe("搜索主题分类"),
      includeRawContent: z
        .boolean()
        .optional()
        .default(false)
        .describe("是否包含原始内容"),
    }),
  },
);

步骤 4：创建 Deep Agent ​

将你的搜索工具和模型传递给 create_deep_agent。传入形如 provider:model 格式的模型字符串，或传入已初始化的模型实例。请参阅受支持的模型查看所有提供商，并参阅推荐模型了解经过测试的建议。

ts
import { createDeepAgent } from "deepagents";

// 引导智能体成为专家研究员的系统提示词
const researchInstructions = `You are an expert researcher. Your job is to conduct thorough research and then write a polished report.

You have access to an internet search tool as your primary means of gathering information.

## \`internet_search\`

Use this to run an internet search for a given query. You can specify the max number of results to return, the topic, and whether raw content should be included.
`;

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

// 引导智能体成为专家研究员的系统提示词
const researchInstructions = `You are an expert researcher. Your job is to conduct thorough research and then write a polished report.

You have access to an internet search tool as your primary means of gathering information.

## \`internet_search\`

Use this to run an internet search for a given query. You can specify the max number of results to return, the topic, and whether raw content should be included.
`;

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

// 引导智能体成为专家研究员的系统提示词
const researchInstructions = `You are an expert researcher. Your job is to conduct thorough research and then write a polished report.

You have access to an internet search tool as your primary means of gathering information.

## \`internet_search\`

Use this to run an internet search for a given query. You can specify the max number of results to return, the topic, and whether raw content should be included.
`;

const agent = createDeepAgent({
  model: "anthropic:claude-sonnet-5",
  tools: [internetSearch],
  systemPrompt: researchInstructions,
});
ts
import { createDeepAgent } from "deepagents";

// 引导智能体成为专家研究员的系统提示词
const researchInstructions = `You are an expert researcher. Your job is to conduct thorough research and then write a polished report.

You have access to an internet search tool as your primary means of gathering information.

## \`internet_search\`

Use this to run an internet search for a given query. You can specify the max number of results to return, the topic, and whether raw content should be included.
`;

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

// 引导智能体成为专家研究员的系统提示词
const researchInstructions = `You are an expert researcher. Your job is to conduct thorough research and then write a polished report.

You have access to an internet search tool as your primary means of gathering information.

## \`internet_search\`

Use this to run an internet search for a given query. You can specify the max number of results to return, the topic, and whether raw content should be included.
`;

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

// 引导智能体成为专家研究员的系统提示词
const researchInstructions = `You are an expert researcher. Your job is to conduct thorough research and then write a polished report.

You have access to an internet search tool as your primary means of gathering information.

## \`internet_search\`

Use this to run an internet search for a given query. You can specify the max number of results to return, the topic, and whether raw content should be included.
`;

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

// 引导智能体成为专家研究员的系统提示词
const researchInstructions = `You are an expert researcher. Your job is to conduct thorough research and then write a polished report.

You have access to an internet search tool as your primary means of gathering information.

## \`internet_search\`

Use this to run an internet search for a given query. You can specify the max number of results to return, the topic, and whether raw content should be included.
`;

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

步骤 5：配置 LangSmith 追踪 ​

LangSmith 为你提供了智能体执行的可视化洞察，使你能够查看工具调用、子智能体委派和 LLM 响应。

在 smith.langchain.com 注册，创建 API 密钥，并设置以下环境变量：

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

步骤 6：运行智能体 ​

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

// 打印智能体的响应
console.log(result.messages[result.messages.length - 1].content);

工作原理是什么？ ​

你的 deep agent 会自动完成以下流程：

  1. 执行研究：通过调用 internet_search 工具收集信息。
  2. 管理上下文：使用文件系统工具（write_file、read_file）将大型搜索结果卸载保存。
  3. 衍生子智能体：根据需要将复杂的子任务委派给专门的子智能体。
  4. 综合撰写报告：将调研发现汇编为条理清晰的最终响应。

要使用 write_todos 添加结构化任务规划，可以通过 TodoListMiddleware 自主选择开启。参见任务规划。

示例 ​

有关可以使用 Deep Agents 构建的智能体、模式和应用程序，请参阅示例仓库。

流式传输 ​

Deep Agents 内置了使用 LangGraph 进行实时更新的流式传输支持。 这使你可以渐进式观察输出，并审查和调试智能体与子智能体的工作过程，例如工具调用、工具执行结果和 LLM 响应。

下一步 ​

现在你已经构建了第一个 deep agent：

  • 自定义你的智能体：了解自定义选项，包括自定义系统提示词、工具和子智能体。
  • 添加长期记忆：启用跨会话的持久记忆。
  • 部署到生产环境：使用 Managed Deep Agents 在 LangSmith 中创建、运行和运营 deep agents。
  • 测试与评估：使用 LangSmith 评估运行自动化测试，并根据数据集衡量智能体的表现。