使用 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 上更新