追踪 Deep Agents 应用 - Docs by LangChain

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

安装

在您的 Python 环境中安装 deepagents：

pip install deepagents

deepagents 需要：

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

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

设置

您可以在 LangSmith UI 的 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.1-pro-preview",
    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 中的追踪树将类似于此，结构如下：

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

生成的追踪记录包含多个嵌套的 span，这使您可以在 LangSmith UI 中跟踪智能体的规划、计算步骤和解释流程。

消息视图

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

自定义 LangSmith 追踪

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

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

pip install 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.1-pro-preview",
    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."
    ),
)

# ----------------------------
# 未追踪的调用
# ----------------------------
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."
                ),
            }
        ]
    }
)

# ----------------------------
# 已追踪的调用
# ----------------------------
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={...} 附加任意的结构化元数据（例如，环境、实验名称或功能标志）。

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

将这些文档通过 MCP 连接到 Claude、VSCode 等，以获取实时答案。

在 GitHub 上编辑此页面或提交问题。

​安装

​设置

​创建追踪记录

​查看追踪记录

​详情视图

​消息视图

​自定义 LangSmith 追踪

安装

设置

创建追踪记录

查看追踪记录

详情视图

消息视图

自定义 LangSmith 追踪