追踪 Deep Agents 应用

deepagents 是一个构建在 LangGraph 之上的开源 agent 框架，专为需要规划、工具使用和子 agent 委派的复杂多步任务而设计。Deep Agents 支持原生 LangSmith 追踪。

本指南展示如何为 Deep Agents 启用 LangSmith 追踪、在 LangSmith UI 中查看追踪，以及（可选）为更高级的用例自定义追踪配置。

安装

在你的 Python 环境中安装 deepagents：

pipuv

bash

pip install deepagents

bash

uv add deepagents

deepagents 需要：

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

NOTE

你不需要安装 langsmith Python 包来追踪 Deep Agents。deepagents 构建在 LangGraph 之上，后者包含原生 LangSmith 追踪支持。只要设置了 LangSmith 环境变量，追踪就会自动发送。

仅当你需要以编程方式控制追踪时（例如使用 tracing_context、添加自定义元数据或从 Python 查询运行），才需要 langsmith 包。

设置

你可以在 LangSmith UI 的 Settings 下找到你的 LangSmith API 密钥和项目名称：

bash

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

创建追踪

通过环境变量启用追踪后，Deep Agents 会自动向 LangSmith 发出追踪。例如：

python

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]:
    """Compute compound interest and return ending balance and interest earned."""
    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]]:
    """Return a year-by-year balance schedule for the investment."""
    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=(
        "You are a careful assistant. "
        "Use tools for calculations and structured outputs. "
        "Return a concise final answer."
    ),
)

result = agent.invoke(
    {
        "messages": [
            {
                "role": "user",
                "content": (
                    "I have $2,500 invested at 6% annual interest compounded monthly for 5 years.\n"
                    "1) Compute the ending balance and total interest earned.\n"
                    "2) Generate a year-by-year ending balance schedule.\n"
                    "Then summarize the key takeaways in 3 bullets.\n\n"
                    "Use compounds_per_year=12."
                ),
            }
        ]
    }
)

print(result)

查看追踪

详细信息视图

点击追踪，并切换到右上角的 Details 视图。你在 LangSmith UI 中的追踪树将类似于此示例，具有以下结构：

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

生成的追踪包含多个嵌套 span，允许你在 LangSmith UI 中跟踪 agent 的规划、计算步骤和解释流程。

轨迹视图

LangSmith UI 中的 Trajectory 视图显示用户与 agent 之间简化的对话历史。此视图从顶层追踪中提取消息（包括用户的初始请求、工具调用和 agent 的最终响应），并以类似聊天的格式呈现。

按子 agent 过滤

Deep Agents 会自动将子 agent 的 name 写入该子 agent 产生的每个运行的 lc_agent_name 元数据键。使用此功能在 LangSmith 中隔离特定子 agent 的所有运行——这对于调试、监控或比较子 agent 行为很有用。

在 LangSmith UI 中过滤：

在 LangSmith 中打开你的追踪项目。
将视图切换为 Runs 以查看单个 span。
点击 Add filter 并选择 Metadata。
将 Key 设置为 lc_agent_name，将 Value 设置为子 agent 名称，例如 coordinator。

LangSmith Runs 视图，对 lc_agent_name 设置了元数据筛选器，值为 coordinator

将过滤器保存为命名视图以便快速复用。有关过滤选项的完整参考，请参阅过滤追踪。

使用 SDK 以编程方式过滤：

python

from langsmith import Client

client = Client()

# Fetch all runs produced by a specific subagent
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)

有关筛选查询语言的完整参考，请参阅 Trace query syntax。

自定义 LangSmith 追踪

默认情况下，通过环境变量启用 LangSmith 追踪时，Deep Agents 会自动发出追踪。你可以直接使用 LangSmith SDK 自定义追踪，例如将追踪范围限定为代码的一部分、附加标签或元数据，或覆盖项目名称。

如果你希望执行以下操作，请安装并使用 langsmith：

仅追踪特定的 agent 调用。
添加自定义标签或元数据以便在 UI 中过滤。
在运行时覆盖项目名称。

pipuv

bash

pip install langsmith

bash

uv add langsmith

此示例调用同一个 deep agent 两次：

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

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

python

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]:
    """Compute compound interest and return ending balance and interest earned."""
    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]]:
    """Return a year-by-year balance schedule for the investment."""
    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=(
        "You are a careful assistant. "
        "Use tools for calculations and structured outputs. "
        "Return a concise final answer."
    ),
)

# ----------------------------
# Untraced invocation
# ----------------------------
agent.invoke(
    {
        "messages": [
            {
                "role": "user",
                "content": (
                    "I have $2,500 invested at 6% annual interest compounded monthly for 5 years. "
                    "Compute the ending balance and total interest earned. "
                    "Use compounds_per_year=12."
                ),
            }
        ]
    }
)

# ----------------------------
# Traced invocation
# ----------------------------
with ls.tracing_context(
    enabled=True,
    project_name="deepagents-demo",
    tags=["deepagents", "scoped-tracing"],
    metadata={"example": "partial-workflow"},
):
    agent.invoke(
        {
            "messages": [
                {
                    "role": "user",
                    "content": (
                        "I have $2,500 invested at 6% annual interest compounded monthly for 5 years.\n"
                        "1) Compute the ending balance and total interest earned.\n"
                        "2) Generate a year-by-year ending balance schedule.\n"
                        "Then summarize the key takeaways in 3 bullets.\n\n"
                        "Use compounds_per_year=12."
                    ),
                }
            ]
        }
    )

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

enabled=True 在块持续时间内显式启用追踪，即使 LANGSMITH_TRACING 未设置或设置为 false。
project_name="deepagents-demo" 将此块产生的追踪路由到指定的 LangSmith 项目。这会覆盖在上下文内创建的运行的 LANGSMITH_PROJECT。
tags=[...] 为追踪的运行附加标签。标签会显示在 LangSmith UI 中，你可以使用它们来过滤和分组追踪。
metadata="..." 附加任意结构化元数据（例如环境、实验名称或功能标志）。

在此示例中，agent 被调用两次，但仅记录 tracing_context 内的调用。这演示了如何选择性地追踪 Deep Agents 工作流的特定部分，而无需为整个进程启用全局追踪。

数据集

创建数据集

运行评估

评估技术

定义评估目标

打分方法

实验配置

多模态评估

分析实验结果

微调

教程

常见数据类型

评估器类型

UI

SDK

框架与集成

改进评估器

反馈

追踪设置

集成

手动埋点

配置与故障排除

项目与环境设置

高级追踪技术

数据与隐私

故障排除指南

查看与管理追踪

批量导出追踪数据

轨迹视图

数据类型参考

监控与告警

在线评估器

自动化

开发你的应用

设置依赖

持久化

能力

助手

运行

并发消息处理

如何构建

鉴权与访问控制

自定义鉴权教程

服务器定制

静态加密

替换内置后端

扩展 HTTP 服务器

请求头与日志

部署指南

参考

配置

参考

提示词

创建与管理提示词

连接模型

上下文中枢

教程

全栈 Web 应用

Agent Server API

控制平面 API

计费与用量

参考

按云服务商起步

用 Terraform 部署

AWS

GCP

Azure

安装实例

配置实例

连接外部服务

平台鉴权与访问控制

管理实例

自托管可观测性

混合部署

脚本

参考

组织