tRPC-Agent → Langfuse 数据上报实现说明

基于源码：trpc-agent / trpc-agent-py（trpc_agent_sdk）
目标读者：想理解「tRPC-Agent 如何把 Agent 执行过程变成 Langfuse Trace」的开发者

---

文档索引

章节	文件	内容
0	0_overview.md	方案总览、与 Claude Code 方案对比
1	1_architecture.md	三层架构：埋点 → 映射 → OTLP 导出
2	2_setup.md	两种接入方式与环境配置
3	3_instrumentation.md	框架在何处创建 Span、写入属性
4	4_attribute_mapping.md	OTel 属性 → Langfuse Observation 映射
5	5_export_pipeline.md	SpanProcessor、Exporter、过滤规则
6	6_prompt_management.md	Instruction 拉取与 Generation 关联
7	7_custom_trace.md	自定义 Agent / Tool 扩展上报

---

一句话总结

tRPC-Agent 不直接调用 Langfuse SDK，而是在 Agent 执行链路中通过 OpenTelemetry 埋点 产生 Span，再由 Langfuse 专用 SpanProcessor 把属性映射为 Langfuse 语义，最后经 OTLP HTTP 推送到 Langfuse 的 /api/public/otel/v1/traces 端点。

---

与 Claude Code 方案的对比

维度	Claude Code → Langfuse	tRPC-Agent → Langfuse
数据来源	旁路读取 jsonl transcript	框架运行时内嵌埋点
上报 API	Langfuse Python SDK v2（trace() / generation() / span()）	OpenTelemetry + OTLP
触发时机	Hook Stop / Watcher 轮询	Agent 执行过程中实时产生 Span
侵入性	零侵入 Claude Code 本体	需在启动时调用 langfuse_setup()
核心包	langfuse_trace/common/langfuse_transcript.py	trpc_agent_sdk/server/langfuse/tracing/opentelemetry.py

---

源码位置

trpc-agent/
├── trpc_agent/
│   └── telemetry/trace.py              # 薄封装，re-export trpc_agent_sdk.telemetry
├── trpc_agent_ecosystem/
│   ├── langfuse/
│   │   ├── tracing/opentelemetry.py    # re-export SDK 实现
│   │   └── prompt/__init__.py          # re-export RemoteInstructionManager
│   └── trpc_langfuse/
│       ├── _langfuse.py                # tRPC-Python 插件入口
│       └── _config.py                  # trpc_python.yaml 配置解析
└── docs/ecosystem/langfuse.md          # 官方接入文档

trpc-agent-py（pip 包 trpc-agent-py，内部模块 trpc_agent_sdk）
├── telemetry/_trace.py                 # trace_runner / trace_call_llm 等属性写入
├── runners.py                          # invocation 根 Span
├── agents/_base_agent.py               # agent_run Span
├── agents/core/_llm_processor.py       # call_llm Span
├── agents/core/_tools_processor.py     # execute_tool Span
└── server/langfuse/
    ├── tracing/opentelemetry.py        # Langfuse setup + 属性映射 + OTLP 导出
    └── prompt/_manager.py              # RemoteInstructionManager

---

建议阅读顺序

1. 0_overview.md — 建立全局图景
2. 1_architecture.md — 理解 OTel 通路
3. 3_instrumentation.md + 4_attribute_mapping.md — 理解输入与输出
4. 5_export_pipeline.md — 理解如何送到 Langfuse
5. 2_setup.md — 动手配置
6. 按需阅读 6 / 7