Yingdao AI Observability

@yingdao-ai/agent-observability 是一个轻量的 Agent 可观测 SDK，用来把宿主运行时事件映射到 Langfuse trace。

它提供一层与宿主解耦的通用抽象：

• AgentObserver
• AgentRun / Generation / ToolSpan
• Transport 接口 / LangfuseDirectTransport
• ReadTransport 接口 / LangfuseReadTransport
• ReflectionRunner
• FlushGate
• ObservationContext
• 数据脱敏规则

适合接在你自己的 Agent runtime、编排层、LangChain / Vercel AI SDK 适配层之上。SDK 负责生命周期建模、上报和脱敏；宿主侧只需要把事件流映射进来。

脱敏默认采用 Langfuse client-side masking 思路，在发送前处理 trace/observation 的 input/output；业务可通过 LANGFUSE_MASK_RULES、registerRules() 或 LangfuseDirectTransport({ mask }) 追加/替换策略。

宿主特定的适配层（事件映射、鉴权、session 生命周期）由各宿主仓库自行维护。

安装

npm install @yingdao-ai/agent-observability

开发验证

bun test
bun typecheck

30 秒看懂模型

run
├── generation    # 一次 LLM 调用
├── tool          # 一次工具执行
└── score         # 对整条 run 的质量评分

Langfuse 中大致对应：

• run → trace
• generation → generation
• tool → tool
• score → score

最小示例

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

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 sessionId = "session-1";
const runId = "run-1";
const run = observer.startRun({
  id: runId,
  sessionId,
  name: "my_agent",
  input: "用户输入",
});

if (run) {
  run.startGeneration({ model: "openai/gpt-4.1" });
  run.appendText("assistant 输出");
  run.endGeneration({ usage: { input: 10, output: 3, total: 13 } });
  await observer.endRun(runId, "最终输出");
  await observer.gate.waitAll();
}

完整接入流程见 5 分钟接入。

可运行示例

examples/ 目录包含三个可直接运行的集成示例，均使用 mock 运行，无需 API key：

cd examples && bun install && cd ..

| 示例 | 命令 | 说明 | |---|---|---| | minimal | bun run examples/minimal/index.ts | 纯 SDK 接入模板，覆盖 basic / tool / score / sub-session | | langchain | bun run examples/langchain/index.ts | LangChain.js CallbackHandler 集成，包含 nested chain、chat model 和错误清理 | | vercel-ai | bun run examples/vercel-ai/index.ts | Vercel AI SDK (ai@6) streamText + tools，两步调用：tool call → text answer |

详细说明见 examples/README.md。

文档导航

npm run dev      # 本地开发
npm run build    # 构建文档到 dist/
npm run preview  # 预览构建结果

• 第一步看 快速开始
• 需要完整生命周期接入时看 5 分钟接入
• 理解模型和边界时看 核心概念 与 适配器契约
• 查接口细节时看 API 参考
• 排查线上问题时看 故障排查
• 发布流程见 RELEASE.md

发布

npm run release:check

发布到 npm 的三个通道：

npm run release:alpha
npm run release:beta
npm run release:latest

npm 包仅包含 dist/ 编译产物，文档和示例保留在仓库中，不随包发布。

版本和 tag 流程见 RELEASE.md。