将 Litefuse 与 CrewAI 集成
本 notebook 提供一个分步指南，演示如何将 Litefuse 与 CrewAI 集成，从而对你的 LLM 应用实现可观测性与调试。
什么是 CrewAI？ CrewAI (GitHub) 是用于编排自主 AI Agent 的框架。CrewAI 使你能够创建 AI 团队，团队中每个 Agent 都有特定的角色、工具和目标，协同完成复杂任务。每个成员（Agent）带来独特的技能与专长，无缝协作以达成你的目标。
什么是 Litefuse？ Litefuse 是一个开源的 AI Agent 可观测性与评估平台。它为 AI 应用提供 tracing 与监控能力。Litefuse 通过提供详细的洞察以及通过原生集成、OpenTelemetry 和专用 SDK 与众多工具和框架对接，帮助开发者调试、分析并优化其 AI 系统。
快速开始
我们通过一个实际示例来演示如何使用 CrewAI 并将其与 Litefuse 集成，以获得全面的 tracing。
第 1 步：安装依赖
%pip install langfuse crewai openinference-instrumentation-crewai -q第 2 步：配置 Langfuse SDK
接下来，设置你的 Litefuse API Key。你可以通过注册免费的 Litefuse Cloud 账号或 自托管 Litefuse 获取这些 Key。这些环境变量是 Langfuse 客户端鉴权并向你的 Litefuse 项目发送数据所必需的。
import os
# Get keys for your project from the project settings page: 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"
# Your openai key
os.environ["OPENAI_API_KEY"] = "sk-proj-***"设置好环境变量后，我们就可以初始化 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 步：初始化 CrewAI Instrumentation
现在，我们初始化 OpenInference instrumentation SDK，自动捕获 CrewAI 的操作并将 OpenTelemetry (OTel) span 导出到 Litefuse。
from openinference.instrumentation.crewai import CrewAIInstrumentor
CrewAIInstrumentor().instrument(skip_dep_check=True)第 4 步：基础 CrewAI 应用
让我们创建一个简单的 CrewAI 应用。在本示例中，我们创建一个简单的 crew，其中的 Agent 可以协作完成任务。这将作为演示 Litefuse tracing 的基础。
from crewai import Agent, Task, Crew
# Define your agents with roles and goals
coder = Agent(
role='Software developer',
goal='Write clear, concise code on demand',
backstory='An expert coder with a keen eye for software trends.',
)
# Create tasks for your agents
task1 = Task(
description="Define the HTML for making a simple website with heading- Hello World! Litefuse monitors your CrewAI agent!",
expected_output="A clear and concise HTML code",
agent=coder
)
# Instantiate your crew
crew = Crew(
agents=[coder],
tasks=[task1],
)
with langfuse.start_as_current_observation(as_type="span", name="crewai-index-trace"):
result = crew.kickoff()
print(result)
langfuse.flush()第 5 步：在 Litefuse 中查看 Trace
执行应用后，进入你的 Litefuse Trace 表。你将看到应用执行的详细 trace，包括 LLM 调用、Agent 操作、输入、输出以及性能指标的洞察。Trace 将完整呈现从任务处理、Agent 协作到响应生成的全过程。
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: