6. Instruction / Prompt 管理

---

1. 能力概述

tRPC-Agent 集成了 Langfuse Prompt Management（文档中称 Instruction Management）：

1. 在 Langfuse 平台创建、版本化 Instruction
2. 运行时通过 RemoteInstructionManager 拉取指定版本
3. 传给 LlmAgent.instruction
4. 框架自动把版本信息写入 LLM Span，Langfuse 关联 Instruction → Generation

不依赖 Langfuse Python SDK，Instruction 拉取走 REST API，Trace 关联走 OTel attributes。

---

2. RemoteInstructionManager

from trpc_agent_ecosystem.langfuse.prompt import RemoteInstructionManager

manager = RemoteInstructionManager(
    public_key="pk-lf-...",
    secret_key="sk-lf-...",
    host="http://your-langfuse-host",
)

# 默认 production 标签
result = manager.get_instruction(name="weather_instruction")

# 指定标签或版本
result = manager.get_instruction(name="weather_instruction", label="staging")
result = manager.get_instruction(name="weather_instruction", version=3)

API

• 端点：GET {host}/api/public/v2/prompts/{promptName}
• 认证：HTTP Basic Auth (public_key, secret_key)
• 参考：Langfuse Prompts API

返回值 Instruction

属性	说明
instruction	模板字符串
metadata.name	Instruction 名称
metadata.version	版本号
metadata.labels	标签列表
metadata.config	附加配置

result.compile(user_name="张三") 可替换 {{variable}} 占位符。

---

3. 与 LlmAgent 集成

from trpc_agent.agents import LlmAgent

result = manager.get_instruction(name="weather_instruction", label="production")

agent = LlmAgent(
    name="weather_agent",
    model=model,
    instruction=result,  # Instruction 实现 InstructionProvider 协议
    tools=[...],
)

---

4. Trace 关联原理

写入（trace_call_llm）

当 LlmAgent.instruction 为带 metadata 的 Instruction 时，_llm_processor.py 提取：

instruction_metadata = getattr(context.agent.instruction, 'metadata', None)
trace_call_llm(..., instruction_metadata=instruction_metadata)

写入 Span 属性：

Span 属性	来源
trpc.python.agent.instruction.name	metadata.name
trpc.python.agent.instruction.version	metadata.version
trpc.python.agent.instruction.labels	metadata.labels 逗号拼接

映射（Langfuse SpanProcessor）

Span 属性	Langfuse 属性
{p}.instruction.name	langfuse.observation.prompt.name
{p}.instruction.version	langfuse.observation.prompt.version

Langfuse UI 在 Instruction 详情页展示关联的 Generation 记录，便于对比不同版本效果。

---

5. 数据流

Langfuse 平台（Instruction v3, label=production）
        │
        │ GET /api/public/v2/prompts/{name}
        ▼
RemoteInstructionManager.get_instruction()
        │
        ▼
LlmAgent(instruction=Instruction(...))
        │
        │ Agent 执行 → call_llm Span
        ▼
trace_call_llm(instruction_metadata=...)
        │
        │ SpanProcessor 映射
        ▼
langfuse.observation.prompt.name/version
        │
        ▼
Langfuse Generation 关联到 Instruction v3

---

6. 与 Tracing setup 的关系

• Tracing：langfuse_setup() — OTLP 上报执行 Trace
• Instruction 拉取：RemoteInstructionManager — 独立 REST 客户端

两者使用相同的 public_key / secret_key / host，但职责分离：

• setup 只需调用一次
• RemoteInstructionManager 可在 Agent 构建时实例化，也可与 setup 分开配置

---

7. 注意事项

1. Instruction 拉取失败会 raise，需在应用层处理降级（本地 fallback prompt）
2. compile() 后的字符串用于 LLM，metadata 仍指向 Langfuse 原始版本
3. 仅 LLM Generation 会关联 Instruction；Tool Span 不含 prompt 字段
4. 自定义 Agent 使用 CustomTraceReporter 时，同样从 ctx.agent.instruction.metadata 读取并传给 trace_call_llm()