将 Litefuse 与 smolagents 集成

本 notebook 演示如何使用 SmolagentsInstrumentor，通过 Litefuse 监控和调试 Hugging Face 的 smolagents。完成本指南后，你将能够使用 Litefuse 追踪 smolagents 应用。

什么是 smolagents？ smolagents 是 Hugging Face 开发的一个极简、开源的 AI Agent 框架，设计目标是用几行代码就能创建并部署强大的 Agent。它聚焦于简洁与高效，方便开发者将 LLM 用于各种应用。

什么是 Litefuse？ Litefuse 是一个面向 LLM 工程的开源平台。它为 AI Agent 提供追踪与监控能力，帮助开发者调试、分析与优化产品。Litefuse 通过原生集成、OpenTelemetry 和 SDK 与各类工具和框架对接。

快速开始

下面我们通过一个简单的例子，演示如何使用 smolagents 并将其与 Litefuse 集成。

第 1 步：安装依赖

%pip install langfuse 'smolagents[telemetry]' opentelemetry-sdk opentelemetry-exporter-otlp openinference-instrumentation-smolagents

第 2 步：设置环境变量

通过注册 Litefuse Cloud 或自托管 Litefuse 来获取 Litefuse API Key。

另外，将你的 Hugging Face token（HF_TOKEN）也设为环境变量。

import os
# 从项目设置页面获取你项目的 Key：https://litefuse.cloud
os.environ["LANGFUSE_PUBLIC_KEY"] = "pk-lf-..." 
os.environ["LANGFUSE_SECRET_KEY"] = "sk-lf-..." 
os.environ["LANGFUSE_BASE_URL"] = "https://litefuse.cloud"
 
# 你的 Hugging Face token
os.environ["HF_TOKEN"] = "hf_..."

设置好环境变量后，我们就可以初始化 Langfuse 客户端了。get_client() 会使用环境变量中的凭证初始化 Langfuse 客户端。

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

Langfuse client is authenticated and ready!

第 3 步：初始化 `SmolagentsInstrumentor`

在你的应用代码之前先初始化 [SmolagentsInstrumentor](https://pypi.org/project/openinference-instrumentation-smolagents/)。

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

第 4 步：运行你的 smolagent

这个 smolagent 示例有一个 manager CodeAgent，负责编排一个具备网络搜索能力的 managed_agent。它会使用 DuckDuckGoSearchTool 和 VisitWebpageTool 等工具来查询 2024 年美国增长率，并计算需要多少年 GDP 才能翻倍。

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 步：在 Litefuse 中查看 Trace

运行 Agent 后，你可以在 Litefuse 中查看 smolagents 应用生成的 trace。你会看到 LLM 交互的详细步骤，便于调试与优化你的 AI Agent。

smolagents 示例 trace

Litefuse 中的公开示例 trace

Interoperability with the Python SDK

You can use this integration together with the Litefuse SDKs to add additional attributes to the observation.

The @observe() decorator provides a convenient way to automatically wrap your instrumented code and add additional attributes to the observation.

from langfuse import observe, propagate_attributes, get_client
 
langfuse = get_client()
 
@observe()
def my_llm_pipeline(input):
    # Add additional attributes (user_id, session_id, metadata, version, tags) to all spans created within this execution scope
    with propagate_attributes(
        user_id="user_123",
        session_id="session_abc",
        tags=["agent", "my-observation"],
        metadata={"email": "user@litefuse.ai"},
        version="1.0.0"
    ):
 
        # YOUR APPLICATION CODE HERE
        result = call_llm(input)
 
        return result
 
# Run the function
my_llm_pipeline("Hi")

Learn more about using the Decorator in the Langfuse SDK instrumentation docs.

Troubleshooting

No observations appearing

First, enable debug mode in the Python SDK:

export LANGFUSE_DEBUG="True"

Then run your application and check the debug logs:

OTel observations appear in the logs: Your application is instrumented correctly but observations are not reaching Litefuse. To resolve this:
1. Call langfuse.flush() at the end of your application to ensure all observations are exported.
2. Verify that you are using the correct API keys and base URL.
No OTel spans in the logs: Your application is not instrumented correctly. Make sure the instrumentation runs before your application code.

Unwanted observations in Litefuse

The Langfuse SDK is based on OpenTelemetry. Other libraries in your application may emit OTel spans that are not relevant to you. These still count toward your billable units, so you should filter them out. See Unwanted spans in Litefuse for details.

Missing attributes

Some attributes may be stored in the metadata object of the observation rather than being mapped to the Litefuse data model. If a mapping or integration does not work as expected, please raise an issue on GitHub.

Next Steps

Once you have instrumented your code, you can manage, evaluate and debug your application:

Manage prompts in Litefuse Add evaluation scores Run LLM-as-a-judge Evaluators Create datasets Create custom dashboards Test queries in the Playground

Semantic Kernel Spring AI

这个页面对你有帮助吗？

支持