跟踪 Deep Agents 应用程序

deepagents 是一个构建在 LangGraph 之上的开源智能体框架，专为需要规划、工具使用和子智能体委托的复杂、多步骤任务而设计。Deep Agents 支持原生 LangSmith 跟踪。本指南将向您展示如何为 Deep Agents 启用 LangSmith 跟踪、在 LangSmith 用户界面中查看跟踪记录，并（可选地）为更高级的用例自定义跟踪配置。

安装

在您的 Python 环境中安装 deepagents：

pip install deepagents

uv add deepagents

deepagents 需要：

Python 3.11+。
一个支持工具调用的 LLM（例如 OpenAI 或 Anthropic 模型）。
用于跟踪时，需要一个 LangSmith 账户和 API 密钥（注册免费）。

您无需安装 langsmith Python 包即可跟踪 Deep Agents。deepagents 构建于 LangGraph 之上，后者包含原生 LangSmith 跟踪支持。只要设置了 LangSmith 环境变量，跟踪数据就会自动发送。只有当您需要以编程方式控制跟踪时（例如，使用 tracing_context、添加自定义元数据或从 Python 查询运行记录），才需要 langsmith 包。

设置

您可以在 LangSmith 用户界面的 Settings 下找到您的 LangSmith API 密钥和项目名称：

export LANGSMITH_API_KEY=<your-langsmith-api-key>
export LANGSMITH_TRACING=true
export LANGSMITH_PROJECT=<your-project-name>

创建跟踪

一旦通过环境变量启用了跟踪，Deep Agents 将自动向 LangSmith 发送跟踪数据。例如：

from typing import Dict, Any, List

from deepagents import create_deep_agent


def compute_compound_interest(
    principal: float,
    annual_rate: float,
    years: int,
    compounds_per_year: int,
) -> Dict[str, Any]:
    """计算复利并返回最终余额和赚取的利息。"""
    r = annual_rate
    n = compounds_per_year
    t = years
    amount = principal * (1 + r / n) ** (n * t)
    interest = amount - principal
    return {
        "principal": principal,
        "annual_rate": annual_rate,
        "years": years,
        "compounds_per_year": n,
        "ending_balance": round(amount, 2),
        "interest_earned": round(interest, 2),
    }


def yearly_balance_schedule(
    principal: float,
    annual_rate: float,
    years: int,
    compounds_per_year: int,
) -> List[Dict[str, Any]]:
    """返回投资的逐年余额计划。"""
    r = annual_rate
    n = compounds_per_year
    schedule: List[Dict[str, Any]] = []

    for year in range(1, years + 1):
        amount = principal * (1 + r / n) ** (n * year)
        schedule.append(
            {
                "year": year,
                "ending_balance": round(amount, 2),
                "interest_earned": round(amount - principal, 2),
            }
        )

    return schedule


agent = create_deep_agent(
    model="google_genai:gemini-3.6-flash",
    tools=[compute_compound_interest, yearly_balance_schedule],
    system_prompt=(
        "你是一个细心的助手。"
        "使用工具进行计算和结构化输出。"
        "返回简洁的最终答案。"
    ),
)

result = agent.invoke(
    {
        "messages": [
            {
                "role": "user",
                "content": (
                    "我有 2500 美元以 6% 的年利率按月复利投资了 5 年。\n"
                    "1) 计算最终余额和赚取的总利息。\n"
                    "2) 生成一个逐年最终余额计划。\n"
                    "然后用 3 个要点总结关键收获。\n\n"
                    "使用 compounds_per_year=12。"
                ),
            }
        ]
    }
)

print(result)

查看跟踪

详细信息视图

点击跟踪记录，并在右上角切换到 Details 视图。您在 LangSmith 用户界面中的跟踪树将看起来像这样，具有以下结构：

智能体运行（顶层）代表完整的 Deep Agents 调用。
LLM 调用，智能体在此分析用户请求并决定使用哪些工具。
工具运行：compute_compound_interest：
- 显示工具输入（例如 principal, annual_rate, years 和 compounds_per_year）。
- 显示结构化输出，包括最终余额和赚取的总利息。
LLM 调用，用于解释计算结果并确定下一步。
工具运行：yearly_balance_schedule：
- 显示用于生成计划的输入。
- 返回逐年最终余额和赚取利息的明细。
最终的 LLM 响应，为用户总结结果。

生成的跟踪包含多个嵌套跨度，这允许您在 LangSmith 用户界面中跟踪智能体的规划、计算步骤和解释流程。

消息视图

LangSmith 用户界面中的 Messages 视图显示了用户与智能体之间的简化对话历史记录。此视图从顶层跟踪中提取消息（包括用户的初始请求、工具调用和智能体的最终响应），并以类似聊天的格式呈现它们。

按子智能体筛选

Deep Agents 会自动将子智能体的 name 写入该子智能体产生的每个运行记录的 lc_agent_name 元数据键中。使用此功能可以在 LangSmith 中隔离来自特定子智能体的所有运行记录——这对于调试、监控或比较子智能体行为非常有用。 在 LangSmith 用户界面中筛选：

在 LangSmith 中打开您的跟踪项目。
将视图切换到 Runs 以查看各个跨度。
点击 Add filter 并选择 Metadata。
将 Key 设置为 lc_agent_name，将 Value 设置为子智能体名称，例如 coordinator。

LangSmith 运行视图，显示对 lc_agent_name 设置为 coordinator 的元数据筛选器

将筛选器保存为命名视图以便快速重用。有关筛选选项的完整参考，请参阅筛选跟踪记录。 使用 SDK 以编程方式筛选：

from langsmith import Client

client = Client()

# 获取由特定子智能体产生的所有运行记录
runs = client.list_runs(
    project_name="<your-project>",
    filter='has(metadata, \'{"lc_agent_name": "research-agent"}\')',
)

for run in runs:
    print(run.name, run.start_time, run.status)

有关筛选查询语言的完整参考，请参阅跟踪查询语法。

自定义 LangSmith 跟踪

默认情况下，当通过环境变量启用 LangSmith 跟踪时，Deep Agents 的跟踪数据会自动发送。您可以直接使用 LangSmith SDK 来自定义您的跟踪，例如将跟踪范围限定在代码的某部分、附加标签或元数据，或者覆盖项目名称。如果您想要执行以下操作，请安装并使用 langsmith：

仅跟踪特定的智能体调用。
添加自定义标签或元数据以在用户界面中进行筛选。
在运行时覆盖项目名称。

pip install langsmith

uv add langsmith

此示例调用了相同的 deep agent 两次：

第一次调用未被跟踪，因为它运行在 tracing_context 之外。
第二次调用被跟踪，因为它运行在 tracing_context(enabled=True, ...) 内部。

您可以有选择地仅跟踪工作流的一部分，而无需使用 LANGSMITH_TRACING=true 为整个进程启用全局跟踪：

from typing import Dict, Any, List

import langsmith as ls
from deepagents import create_deep_agent


def compute_compound_interest(
    principal: float,
    annual_rate: float,
    years: int,
    compounds_per_year: int,
) -> Dict[str, Any]:
    """计算复利并返回最终余额和赚取的利息。"""
    r = annual_rate
    n = compounds_per_year
    t = years
    amount = principal * (1 + r / n) ** (n * t)
    interest = amount - principal
    return {
        "principal": principal,
        "annual_rate": annual_rate,
        "years": years,
        "compounds_per_year": n,
        "ending_balance": round(amount, 2),
        "interest_earned": round(interest, 2),
    }


def yearly_balance_schedule(
    principal: float,
    annual_rate: float,
    years: int,
    compounds_per_year: int,
) -> List[Dict[str, Any]]:
    """返回投资的逐年余额计划。"""
    r = annual_rate
    n = compounds_per_year
    schedule: List[Dict[str, Any]] = []

    for year in range(1, years + 1):
        amount = principal * (1 + r / n) ** (n * year)
        schedule.append(
            {
                "year": year,
                "ending_balance": round(amount, 2),
                "interest_earned": round(amount - principal, 2),
            }
        )

    return schedule


agent = create_deep_agent(
    model="google_genai:gemini-3.6-flash",
    tools=[compute_compound_interest, yearly_balance_schedule],
    system_prompt=(
        "你是一个细心的助手。"
        "使用工具进行计算和结构化输出。"
        "返回简洁的最终答案。"
    ),
)

# ----------------------------
# 未跟踪的调用
# ----------------------------
agent.invoke(
    {
        "messages": [
            {
                "role": "user",
                "content": (
                    "我有 2500 美元以 6% 的年利率按月复利投资了 5 年。"
                    "计算最终余额和赚取的总利息。"
                    "使用 compounds_per_year=12。"
                ),
            }
        ]
    }
)

# ----------------------------
# 被跟踪的调用
# ----------------------------
with ls.tracing_context(
    enabled=True,
    project_name="deepagents-demo",
    tags=["deepagents", "scoped-tracing"],
    metadata={"example": "partial-workflow"},
):
    agent.invoke(
        {
            "messages": [
                {
                    "role": "user",
                    "content": (
                        "我有 2500 美元以 6% 的年利率按月复利投资了 5 年。\n"
                        "1) 计算最终余额和赚取的总利息。\n"
                        "2) 生成一个逐年最终余额计划。\n"
                        "然后用 3 个要点总结关键收获。\n\n"
                        "使用 compounds_per_year=12。"
                    ),
                }
            ]
        }
    )

tracing_context 块启用了跟踪，并配置了跟踪数据在 LangSmith 中的记录和组织方式：

enabled=True 为该代码块的持续时间显式启用跟踪，即使 LANGSMITH_TRACING 未设置或设置为 false。
project_name="deepagents-demo" 将此代码块的跟踪数据路由到指定的 LangSmith 项目。这会覆盖在上下文中创建的运行记录的 LANGSMITH_PROJECT。
tags=[...] 将标签附加到被跟踪的运行记录上。标签会出现在 LangSmith 用户界面中，您可以使用它们来筛选和分组跟踪记录。
metadata={...} 附加任意的结构化元数据（例如环境、实验名称或功能标志）。

在此示例中，智能体被调用了两次，但只有在 tracing_context 内的调用被记录下来。这演示了如何在不为整个进程启用全局跟踪的情况下，有选择地跟踪 Deep Agents 工作流的特定部分。

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

Tracing setup

Configuration & troubleshooting

安装

设置

创建跟踪

查看跟踪

详细信息视图

消息视图

按子智能体筛选

自定义 LangSmith 跟踪

​安装

​设置

​创建跟踪

​查看跟踪

​详细信息视图

​消息视图

​按子智能体筛选

​自定义 LangSmith 跟踪

安装

设置

创建跟踪

查看跟踪

详细信息视图

消息视图

按子智能体筛选

自定义 LangSmith 跟踪