以编程方式使用文档

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

本指南将向您展示如何为 Deep Agents 启用 LangSmith 追踪功能、在 LangSmith UI 中查看追踪记录，以及（可选）为更高级的使用场景自定义追踪配置。

安装

安装 deepagents 在您的 Python 环境中：

pip install deepagents
uv add deepagents

deepagents requires:

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

设置

您可以在 LangSmith UI 的 LangSmith UI 中的 **设置**:

下找到您的 LangSmith API 密钥和项目名称。创建追踪记录

一旦通过环境变量启用了追踪功能，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]:
    """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.5-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)

查看追踪记录

详情视图

点击追踪记录，然后在右上角切换到 **详情** 视图。您的追踪树在 LangSmith UI 中会显示如下 ，包含以下结构：，包含以下结构：

  • - Agent 运行（顶层），代表完整的 Deep Agents 调用。
  • - LLM 调用，Agent 在此分析用户请求并决定使用哪些工具。
  • - 工具运行： compute_compound_interest:
  • - 显示工具输入（例如，本金、年_利率、期限和每年复利_次数）。_次数）。
  • - 显示结构化输出，包括最终余额和赚取的总利息。
  • - LLM 调用解释计算结果并确定下一步。
  • - 工具运行： yearly_balance_schedule:
  • - 显示用于生成计划的输入。
  • - 返回逐年细分的最终余额和赚取的利息。
  • - 最终 LLM 响应，为用户总结结果。

生成的追踪包含多个嵌套的跨度，使您能够跟踪代理的规划、计算步骤和解释流程在 LangSmith UI 中。

消息视图

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

按子代理筛选

Deep Agents 自动将子代理的 name 写入 lc_agent_name 元数据键，每个子代理生成的运行都会写入此键。使用此功能可以在 LangSmith 中隔离来自特定子代理的所有运行——有助于调试、监控或比较子代理行为。

在 LangSmith UI 中筛选：

  1. 在 LangSmith.
  2. 中打开追踪项目，将视图切换到 **运行** 以查看各个跨度。
  3. 点击 **添加筛选** 并选择 **元数据**.
  4. 将 **键** to lc_agent_name 和 **值** 设置为子代理名称，例如 research-agent.

将筛选保存为命名视图以便快速重用。完整的筛选选项参考，请参见 筛选追踪.

使用 SDK 编程筛选：

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)

完整的筛选查询语言参考，请参见 追踪查询语法.

自定义 LangSmith 追踪

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

安装和使用 langsmith 如果您想：

  • - 仅追踪特定的代理调用。
  • - 添加自定义标签或元数据以便在 UI 中筛选。
  • - 在运行时覆盖项目名称。
pip install langsmith
uv add langsmith

此示例调用同一个深度代理两次：

  • - 第一次调用未被追踪，因为它在 tracing_context.
  • - 第二次调用被追踪，因为它在 tracing_context(enabled=True, ...).

您可以有选择性地只追踪工作流的一部分，而不需要通过 LANGSMITH_TRACING=true:

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

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