使用 OpenTelemetry 检查运行

如果您是 agent 构建新手，请务必首先阅读 agent 介绍和 smolagents 引导式教程。

为什么记录您的 agent 运行？

Agent 运行难以调试。

验证运行是否正常进行很困难，因为 agent 工作流程在设计上是不可预测的（如果它们是可预测的，您只需使用旧代码）。

并且检查运行也很困难：多步 agent 倾向于快速用日志填充控制台，并且大多数错误只是“LLM 笨”类型的错误，LLM 会在下一步通过编写更好的代码或工具调用来自动纠正这些错误。

因此，在生产中使用检测来记录 agent 运行对于以后的检查和监控是必要的！

我们采用了 OpenTelemetry 标准来检测 agent 运行。

这意味着您可以只运行一些检测代码，然后正常运行您的 agent，一切都会记录到您的平台中。以下是如何使用不同的 OpenTelemetry 后端执行此操作的一些示例。

以下是它在平台上的外观

使用 Arize AI Phoenix 设置遥测

首先安装所需的软件包。这里我们安装 Arize AI 的 Phoenix，因为这是一个收集和检查日志的好解决方案，但还有其他与 OpenTelemetry 兼容的平台可用于此收集和检查部分。

pip install 'smolagents[telemetry]'

然后在后台运行收集器。

python -m phoenix.server.main serve

最后，设置 SmolagentsInstrumentor 以跟踪您的 agent 并将跟踪发送到 Phoenix 默认端点。

from phoenix.otel import register
from openinference.instrumentation.smolagents import SmolagentsInstrumentor

register()
SmolagentsInstrumentor().instrument()

然后您可以运行您的 agent！

from smolagents import (
    CodeAgent,
    ToolCallingAgent,
    DuckDuckGoSearchTool,
    VisitWebpageTool,
    HfApiModel,
)

model = HfApiModel()

search_agent = ToolCallingAgent(
    tools=[DuckDuckGoSearchTool(), VisitWebpageTool()],
    model=model,
    name="search_agent",
    description="This is an agent that can do web search.",
)

manager_agent = CodeAgent(
    tools=[],
    model=model,
    managed_agents=[search_agent],
)
manager_agent.run(
    "If the US keeps its 2024 growth rate, how many years will it take for the GDP to double?"
)

瞧！然后您可以导航到 http://0.0.0.0:6006/projects/ 以检查您的运行！

您可以看到 CodeAgent 调用了其管理的 ToolCallingAgent（顺便说一句，管理的 agent 也可能是 CodeAgent）以要求它运行美国 2024 年增长率的网络搜索。然后，管理的 agent 返回了其报告，而管理器 agent 根据该报告采取行动来计算经济翻番时间！很棒，不是吗？

使用 Langfuse 设置遥测

本部分介绍如何使用 SmolagentsInstrumentor 通过 Langfuse 监控和调试您的 Hugging Face smolagents。

什么是 Langfuse？ Langfuse 是一个用于 LLM 工程的开源平台。它为 AI agent 提供跟踪和监控功能，帮助开发人员调试、分析和优化他们的产品。Langfuse 通过原生集成、OpenTelemetry 和 SDK 与各种工具和框架集成。

步骤 1：安装依赖项

%pip install smolagents
%pip install opentelemetry-sdk opentelemetry-exporter-otlp openinference-instrumentation-smolagents

步骤 2：设置环境变量

设置您的 Langfuse API 密钥并配置 OpenTelemetry 端点以将跟踪发送到 Langfuse。通过注册 Langfuse Cloud 或自托管 Langfuse 获取您的 Langfuse API 密钥。

此外，添加您的 Hugging Face 令牌 (HF_TOKEN) 作为环境变量。

import os
import base64

LANGFUSE_PUBLIC_KEY="pk-lf-..."
LANGFUSE_SECRET_KEY="sk-lf-..."
LANGFUSE_AUTH=base64.b64encode(f"{LANGFUSE_PUBLIC_KEY}:{LANGFUSE_SECRET_KEY}".encode()).decode()

os.environ["OTEL_EXPORTER_OTLP_ENDPOINT"] = "https://cloud.langfuse.com/api/public/otel" # EU data region
# os.environ["OTEL_EXPORTER_OTLP_ENDPOINT"] = "https://us.cloud.langfuse.com/api/public/otel" # US data region
os.environ["OTEL_EXPORTER_OTLP_HEADERS"] = f"Authorization=Basic {LANGFUSE_AUTH}"

# your Hugging Face token
os.environ["HF_TOKEN"] = "hf_..."

步骤 3：初始化 SmolagentsInstrumentor

在您的应用程序代码之前初始化 SmolagentsInstrumentor。配置 tracer_provider 并添加 span 处理器以将跟踪导出到 Langfuse。OTLPSpanExporter() 使用来自环境变量的端点和标头。

from opentelemetry.sdk.trace import TracerProvider

from openinference.instrumentation.smolagents import SmolagentsInstrumentor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace.export import SimpleSpanProcessor

trace_provider = TracerProvider()
trace_provider.add_span_processor(SimpleSpanProcessor(OTLPSpanExporter()))

SmolagentsInstrumentor().instrument(tracer_provider=trace_provider)

步骤 4：运行您的 smolagent

from smolagents import (
    CodeAgent,
    ToolCallingAgent,
    DuckDuckGoSearchTool,
    VisitWebpageTool,
    HfApiModel,
)

model = HfApiModel(
    model_id="deepseek-ai/DeepSeek-R1-Distill-Qwen-32B"
)

search_agent = ToolCallingAgent(
    tools=[DuckDuckGoSearchTool(), VisitWebpageTool()],
    model=model,
    name="search_agent",
    description="This is an agent that can do web search.",
)

manager_agent = CodeAgent(
    tools=[],
    model=model,
    managed_agents=[search_agent],
)
manager_agent.run(
    "How can Langfuse be used to monitor and improve the reasoning and decision-making of smolagents when they execute multi-step tasks, like dynamically adjusting a recipe based on user feedback or available ingredients?"
)

步骤 5：在 Langfuse 中查看跟踪

运行 agent 后，您可以在 Langfuse 中查看由您的 smolagents 应用程序生成的跟踪。您应该看到 LLM 交互的详细步骤，这可以帮助您调试和优化您的 AI agent。

smolagents example trace

Langfuse 中的公共示例跟踪

< > 在 GitHub 上更新