快速上手

这一页使用 Deep Agents 构建一个最小但边界明确的 Agent。它可以读取一份本地天气 fixture，并根据用户 问题决定是否调用工具。fixture 是确定性的，不会访问网络；真正的模型调用仍需要你自己的 provider 凭据，因此本仓库不会执行示例。

目标

完成后你会看到四个关键接口：

1. 用结构化 schema 定义业务工具。
2. 通过 create_deep_agent 或 createDeepAgent 组装 Harness。
3. 用 LangChain message 形状调用已编译图。
4. 从最终 state 的 messages 中读取回复。

前端类比

可以把工具 schema 类比为类型安全的 server action，把 createDeepAgent 类比为创建带默认 middleware 的应用实例，把 invoke 类比为向服务端 action 发送一次请求。

Deep Agents 原生语义：模型不是按固定路由调用工具。Deep Agents 把工具描述交给支持 tool calling 的模型，模型在 LangGraph 驱动的 Agent 循环中决定下一步；Todo、filesystem 与 subagent middleware 也处在同一个循环里。

1. 配置模型

先完成 安装、版本与模型配置，再设置经过团队验证的模型：

export DEEPAGENTS_MODEL="provider:model-name"

不要把示例占位值直接用于生产。你还需要设置对应 provider 的 API key，并确认模型支持 tool calling。

2. 定义一个确定性工具

Python

from langchain.tools import tool

WEATHER_FIXTURE = {
    "上海": "多云，24°C",
    "深圳": "阵雨，28°C",
}


@tool
def get_weather(city: str) -> str:
    """读取教程内置的城市天气 fixture。"""
    return WEATHER_FIXTURE.get(city, f"没有 {city} 的本地数据")

TypeScript

import { tool } from '@langchain/core/tools'
import { z } from 'zod'

const weatherFixture: Record<string, string> = {
  上海: '多云，24°C',
  深圳: '阵雨，28°C',
}

const getWeather = tool(({ city }) => weatherFixture[city] ?? `没有 ${city} 的本地数据`, {
  name: 'get_weather',
  description: '读取教程内置的城市天气 fixture',
  schema: z.object({
    city: z.string().describe('城市中文名'),
  }),
})

工具的描述和参数 schema 是模型选择工具时的主要依据。描述应说明它能做什么，不要把权限控制 寄托在描述文本上。

3. 使用 Deep Agents 创建并调用 Agent

Python

import os

from deepagents import create_deep_agent

model = os.environ.get("DEEPAGENTS_MODEL")
if not model:
    raise RuntimeError("DEEPAGENTS_MODEL is required")

agent = create_deep_agent(
    model=model,
    tools=[get_weather],
    system_prompt=(
        "你是旅行助理。需要天气信息时调用 get_weather；"
        "fixture 没有数据时如实说明，不要编造实时天气。"
    ),
)

result = agent.invoke(
    {
        "messages": [
            {"role": "user", "content": "上海和深圳今天哪边更适合户外散步？"}
        ]
    }
)

print(result["messages"][-1].content)

TypeScript

import { createDeepAgent } from 'deepagents'

const model = process.env.DEEPAGENTS_MODEL
if (!model) throw new Error('DEEPAGENTS_MODEL is required')

const agent = createDeepAgent({
  model,
  tools: [getWeather],
  systemPrompt:
    '你是旅行助理。需要天气信息时调用 get_weather；' +
    'fixture 没有数据时如实说明，不要编造实时天气。',
})

const result = await agent.invoke({
  messages: [
    {
      role: 'user',
      content: '上海和深圳今天哪边更适合户外散步？',
    },
  ],
})

console.log(result.messages.at(-1)?.content)

4. Harness 在背后做了什么

即使只传入一个业务工具，Agent 仍会获得 Deep Agents 的默认 Harness：

• write_todos：模型可为较长问题维护任务列表。
• filesystem 工具：默认由 StateBackend 保存当前 thread 的文件。
• task：提供 subagent 委派入口。
• summarization：接近上下文限制时压缩历史。
• tool-call patching：处理部分 provider 的工具调用兼容问题。

这个问题很短，模型可能不会写 Todo 或创建文件。Harness 提供能力，不保证模型每次都调用它们。

5. 结果不是普通字符串

invoke 返回 LangGraph state，其中 messages 包含用户消息、模型消息和工具消息。快速示例取最后 一条消息方便展示；真实应用通常还需要：

• 处理结构化 content block，而不是假设 content 永远是字符串。
• 使用 streaming 实时展示工具和 subagent 进度。
• 为多轮对话配置 checkpointer 与稳定的 thread id。
• 记录 trace，并对工具轨迹而不只是最终文本做测试。

常见问题

模型没有调用工具

检查模型是否支持 tool calling、工具描述是否明确、问题是否真的需要工具。不要用提示词强迫模型 调用一个与任务无关的工具。

Import 成功但模型初始化失败

deepagents 不包含所有 provider 实现。确认已经安装对应 LangChain 集成包，并设置 provider 所需 的环境变量。

示例能跑就可以接入真实文件系统

不可以。默认 StateBackend 是虚拟文件工作区；接入宿主文件或 shell 前必须先完成 backend、 sandbox、permissions 与安全设计。

先修

• 安装、版本与模型配置
• LangChain 工具

下一步

• Agent Harness 架构与规划

官方参考

• Python Quickstart
• JavaScript Quickstart
• Python create_deep_agent
• TypeScript CreateDeepAgentParams