2. 接入与配置

---

1. 安装

# requirements.txt
--index-url https://mirrors.cloud.tencent.com/pypi/simple/
--extra-index-url https://mirrors.tencent.com/repository/pypi/tencent_pypi/simple/

trpc-agent[langfuse]>=0.1.1

[langfuse] extra 会安装：

• opentelemetry-sdk>=1.28.0,<2.0.0
• opentelemetry-exporter-otlp-proto-http>=1.28.0,<2.0.0

若使用 tRPC-Python 部署，额外安装：

trpc-agent[trpc_langfuse]>=0.3.0

---

2. 方式 A：langfuse 扩展（代码配置）

适用于独立脚本、FastAPI Debug Server 等场景。

from trpc_agent_ecosystem.langfuse.tracing.opentelemetry import setup as langfuse_setup
from trpc_agent_ecosystem.langfuse.tracing.opentelemetry import LangfuseConfig

# 必须在 Runner.run_async() 之前调用
langfuse_setup(
    LangfuseConfig(
        public_key="pk-lf-your-public-key",
        secret_key="sk-lf-your-secret-key",
        host="http://your-langfuse-host",  # 不要带尾部 /
    )
)

环境变量替代

环境变量	对应配置项
LANGFUSE_PUBLIC_KEY	public_key
LANGFUSE_SECRET_KEY	secret_key
LANGFUSE_HOST	host

也可 langfuse_setup(LangfuseConfig()) 留空，由环境变量填充。

LangfuseConfig 完整参数

参数	必填	默认	说明
public_key	是	—	Langfuse 公钥
secret_key	是	—	Langfuse 密钥
host	是	—	服务地址，如 https://cloud.langfuse.com
batch_export	否	True	是否批量导出 Span
compatibility_old_version	否	False	兼容 Langfuse v3.90.0 之前的 attribute 格式
enable_a2a_trace	否	False	为 True 时不过滤 a2a-sdk / HTTP 自动埋点 Span

---

3. 方式 B：trpc_langfuse 插件（YAML 配置）

适用于 tRPC-Python 微服务。

trpc_python.yaml

plugins:
  agent:
    langfuse:
      public_key: "pk-lf-your-public-key"
      secret_key: "sk-lf-your-secret-key"
      host: "http://your-langfuse-host"
      # enabled: true                    # 默认 true
      # batch_export: true             # 默认 true
      # compatibility_old_version: false

trpc_main.py

import trpc_agent_ecosystem.trpc_langfuse  # 注册插件

插件生命周期

TrpcLangfusePlugin 注册为 PluginType.TRACE，在 MASTER 进程 on_master_start() 时：

1. 从 trpc_python.yaml 加载 TrpcLangfuseConfig
2. 校验 public_key / secret_key / host
3. 调用 langfuse_setup(LangfuseConfig(...))

配置无效时打 error 日志并跳过初始化，不会阻断服务启动。

---

4. 自托管 Langfuse（可选）

git clone https://github.com/langfuse/langfuse.git
cd langfuse
docker compose up

浏览器访问 http://<host>:3000，在 Settings → API Keys 创建密钥。

---

5. 验证上报成功

1. 启动应用并完成一次 Agent 对话
2. 打开 Langfuse → Traces
3. 应看到 Trace 名称形如 [trpc-agent]: {app_name}/{agent_name}
4. 展开后可看到 call_llm Generation 和 execute_tool Span

开启 debug 日志可看到 Exporter 输出（_LangfuseOTLPExporter.export 会 log 每个 Span JSON）。

---

6. 常见配置错误

现象	原因
启动报 Missing required Langfuse credentials	未配置 key 或 host
Traces 页面为空	未在 Runner 前调用 setup()，或 enabled: false
属性格式不对	旧版 Langfuse 需设 compatibility_old_version=True
出现大量 HTTP GET/POST Span	设 enable_a2a_trace=False（默认）以过滤

更多排查见 cc_to_langfuse 的 Langfuse 连通性章节；OTel 通路需确认 endpoint 可达：{host}/api/public/otel/v1/traces。

---

7. 与业务代码的最小示例

from trpc_agent.agents import LlmAgent
from trpc_agent.runners import Runner
from trpc_agent_ecosystem.langfuse.tracing.opentelemetry import setup, LangfuseConfig

setup(LangfuseConfig(
    public_key="pk-lf-...",
    secret_key="sk-lf-...",
    host="http://localhost:3000",
))

agent = LlmAgent(name="demo", model=..., instruction="You are helpful.")
runner = Runner(agent=agent, app_name="demo_app")

# runner.run_async(...) 产生的 Span 会自动上报 Langfuse

注意：setup() 只需调用一次，通常在 main() 或应用启动钩子中完成。