5 分钟接入

本文档讲清楚使用方最关心的内容：怎么把 @yingdao-ai/agent-observability 接到业务里，并把 Agent run、LLM 调用、tool 调用和 score 写到 Langfuse。

你会接入什么

SDK 把一次 Agent 执行抽象成这几个对象：

run
├── generation       ← 一次 LLM 调用
├── tool span        ← 一次工具执行
└── score            ← 质量评分

对应 Langfuse 中：

SDK 对象	Langfuse 概念
run	trace
generation	generation
tool span	span
score	score

步骤 1：安装和导入

npm install @yingdao-ai/agent-observability

import { AgentObserver, LangfuseDirectTransport } from "@yingdao-ai/agent-observability"

步骤 2：创建 observer

直连 Langfuse：

const observer = new AgentObserver({
  transport: new LangfuseDirectTransport({
    host: "https://langfuse.example.com",
    publicKey: process.env.LANGFUSE_PUBLIC_KEY!,
    secretKey: process.env.LANGFUSE_SECRET_KEY!,
    environment: "prod",
  }),
})

走业务代理：

const observer = new AgentObserver({
  transport: new LangfuseDirectTransport({
    host: "https://power.example.com/langfuse",
    environment: "prod",
    authHeaders: (sessionId) => ({
      Authorization: `Bearer ${resolveToken(sessionId)}`,
    }),
  }),
})

步骤 3：一次完整调用

// 开始运行
const run = observer.startRun({
  id: sessionId,
  name: "super_agent",
  input: userInput,
  userId,
  tags: ["agentType:super_agent"],
  metadata: { org_uuid: orgId },
})

if (!run) return   // transport disabled 时 startRun 返回 undefined

// LLM 调用
run.startGeneration({
  model: "openai/gpt-4.1",
  input: [{ role: "user", content: userInput }],
})

run.appendText("hello")
run.appendText(" world")

run.endGeneration({
  usage: { input: 100, output: 20, total: 120 },
  cost: 0.01,
})

// 工具调用
const tool = run.startTool({
  id: "call-1",
  name: "search",
  input: { q: "Langfuse" },
})

tool.end({
  output: { result: "ok" },
})

// 评分
run.score({
  name: "agent_outcome",
  value: "completed",
  dataType: "CATEGORICAL",
})

// 结束运行
await observer.endRun(sessionId, "final output")

// 等待所有数据上报
await observer.gate.waitAll()

调用顺序很重要

必须按此顺序调用：

1. startRun()
2. startGeneration()
3. appendText() / appendReasoning()
4. endGeneration()
5. startTool() / tool.end()
6. score()
7. endRun()
8. 进程退出前 observer.gate.waitAll()

常用能力

Reasoning 推理过程

run.startGeneration({ model: "openai/gpt-4.1" })
run.appendReasoning("thinking...")  // 推理过程
run.appendText("answer")            // 最终输出
run.endGeneration()

reasoning 会作为 generation 下的子 observation 写入 Langfuse。

Named Generation（辅助调用）

适合标题生成、摘要生成等辅助 LLM 调用：

const gen = run.startNamedGeneration("title", {
  model: "openai/gpt-4.1-mini",
  input: chatMessages,
})

gen.appendText("我的标题")
run.endNamedGeneration("title", "我的标题")

Trace 元信息（延迟写入）

如果上下文信息在 startRun 后才能拿到：

run.setName("workflow_agent")
run.setTags(["agentType:workflow_agent", "source:web"])
run.setUserId("user-1")
run.setMetadata({ title: "新会话" })
run.setInput({ prompt: "..." })

多个 Score

run.score([
  { name: "session_duration_ms", value: 1200, dataType: "NUMERIC" },
  { name: "tool_error", value: false, dataType: "BOOLEAN" },
])

接入检查清单

接完后至少确认以下几点：

• [ ] observer.startRun() 返回的不是 undefined
• [ ] Langfuse 里能看到 trace
• [ ] trace 下能看到 generation 和 tool span
• [ ] score() 能写进去
• [ ] 进程退出前调用了 observer.gate.waitAll()

接下来

• 核心概念 — 深入了解数据模型
• 数据脱敏 — 配置脱敏规则
• AgentObserver API — 完整 API 参考