将 Litefuse 与 Strands Agents SDK 集成
本 notebook 演示如何使用 Litefuse 高效地监控与调试你的 Strands Agent。按照本指南操作，你可以追踪 Agent 的运行情况，深入了解其行为和性能。
什么是 Strands Agents SDK？ Strands Agents SDK（文档）由 AWS 开发，是一个用于构建可与各种工具和服务交互的 AI Agent 工具包，支持 AWS Bedrock 等服务。
什么是 Litefuse？ Litefuse 是一个开源的 AI Agent 可观测性与评估平台，为 AI Agent 和 LLM 应用提供强大的追踪、调试、评估与监控能力。Litefuse 通过原生集成、OpenTelemetry 以及自有 SDK，与多种工具和框架无缝衔接。
快速开始
下面我们通过一个简单的示例，带你了解如何使用 Strands Agents，并将其与 Litefuse 集成以实现可观测性。
第 1 步：安装依赖
若要启用 OTEL 导出，请安装带 otel 额外依赖的 Strands Agents：pip install ‘strands-agents[otel]‘
%pip install "strands-agents[otel]" strands-agents-tools langfuse第 2 步：设置环境变量
接下来需要为 Litefuse 与 AWS（用于 Bedrock 模型）配置环境变量。
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"
# 你的 openai key
os.environ["OPENAI_API_KEY"] = "sk-proj-..."设置好环境变量后，我们就可以初始化 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.")第 3 步：初始化 Strands Agent
环境就绪后，我们可以初始化 Strands Agent。这一步包括定义 Agent 的行为、配置底层 LLM，以及为 Litefuse 设置追踪属性。
from strands import Agent
from strands.models.openai import OpenAIModel
# 配置 Agent 使用的 OpenAI 模型
model = OpenAIModel(
model_id="gpt-5", # 示例模型 ID
)
# 配置 Agent
agent = Agent(
model=model,
system_prompt="You are a helpful assistant that can answer questions and help with tasks.",
)第 4 步：运行 Agent
现在用一个示例查询来运行已初始化好的 Agent。Agent 会处理输入，Litefuse 则会通过此前配置好的 OpenTelemetry 集成自动追踪整个执行过程。
results = agent("Hi, where can I eat in San Francisco?")第 5 步：在 Litefuse 中查看 Trace
运行 Agent 后，你可以前往 Litefuse 项目查看详细的 trace。这些 trace 会逐步展示 Agent 的执行过程，包括 LLM 调用、工具使用（若有）、输入、输出、延迟以及成本。
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:
- Call
langfuse.flush()at the end of your application to ensure all observations are exported. - Verify that you are using the correct API keys and base URL.
- Call
- 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: