AgentScope + Python + OTel HTTP 直连 Langfuse

一、核心前提

AgentScope 原生基于 OpenTelemetry 标准实现了分布式追踪能力。通过 agentscope.init() 传入 tracing_url 参数，即可将 Trace 数据通过 OTLP HTTP 协议导出到任意兼容后端。

Langfuse 接收 OTLP over HTTP 的 Trace 数据（暂不支持 gRPC），端点路径为 /api/public/otel。

二、环境变量配置

1. 设置 Langfuse 项目密钥

在 Langfuse 项目设置页面获取 LANGFUSE_PUBLIC_KEY 和 LANGFUSE_SECRET_KEY，然后配置环境变量：

import os
import base64

os.environ["LANGFUSE_PUBLIC_KEY"] = "pk-lf-xxx"
os.environ["LANGFUSE_SECRET_KEY"] = "sk-lf-xxx"

2. 构建 OTLP 端点与认证头

Langfuse 使用 Basic Auth 进行认证，需要将 Public Key 和 Secret Key 组合后 Base64 编码：

LANGFUSE_AUTH = base64.b64encode(
f"{os.environ['LANGFUSE_PUBLIC_KEY']}:{os.environ['LANGFUSE_SECRET_KEY']}".encode()
).decode()

3. 设置 OpenTelemetry 标准环境变量

# OTLP 端点（Langfuse OTLP 接收地址）
os.environ["OTEL_EXPORTER_OTLP_ENDPOINT"] = "https://cloud.langfuse.com/api/public/otel"

# 认证头（Basic Auth）
os.environ["OTEL_EXPORTER_OTLP_HEADERS"] = f"Authorization=Basic {LANGFUSE_AUTH}"

# （可选）自定义服务名称
os.environ["OTEL_SERVICE_NAME"] = "my-agentscope-app"

三、AgentScope 初始化

在应用程序最开始的位置调用 agentscope.init()，传入 tracing_url：

import agentscope

agentscope.init(
tracing_url="https://cloud.langfuse.com/api/public/otel/v1/traces"
)

注意：tracing_url 的路径需要包含 /v1/traces 后缀。Langfuse 的 OTLP 接收端点为 /api/public/otel，Trace 专用路径为 /api/public/otel/v1/traces。

四、完整集成示例代码

import os
import base64
import agentscope

# 1. 设置 Langfuse 密钥
os.environ["LANGFUSE_PUBLIC_KEY"] = "pk-lf-xxx"
os.environ["LANGFUSE_SECRET_KEY"] = "sk-lf-xxx"

# 2. 构建 Basic Auth
LANGFUSE_AUTH = base64.b64encode(
f"{os.environ['LANGFUSE_PUBLIC_KEY']}:{os.environ['LANGFUSE_SECRET_KEY']}".encode()
).decode()

# 3. 配置 OTLP 环境变量
os.environ["OTEL_EXPORTER_OTLP_ENDPOINT"] = "https://cloud.langfuse.com/api/public/otel"
os.environ["OTEL_EXPORTER_OTLP_HEADERS"] = f"Authorization=Basic {LANGFUSE_AUTH}"
os.environ["OTEL_SERVICE_NAME"] = "my-agentscope-app"

# 4. 初始化 AgentScope，启用追踪
agentscope.init(
tracing_url="https://cloud.langfuse.com/api/public/otel/v1/traces"
)

# 5. 编写 Agent 业务逻辑…
# AgentScope 会自动为 LLM 调用、工具调用、Agent 执行等生成 Trace 数据

五、自定义追踪与属性增强

如果需要在 Span 上附加自定义属性（如用户 ID、会话 ID），可以通过 AgentScope 的 TracingMiddleware 实现：

from agentscope.middleware import TracingMiddleware

# 在 Span 上设置用户和会话上下文
# 支持设置 user.id、session.id 等属性，Langfuse 会自动识别并关联

Langfuse 遵循 OpenTelemetry GenAI 语义约定，带有 gen_ai.* 属性的 Span 会自动映射为 Langfuse 的 Generation 类型。AgentScope 内置的追踪已自动处理这些属性。

六、实时数据接收（Langfuse v4）

如果使用的是 Langfuse v4，建议在 OTLP 头中添加 x-langfuse-ingestion-version: 4 以启用实时数据接收：

os.environ["OTEL_EXPORTER_OTLP_HEADERS"] = (
f"Authorization=Basic {LANGFUSE_AUTH},"
"x-langfuse-ingestion-version=4"
)

七、验证与排错

1. 验证数据是否上报成功

• 登录 Langfuse 控制台，在 Traces 页面查看是否有新的 Trace 记录
• 检查 Trace 时间线是否包含完整的 Span 层次结构（LLM 调用、工具调用等）

2. 常见问题

3. 可选依赖包

如果遇到导入问题，可安装 AgentScope 的 Langfuse 集成扩展包：

pip install agentscope-otel-langfuse

总结

AgentScope + Python + OTel HTTP 直连 Langfuse 的核心步骤：