AgentRun

单个 Agent 执行的高层对象，对应 Langfuse 的一条 trace。

通过 observer.startRun() 创建，不直接实例化。

Generation 方法

startGeneration(input: GenerationInput): void

开始一次 LLM 调用。

若已有主 generation 未结束，自动结束旧 generation。

run.startGeneration({
  model: "openai/gpt-4.1",
  input: [{ role: "user", content: "用户输入" }],
})

GenerationInput

type GenerationInput = {
  model: string                    // 模型名称，如 "openai/gpt-4.1"
  input?: unknown                  // LLM 输入消息
  metadata?: Record<string, unknown>
  name?: string                    // 可选，generation 名称
}

appendText(text: string): void

追加 assistant 输出文本（支持流式增量）。

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

appendReasoning(text: string): void

追加推理过程文本（支持流式增量）。

推理内容会作为 generation 下的子 observation 写入 Langfuse。

run.appendReasoning("让我思考一下...")

endGeneration(opts?): void

结束当前主 generation。

run.endGeneration({
  usage: {
    input: 100,
    output: 20,
    total: 120,
    reasoning: 50,      // 可选
    cache: {            // 可选
      read: 0,
      write: 0,
    },
  },
  cost: 0.01,           // 可选，单位 USD
  output: "...",        // 可选，若不传则使用 appendText 累积的内容
})

TokenUsage

type TokenUsage = {
  input?: number
  output?: number
  total?: number
  reasoning?: number
  cache?: {
    read?: number
    write?: number
  }
}

startNamedGeneration(key: string, input: GenerationInput): Generation

开始一个命名 generation（辅助 LLM 调用，如标题生成、摘要生成）。

• key 在单条 run 内唯一
• 同一个 key 再次调用时，自动结束旧 generation
• 返回 Generation 实例，可直接调用 gen.appendText()

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

gen.appendText("我的标题")

endNamedGeneration(key: string, output?: string): void

结束命名 generation。

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

Tool 方法

startTool(input: ToolInput): ToolSpan

开始一次工具调用，返回 ToolSpan 实例。

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

ToolInput

type ToolInput = {
  id: string                       // 工具调用 ID，必须唯一且与 endTool 一致
  name: string                     // 工具名称
  input?: unknown                  // 工具输入
  metadata?: Record<string, unknown>
}

endTool(callId: string, opts?): void

结束指定 tool span。

// 成功
run.endTool("call-1", { output: { result: "ok" } })

// 失败
run.endTool("call-1", { error: "timeout" })

也可直接通过 ToolSpan 实例结束：

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

Score 方法

score(spec: ScoreSpec | ScoreSpec[]): void

写入 trace 评分。

// 单个
run.score({
  name: "agent_outcome",
  value: "completed",
  dataType: "CATEGORICAL",
  comment: "正常完成",
})

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

ScoreSpec

type ScoreSpec = {
  name: string
  value: string | number | boolean
  dataType: "CATEGORICAL" | "NUMERIC" | "BOOLEAN"
  comment?: string
}

Trace 元信息方法

以下方法可在 run 的任意阶段调用，用于更新 trace 元信息：

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

错误标记

markError(message: string): void

标记当前 run 为错误状态。

run.markError("session failed: timeout")