本指南将引导你创建第一个具备文件系统工具和子智能体能力的深度智能体。你将构建一个能够开展研究并撰写报告的研究智能体。

TIP

正在使用 AI 编程助手？

• 安装 LangChain 文档 MCP 服务器，让你的智能体访问最新的 LangChain 文档和示例。
• 安装 LangChain Skills 以提高你的智能体在 LangChain 生态任务上的表现。

先决条件

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

INFO

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

第 1 步：安装依赖

Python · pip

pip install deepagents

Python · uv

uv init
uv add deepagents
uv sync

TypeScript · npm

npm install deepagents langchain @langchain/core

TypeScript · yarn

yarn add deepagents langchain @langchain/core

TypeScript · pnpm

pnpm add deepagents langchain @langchain/core

INFO

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

pip install tavily-python

npm install @langchain/tavily

第 2 步：设置 API 密钥

Google

export GOOGLE_API_KEY="your-api-key"

OpenAI

export OPENAI_API_KEY="your-api-key"

Anthropic

export ANTHROPIC_API_KEY="your-api-key"

OpenRouter

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

Fireworks

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

Baseten

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

Ollama

# 本地：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 对话模型](/oss/deepagents/models#supported-models)配合使用。为你的提供商设置 API 密钥。

TIP

使用 LangSmith Gateway

LangSmith Gateway 将大多数主流提供商路由到 LangSmith。你可以自带提供商密钥，或使用 Gateway Credits 在无需提供商密钥的情况下访问模型。

第 3 步：创建搜索工具

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

提供商搜索（推荐）

Python · Google

from deepagents import create_deep_agent

# Google 内置搜索——无需额外安装或 API 密钥
internet_search = {"google_search": {}}

Python · OpenAI

from deepagents import create_deep_agent

# OpenAI 内置网页搜索——无需额外安装或 API 密钥
internet_search = {"type": "web_search"}

Python · Anthropic

from deepagents import create_deep_agent

# Anthropic 内置网页搜索——无需额外安装或 API 密钥
internet_search = {"type": "web_search_20260209", "name": "web_search"}

TypeScript · Google

import { createDeepAgent } from "deepagents";

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

TypeScript · OpenAI

import { createDeepAgent } from "deepagents";

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

TypeScript · Anthropic

import { createDeepAgent } from "deepagents";

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

Tavily（任意提供商）

import os
from typing import Literal

from tavily import TavilyClient
from deepagents import create_deep_agent

tavily_client = TavilyClient(api_key=os.environ["TAVILY_API_KEY"])

def internet_search(
query: str,
max_results: int = 5,
topic: Literal["general", "news", "finance"] = "general",
include_raw_content: bool = False,
):
"""Run a web search"""
return tavily_client.search(
query,
max_results=max_results,
include_raw_content=include_raw_content,
topic=topic,
)

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"),
}),
},
);

第 4 步：创建深度智能体

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

Python · Google

# 用于引导智能体成为专家研究员的系统提示词
research_instructions = """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.
"""

agent = create_deep_agent(
    model="google_genai:gemini-3.6-flash",
    tools=[internet_search],
    system_prompt=research_instructions,
)

Python · OpenAI

# 用于引导智能体成为专家研究员的系统提示词
research_instructions = """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.
"""

agent = create_deep_agent(
    model="openai:gpt-5.5",
    tools=[internet_search],
    system_prompt=research_instructions,
)

Python · Anthropic

# 用于引导智能体成为专家研究员的系统提示词
research_instructions = """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.
"""

agent = create_deep_agent(
    model="anthropic:claude-sonnet-4-6",
    tools=[internet_search],
    system_prompt=research_instructions,
)

Python · OpenRouter

# 用于引导智能体成为专家研究员的系统提示词
research_instructions = """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.
"""

agent = create_deep_agent(
    model="openrouter:z-ai/glm-5.2",
    tools=[internet_search],
    system_prompt=research_instructions,
)

Python · Fireworks

# 用于引导智能体成为专家研究员的系统提示词
research_instructions = """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.
"""

agent = create_deep_agent(
    model="fireworks:accounts/fireworks/models/glm-5p2",
    tools=[internet_search],
    system_prompt=research_instructions,
)

Python · Baseten

# 用于引导智能体成为专家研究员的系统提示词
research_instructions = """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.
"""

agent = create_deep_agent(
    model="baseten:zai-org/GLM-5.2",
    tools=[internet_search],
    system_prompt=research_instructions,
)

Python · Ollama

# 用于引导智能体成为专家研究员的系统提示词
research_instructions = """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.
"""

agent = create_deep_agent(
    model="ollama:north-mini-code-1.0",
    tools=[internet_search],
    system_prompt=research_instructions,
)

TypeScript · Google

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-genai:gemini-3.6-flash",
  tools: [internetSearch],
  systemPrompt: researchInstructions,
});

TypeScript · OpenAI

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,
});

TypeScript · Anthropic

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-4-6",
  tools: [internetSearch],
  systemPrompt: researchInstructions,
});

TypeScript · OpenRouter

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:openrouter:z-ai/glm-5.2",
  tools: [internetSearch],
  systemPrompt: researchInstructions,
});

TypeScript · Fireworks

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,
});

TypeScript · Baseten

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,
});

TypeScript · Ollama

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 密钥，并设置以下环境变量：

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

第 6 步：运行智能体

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

# 打印智能体的响应
print(result["messages"][-1].content)

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

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

它是如何工作的？

你的深度智能体会自动：

1. 开展研究：调用 internet_search 工具收集信息。
2. 管理上下文：使用文件系统工具（write_file、read_file）卸载大型搜索结果。
3. 生成子智能体：根据需要生成子智能体，将复杂的子任务委派给专门的子智能体。
4. 综合生成报告：将研究结果整理为连贯的响应。

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

示例

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

流式输出

Deep Agents 内置流式输出功能，可使用 LangGraph 实时获取智能体执行的更新。 这使你可以渐进式地观察输出，并检查和调试智能体及子智能体的工作，例如工具调用、工具结果和 LLM 响应。

后续步骤

现在你已经构建了第一个深度智能体：

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