快速开始

在几分钟内构建你的第一个深度智能体

本指南将带你创建你的第一个具有文件系统工具和子智能体能力的深度智能体。你将构建一个能够进行研究并撰写报告的研究智能体。

按照 Deep Agents 快速入门，在此工作目录中构建一个 Deep Agents 研究智能体。

第 1 步：阅读指南

检测此项目使用的是 Python 还是 TypeScript/JavaScript。获取并遵循匹配的页面；将其视为包名称、模型字符串、搜索工具设置和代码的权威来源：

• Python：https://www.bytesrouter.com/langchain/oss/python/deepagents/quickstart
• TypeScript：https://www.bytesrouter.com/langchain/oss/javascript/deepagents/quickstart

第 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. 使用搜索工具、指南中的 provider:model 字符串（或已初始化的模型）以及页面上展示的研究系统提示词来调用 create_deep_agent。
3. 可选地启用 LangSmith 追踪，方法是请用户自行设置 LANGSMITH_TRACING=true 和 LANGSMITH_API_KEY。
4. 使用指南中的一个示例研究查询运行智能体，并打印最终响应。

规则

• 请将范围限定在本快速入门内。不要添加 Managed Deep Agents 部署、评估或无关的框架。
• 在可用时优先使用服务商内置网络搜索；仅在需要时使用 Tavily。
• 当密钥、服务商选择或项目约定不明确时，请询问而不是猜测。

TIP

使用 AI 编码助手？

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

将两个 LangChain 文档 MCP 服务器都连接到我的编码智能体，以便它能查询最新的 LangChain、LangGraph 和 LangSmith 文档及 API 参考。

要添加的服务器：

* `docs-langchain`: [https://docs.langchain.com/mcp](/mcp)
* `reference-langchain`: [https://reference.langchain.com/mcp](https://reference.langchain.com/mcp)

检测我正在使用哪个智能体或编辑器（Claude Code、Cursor、Codex CLI、Claude Desktop、Deep Agents Code、VS Code、Antigravity 或其他兼容 MCP 的客户端）。使用 [https://docs.langchain.com/use-these-docs.md](/langchain/use-these-docs) 中匹配的设置：

* Claude Code：为每个服务器使用 `claude mcp add --transport http`（默认项目范围；只有在我要求全局访问时才使用 `--scope user`）。
* Codex CLI：使用 `codex mcp add` 加上每个服务器的 URL。
* Cursor、Deep Agents Code、VS Code 或 Antigravity：使用该页面为我的客户端显示的字段名，将两个条目合并到 MCP 设置 JSON 中。
* Claude Desktop：在 Settings > Connectors 下添加两个 URL。

不要凭空编造其他 MCP URL。配置完成后，确认两个服务器都已列出且可访问。

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

为我的编码智能体安装 LangChain Skills，使其在 LangChain、LangGraph 和 Deep Agents 任务上表现更好。

使用来自 [https://github.com/langchain-ai/langchain-skills](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。安装完成后，确认这些技能对智能体可用。

前置条件

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

NOTE

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

步骤 1：安装依赖项

pip

pip install deepagents

uv

uv init
uv add deepagents
uv sync

NOTE

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

pip install tavily-python

步骤 2：设置你的 API 密钥

export GOOGLE_API_KEY="your-api-key"

TIP

使用 LangSmith Gateway

LangSmith Gateway 将大多数主流服务商路由到 LangSmith。你可以携带自己的服务商密钥，或使用 Gateway Credits 在没有服务商密钥的情况下访问模型。

步骤 3：创建搜索工具

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

Google

from deepagents import create_deep_agent

# Google's built-in search — no extra install or API key needed
internet_search = {"google_search": {}}

OpenAI

from deepagents import create_deep_agent

# OpenAI's built-in web search — no extra install or API key needed
internet_search = {"type": "web_search"}

Anthropic

from deepagents import create_deep_agent

# Anthropic's built-in web search — no extra install or API key needed
internet_search = {"type": "web_search_20260209", "name": "web_search"}

步骤 4：创建深度智能体

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

Google

# System prompt to steer the agent to be an expert researcher
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,
)

OpenAI

# System prompt to steer the agent to be an expert researcher
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,
)

Anthropic

# System prompt to steer the agent to be an expert researcher
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-5",
    tools=[internet_search],
    system_prompt=research_instructions,
)

OpenRouter

# System prompt to steer the agent to be an expert researcher
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,
)

Fireworks

# System prompt to steer the agent to be an expert researcher
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,
)

Baseten

# System prompt to steer the agent to be an expert researcher
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,
)

Ollama

# System prompt to steer the agent to be an expert researcher
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,
)

第 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 the agent's response
print(result["messages"][-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 agent。
• 测试与评估：使用 LangSmith 评估 运行自动化测试，并针对数据集衡量智能体的表现。

---