快速入门

我们要构建什么

一个能自主规划、搜索、总结的研究型 Agent

传统聊天机器人只能一问一答。但现实中的研究任务需要多步推理、工具调用、上下文管理。Deep Agent 就是为此而生。

前提条件

安装依赖

只需一行命令，安装核心包和搜索工具

Deep Agents 的核心包是 deepagents，配合 langchain 和 @langchain/tavily 即可快速启动。

$ npm install deepagents langchain @langchain/core @langchain/tavily

$ yarn add deepagents langchain @langchain/core @langchain/tavily

$ pnpm add deepagents langchain @langchain/core @langchain/tavily

配置密钥

配置你的模型提供商和搜索服务的密钥

Deep Agents 通过环境变量读取 API Key。根据你的模型提供商设置对应的变量：

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

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

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

# DeepSeek 通过 @langchain/community 的 ChatDeepSeek 接入
# 或直接使用 "deepseek:模型名" 字符串（如 deepseek:deepseek-chat）
export DEEPSEEK_API_KEY="your-api-key"
export TAVILY_API_KEY="your-tavily-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 Key 以进行托管推理
export OLLAMA_API_KEY="your-api-key"
export TAVILY_API_KEY="your-tavily-api-key"

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

// Google Gemini
model: "google-genai:gemini-3.1-pro-preview"

// OpenAI
model: "openai:gpt-5.5"

// Anthropic
model: "anthropic:claude-sonnet-4-6"

// DeepSeek（通过 @langchain/community 的 ChatDeepSeek，或直接用 "deepseek:模型名"）
model: "deepseek:deepseek-chat"        // 稳妥示例：具体可用型号与参数以 DeepSeek 官方公告为准

// Ollama 本地
model: "ollama:llama3"

创建搜索工具

用 LangChain 的 tool 函数封装 Tavily 搜索能力

工具是 Agent 感知外部世界的手脚。我们用 tool() 函数把 Tavily 搜索封装成 Agent 可调用的工具。

比喻是为了帮你理解——实际上，工具不过是一段定义了 name、description 和 schema 的函数。Agent 通过 LLM 的 tool calling 能力来决定何时调用它，并非真的有"手脚"。

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

// 定义搜索工具：tool() 接收执行函数和元数据两个参数
const internetSearch = tool(
  // 执行函数：每次 Agent 决定搜索时调用
  async ({
    query,                     // 搜索关键词
    maxResults = 5,            // 最多返回几条结果
    topic = "general",         // 搜索类别：general / news / finance
    includeRawContent = false, // 是否包含原始网页内容（更耗 token）
  }: {
    query: string;
    maxResults?: number;
    topic?: "general" | "news" | "finance";
    includeRawContent?: boolean;
  }) => {
    // 创建 Tavily 搜索实例，传入 API Key 和配置
    const tavilySearch = new TavilySearch({
      maxResults,
      tavilyApiKey: process.env.TAVILY_API_KEY,
      includeRawContent,
      topic,
    });
    // _call() 执行搜索并返回结果
    return await tavilySearch._call({ query });
  },
  // 元数据：帮助 LLM 理解工具的用途和参数
  {
    name: "internet_search",        // Agent 调用时的工具名称
    description: "Run a web search", // LLM 据此判断何时该调用此工具
    schema: z.object({
      query: z.string().describe("The search query"),
      maxResults: z.number().optional().default(5)
        .describe("Maximum number of results"),
      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"),
    }),
  },
);

工具代码解读

理解 tool() 函数的两个核心部分

创建智能体

用 createDeepAgent() 一行代码组装完整智能体

接下来，用 createDeepAgent() 把模型、工具和系统提示词组合在一起：

import { createDeepAgent } from "deepagents";

// 系统提示词：定义 Agent 的角色、工作方式和工具使用说明
// 这个提示词会叠加在 SDK 内置提示之上，不会替换它
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-genai:gemini-3.1-pro-preview",  // 以 "provider:model" 格式指定模型
  tools: [internetSearch],                         // Agent 会自主决定何时调用搜索
  systemPrompt: researchInstructions,              // 你的自定义提示叠加在 SDK 默认提示之上
});

import { createDeepAgent } from "deepagents";

// 系统提示词：引导 Agent 成为专业研究人员
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,
});

import { createDeepAgent } from "deepagents";

// 系统提示词：引导 Agent 成为专业研究人员
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-4-6",
  tools: [internetSearch],
  systemPrompt: researchInstructions,
});

import { createDeepAgent } from "deepagents";

// 系统提示词：引导 Agent 成为专业研究人员
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: "deepseek:deepseek-chat",       // 稳妥示例：具体可用型号以 DeepSeek 官方公告为准
  tools: [internetSearch],
  systemPrompt: researchInstructions,
});

import { createDeepAgent } from "deepagents";

// 系统提示词：引导 Agent 成为专业研究人员
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:anthropic/claude-sonnet-4-6",
  tools: [internetSearch],
  systemPrompt: researchInstructions,
});

import { createDeepAgent } from "deepagents";

// 系统提示词：引导 Agent 成为专业研究人员
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/qwen3p5-397b-a17b",
  tools: [internetSearch],
  systemPrompt: researchInstructions,
});

import { createDeepAgent } from "deepagents";

// 系统提示词：引导 Agent 成为专业研究人员
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",
  tools: [internetSearch],
  systemPrompt: researchInstructions,
});

import { createDeepAgent } from "deepagents";

// 系统提示词：引导 Agent 成为专业研究人员
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:llama3",
  tools: [internetSearch],
  systemPrompt: researchInstructions,
});

代码逐行解读

理解 createDeepAgent 的每个参数

运行 Agent

用 invoke() 启动 Agent，传入用户消息即可

创建好 Agent 后，用 invoke() 方法运行它。传入一个包含用户消息的对象：

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

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

工作原理

Deep Agent 自动执行五个阶段

当你调用 invoke() 后，Deep Agent 会自动执行以下步骤：

流式输出

实时获取 Agent 执行的每一步更新

invoke() 会等待整个任务完成后才返回。如果你需要实时监控 Agent 的执行过程，可以使用流式输出。

// 流式获取 Agent 执行过程 —— 每完成一步就推送一个事件
const stream = await agent.stream({
  messages: [{ role: "user", content: "What is langgraph?" }],
});

for await (const event of stream) {
  // 每个 event 包含一步更新的信息
  // 事件类型包括：工具调用（tool_calls）、工具结果（tool_results）、LLM 响应等
  console.log(event);
}

调试与追踪

用 LangSmith 可视化查看 Agent 的完整执行过程

当 Agent 行为不符合预期时，LangSmith 能帮你追踪每一个规划步骤、工具调用和子 Agent 委派。

完整代码汇总

从零到运行的所有代码，一个文件搞定

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

// 1. 创建搜索工具 —— 封装 Tavily API 为 LangChain 工具格式
const internetSearch = tool(
  async ({ query, maxResults = 5, topic = "general" }) => {
    const tavilySearch = new TavilySearch({
      maxResults,
      tavilyApiKey: process.env.TAVILY_API_KEY,  // 从环境变量读取密钥
      topic,
    });
    return await tavilySearch._call({ query });    // 执行搜索并返回结果
  },
  {
    name: "internet_search",
    description: "Run a web search",
    schema: z.object({
      query: z.string().describe("The search query"),
    }),
  },
);

// 2. 创建 Deep Agent —— 传入模型、工具和系统提示词
const agent = createDeepAgent({
  model: "google-genai:gemini-3.1-pro-preview",
  tools: [internetSearch],
  systemPrompt: "You are an expert researcher. "
    + "Conduct thorough research and write reports.",
});

// 3. 运行 —— invoke() 等待完整结果后返回
const result = await agent.invoke({
  messages: [{ role: "user", content: "What is langgraph?" }],
});
// result.messages 数组包含完整对话历史，最后一条是 Agent 最终回复
console.log(result.messages[result.messages.length - 1].content);

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

// 1. 创建搜索工具 —— 封装 Tavily API 为 LangChain 工具格式
const internetSearch = tool(
  async ({ query, maxResults = 5, topic = "general" }) => {
    const tavilySearch = new TavilySearch({
      maxResults,
      tavilyApiKey: process.env.TAVILY_API_KEY,  // 从环境变量读取密钥
      topic,
    });
    return await tavilySearch._call({ query });    // 执行搜索并返回结果
  },
  {
    name: "internet_search",
    description: "Run a web search",
    schema: z.object({
      query: z.string().describe("The search query"),
    }),
  },
);

// 2. 创建 Deep Agent —— 使用 DeepSeek 模型
const agent = createDeepAgent({
  model: "deepseek:deepseek-chat",       // 稳妥示例：具体可用型号以 DeepSeek 官方公告为准
  tools: [internetSearch],
  systemPrompt: "You are an expert researcher. "
    + "Conduct thorough research and write reports.",
});

// 3. 运行 —— invoke() 等待完整结果后返回
const result = await agent.invoke({
  messages: [{ role: "user", content: "What is langgraph?" }],
});
console.log(result.messages[result.messages.length - 1].content);

下一步学什么

你已经构建了第一个 Deep Agent，接下来可以深入这些方向