将 Litefuse 与 Embabel Agent 集成

本指南演示如何使用 OpenTelemetry 将 Litefuse 与 Embabel 集成。

Embabel：由 Spring 框架创始人 Rod Johnson 创建的 JVM 框架，用于构建智能 AI 应用。它具有模块化的规划系统（GOAP、Utility AI、状态机），让 Agent 可以动态决定其行动，并通过 OpenTelemetry 提供零代码的可观测性。

Litefuse：开源 AI Agent 可观测性与评估平台，支持可观测性、评估和 prompt 管理。

第 1 步：设置 Litefuse

• 注册 Litefuse Cloud 或 自托管 Litefuse。
• 在 Litefuse 中创建一个新项目，复制你的 Public Key 和 Secret Key。

第 2 步：添加依赖

在 pom.xml 中添加 Embabel 可观测性 starter 和 Litefuse OpenTelemetry exporter：

首先，在 pom.xml 中设置 Embabel 版本属性：

<properties>
    <embabel-agent.version>0.3.4</embabel-agent.version>
</properties>

然后添加以下依赖：

<dependencies>
    <!-- Embabel Agent Observability Starter -->
    <dependency>
        <groupId>com.embabel.agent</groupId>
        <artifactId>embabel-agent-starter-observability</artifactId>
        <version>${embabel-agent.version}</version>
    </dependency>
 
    <!-- Langfuse OpenTelemetry Exporter (you can use Zipkin too) -->
    <dependency>
        <groupId>com.quantpulsar</groupId>
        <artifactId>opentelemetry-exporter-langfuse</artifactId>
        <version>0.4.0</version>
    </dependency>
</dependencies>

第 3 步：配置可观测性

将以下内容添加到你的 application.properties 中：

# Enable observability
embabel.observability.enabled=true
embabel.observability.service-name=observability
 
# Enable Spring Boot tracing
management.tracing.enabled=true
management.tracing.sampling.probability=1.0
 
# Langfuse
management.langfuse.enabled=true
management.langfuse.endpoint=https://litefuse.cloud/api/public/otel
management.langfuse.public-key=pk-lf-…
management.langfuse.secret-key=sk-lf-…

将 pk-lf-… 和 sk-lf-… 替换为你实际的 Litefuse 项目 Key。如果你自托管 Litefuse，请相应地更新 endpoint URL。

第 4 步：运行测试

启动你的应用：

mvn spring-boot:run

触发一次 Agent 执行 —— 例如调用一个 endpoint 或运行一个调用 Embabel Agent 的 CommandLineRunner。你应该能在应用日志中看到 trace 数据被导出。

第 5 步：在 Litefuse 中查看 Trace

trace 开始流入后，打开 Litefuse 控制台：

• Trace 列表：查看所有 Agent 执行，包括时间戳、延迟和 token 数。
• Trace 时间线：深入单条 trace，查看完整的 span 层级 —— Agent 动作、LLM 调用、工具调用和规划步骤。
• 输入/输出详情：查看发送给模型的 prompt 和收到的 completion，以及模型名称、token 使用情况等元数据。
• 分析控制台：跟踪一段时间内的成本、延迟和使用趋势。

排错

没有 Trace：

• 确认 embabel.observability.enabled 设为 true。
• 检查 OTLP endpoint 和凭证是否正确。
• 确认确实执行了 Agent 动作。

Prompt/Completion 缺失：

• 开发期间确保采样概率设为 1.0。
• 检查 classpath 中是否包含 Litefuse OpenTelemetry exporter 依赖。