W&B Weave 导出器

Koog 提供内置支持，用于将 agent 跟踪导出到 W&B Weave。 Weave 是 Weights & Biases 推出的一款开发者工具，用于 AI 应用程序的可观测性与分析。
通过 Weave 集成，您可以捕获提示词、补全、系统上下文及执行跟踪，并直接在您的 W&B 工作区中将其可视化。

有关 Koog 的 OpenTelemetry 支持的背景信息，请参阅 OpenTelemetry 支持。

---

设置说明

1. 在 https://wandb.ai 注册 W&B 帐号。
2. 从 https://wandb.ai/authorize 获取您的 API 密钥。
3. 访问您的 W&B 仪表板 https://wandb.ai/home 查找您的实体名称。 如果是个人帐户，您的实体通常是您的用户名，或者是您的团队/组织名称。
4. 为您的项目定义一个名称。您无需预先创建项目，当发送第一个跟踪时，项目将自动创建。
5. 将 Weave 实体、项目名称和 API 密钥传递给 Weave 导出器。 可以通过将它们作为参数提供给 addWeaveExporter() 函数来实现， 或者通过设置如下所示的环境变量来实现：

export WEAVE_API_KEY="<your-api-key>"
export WEAVE_ENTITY="<your-entity>"
export WEAVE_PROJECT_NAME="koog-tracing"

配置

要启用 Weave 导出，请安装 OpenTelemetry 功能并添加 WeaveExporter。
该导出器通过 OtlpHttpSpanExporter 使用 Weave 的 OpenTelemetry 端点。

示例：带有 Weave 跟踪的 agent

fun main() = runBlocking {
    val apiKey = "api-key"
    val entity = System.getenv()["WEAVE_ENTITY"] ?: throw IllegalArgumentException("WEAVE_ENTITY is not set")
    val projectName = System.getenv()["WEAVE_PROJECT_NAME"] ?: "koog-tracing"
    
    val agent = AIAgent(
        promptExecutor = simpleOpenAIExecutor(apiKey),
        llmModel = OpenAIModels.Chat.GPT4oMini,
        systemPrompt = "You are a code assistant. Provide concise code examples."
    ) {
        install(OpenTelemetry) {
            addWeaveExporter()
        }
    }

    println("Running agent with Weave tracing")

    val result = agent.run("Tell me a joke about programming")

    println("Result: $result
See traces on https://wandb.ai/$entity/$projectName/weave/traces")
}

哪些内容会被跟踪

启用后，Weave 导出器会捕获与 Koog 通用 OpenTelemetry 集成相同的 span，包括：

• Agent 生命周期事件：agent 启动、停止、错误
• LLM 交互：提示词、补全、延迟
• 工具调用：工具调用的执行跟踪
• 系统上下文：模型名称、环境、Koog 版本等元数据

出于安全原因，OpenTelemetry span 的部分内容默认会被屏蔽。 若要在 Weave 中查看这些内容，请在 OpenTelemetry 配置中使用 setVerbose 方法，并将 verbose 参数设置为 true，如下所示：

install(OpenTelemetry) {
    addWeaveExporter()
    setVerbose(true)
}

在 W&B Weave 中可视化时，跟踪显示如下：

有关更多详细信息，请参阅官方 Weave OpenTelemetry 文档。

---

故障排除

Weave 中未出现跟踪

• 确认您的环境中已设置 WEAVE_API_KEY、WEAVE_ENTITY 和 WEAVE_PROJECT_NAME。
• 确保您的 W&B 帐号具有访问指定实体和项目的权限。

身份验证错误

• 检查您的 WEAVE_API_KEY 是否有效。
• API 密钥必须具有为所选实体写入跟踪的权限。

连接问题

• 确保您的环境具有访问 W&B OpenTelemetry 摄取端点的网络权限。