使用 OpenTelemetry 检查运行

如果您是构建代理的新手，请务必先阅读代理简介和smolagents 入门指南。

为什么要记录您的 Agent 运行？

Agent 运行的调试过程很复杂。

验证运行是否正常进行是很困难的，因为 Agent 工作流在设计上是不可预测的（如果它们是可预测的，您就会使用传统的代码）。

并且检查一次运行也很困难：多步 Agent 往往会迅速用日志填满控制台，而且大多数错误只是“LLM 犯傻”之类的错误，LLM 会在下一步通过编写更好的代码或工具调用来自我纠正。

因此，在生产环境中使用检测工具来记录 Agent 运行，对于后续的检查和监控是必要的！

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

这意味着您只需运行一些检测代码，然后正常运行您的 Agent，所有内容都会被记录到您的平台中。以下是一些关于如何使用不同 OpenTelemetry 后端实现此操作的示例。

以下是在平台上的样子

使用 Arize AI Phoenix 设置遥测

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

pip install 'smolagents[telemetry,toolkit]'

然后在后台运行收集器。

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,
    WebSearchTool,
    VisitWebpageTool,
    InferenceClientModel,
)

model = InferenceClientModel()

search_agent = ToolCallingAgent(
    tools=[WebSearchTool(), 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 来监控和调试您的 Hugging Face smolagents 与 Langfuse。

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

步骤 1：安装依赖项

%pip install langfuse 'smolagents[telemetry]' openinference-instrumentation-smolagents

步骤 2：设置环境变量

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

同时，将您的 Hugging Face 令牌（HF_TOKEN）添加为环境变量。

import os
# Get keys for your project from the project settings page: https://cloud.langfuse.com
os.environ["LANGFUSE_PUBLIC_KEY"] = "pk-lf-..." 
os.environ["LANGFUSE_SECRET_KEY"] = "sk-lf-..." 
os.environ["LANGFUSE_HOST"] = "https://cloud.langfuse.com" # 🇪🇺 EU region
# os.environ["LANGFUSE_HOST"] = "https://us.cloud.langfuse.com" # 🇺🇸 US region
 
# your Hugging Face token
os.environ["HF_TOKEN"] = "hf_..."

设置好环境变量后，我们现在可以初始化 Langfuse 客户端。get_client() 使用环境变量中提供的凭据来初始化 Langfuse 客户端。

from langfuse import get_client
 
langfuse = get_client()
 
# Verify connection
if langfuse.auth_check():
    print("Langfuse client is authenticated and ready!")
else:
    print("Authentication failed. Please check your credentials and host.")

步骤 3：初始化 SmolagentsInstrumentor

在您的应用程序代码之前初始化 SmolagentsInstrumentor。

from openinference.instrumentation.smolagents import SmolagentsInstrumentor
 
SmolagentsInstrumentor().instrument()

步骤 4：运行您的 smolagent

from smolagents import (
    CodeAgent,
    ToolCallingAgent,
    WebSearchTool,
    VisitWebpageTool,
    InferenceClientModel,
)

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

search_agent = ToolCallingAgent(
    tools=[WebSearchTool(), 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 上更新