Open AIDoc

简体中文

繁體中文
日本語
한국어

简体中文

繁體中文
日本語
한국어

Appearance

追踪 ​

本页面包含有关 Tracing 特性的详细信息，该特性为 AI 代理提供了全面的追踪能力。

特性概览 ​

Tracing 特性是一个强大的监控和调试工具，它捕获有关代理运行的详细信息，包括：

  • 策略执行
  • LLM 调用
  • LLM 流式传输（开始、帧、完成、错误）
  • 工具调用
  • 代理图中的节点执行

此特性通过拦截代理流水线中的关键事件并将其转发给可配置的消息处理器。这些处理器可以将追踪信息输出到各种目标，例如日志文件或文件系统中的其他类型文件，使开发者能够深入了解代理行为并有效排查问题。

事件流 ​

  1. Tracing 特性拦截代理流水线中的事件。
  2. 事件根据配置的消息过滤器进行过滤。
  3. 过滤后的事件传递给已注册的消息处理器。
  4. 消息处理器格式化并输出事件到各自的目标。

配置与初始化 ​

基本设置 ​

要使用 Tracing 特性，你需要：

  1. 拥有一个或多个消息处理器（你可以使用现有处理器或创建自己的处理器）。
  2. 在你的代理中安装 Tracing。
  3. 配置消息过滤器（可选）。
  4. 将消息处理器添加到该特性中。
kotlin
// 定义将用作追踪消息目标的日志器/文件
val logger = KotlinLogging.logger { }
val outputPath = Path("/path/to/trace.log")

// 创建一个代理
val agent = AIAgent(
    promptExecutor = simpleOllamaAIExecutor(),
    llmModel = OllamaModels.Meta.LLAMA_3_2,
) {
    install(Tracing) {

        // 配置消息处理器以处理追踪事件
        addMessageProcessor(TraceFeatureMessageLogWriter(logger))
        addMessageProcessor(TraceFeatureMessageFileWriter(
            outputPath,
            { path: Path -> SystemFileSystem.sink(path).buffered() }
        ))
    }
}

消息过滤 ​

你可以处理所有现有事件，或根据特定条件选择其中一些。消息过滤器允许你控制哪些事件被处理。这对于关注代理运行的特定方面非常有用：

kotlin

val fileWriter = TraceFeatureMessageFileWriter(
    outputPath,
    { path: Path -> SystemFileSystem.sink(path).buffered() }
)

addMessageProcessor(fileWriter)

// 仅过滤与 LLM 相关的事件
fileWriter.setMessageFilter { message ->
    message is LLMCallStartingEvent || message is LLMCallCompletedEvent
}

// 仅过滤与工具相关的事件
fileWriter.setMessageFilter { message -> 
    message is ToolCallStartingEvent ||
           message is ToolCallCompletedEvent ||
           message is ToolValidationFailedEvent ||
           message is ToolCallFailedEvent
}

// 仅过滤节点执行事件
fileWriter.setMessageFilter { message -> 
    message is NodeExecutionStartingEvent || message is NodeExecutionCompletedEvent
}

大量追踪数据 ​

对于具有复杂策略或长时间运行的代理，追踪事件量可能非常大。考虑使用以下方法管理事件量：

  • 使用特定的消息过滤器来减少事件数量。
  • 实现带有缓冲或采样的自定义消息处理器。
  • 对日志文件使用文件轮转，以防止它们变得过大。

依赖图 ​

Tracing 特性具有以下依赖项：

Tracing
├── AIAgentPipeline (for intercepting events)
├── TraceFeatureConfig
│   └── FeatureConfig
├── Message Processors
│   ├── TraceFeatureMessageLogWriter
│   │   └── FeatureMessageLogWriter
│   ├── TraceFeatureMessageFileWriter
│   │   └── FeatureMessageFileWriter
│   └── TraceFeatureMessageRemoteWriter
│       └── FeatureMessageRemoteWriter
└── Event Types (from ai.koog.agents.core.feature.model)
    ├── AgentStartingEvent
    ├── AgentCompletedEvent
    ├── AgentExecutionFailedEvent
    ├── StrategyStartingEvent
    ├── StrategyCompletedEvent
    ├── NodeExecutionStartingEvent
    ├── NodeExecutionCompletedEvent
    ├── LLMCallStartingEvent
    ├── LLMCallCompletedEvent
    ├── LLMStreamingStartingEvent
    ├── LLMStreamingFrameReceivedEvent
    ├── LLMStreamingFailedEvent
    ├── LLMStreamingCompletedEvent
    ├── ToolCallStartingEvent
    ├── ToolValidationFailedEvent
    ├── ToolCallFailedEvent
    └── ToolCallCompletedEvent

示例与快速入门 ​

基本日志追踪 ​

kotlin
// 创建一个日志器
val logger = KotlinLogging.logger { }

fun main() {
    runBlocking {
       // 创建一个带追踪功能的代理
       val agent = AIAgent(
          promptExecutor = simpleOllamaAIExecutor(),
          llmModel = OllamaModels.Meta.LLAMA_3_2,
       ) {
          install(Tracing) {
             addMessageProcessor(TraceFeatureMessageLogWriter(logger))
          }
       }

       // 运行代理
       agent.run("Hello, agent!")
    }
}

错误处理与边缘情况 ​

没有消息处理器 ​

如果 Tracing 特性没有添加任何消息处理器，将记录一条警告：

Tracing Feature. No feature out stream providers are defined. Trace streaming has no target.

该特性仍将拦截事件，但它们不会被处理或输出到任何地方。

资源管理 ​

消息处理器可能会持有需要正确释放的资源（如文件句柄）。使用 use 扩展函数以确保正确清理：

kotlin
// 创建代理
val agent = AIAgent(
    promptExecutor = simpleOllamaAIExecutor(),
    llmModel = OllamaModels.Meta.LLAMA_3_2,
) {
    val writer = TraceFeatureMessageFileWriter(
        outputPath,
        { path: Path -> SystemFileSystem.sink(path).buffered() }
    )

    install(Tracing) {
        addMessageProcessor(writer)
    }
}
// 运行代理
agent.run(input)
// 当代码块退出时，writer 将自动关闭

追踪特定事件到文件 ​

kotlin
install(Tracing) {
    
    val fileWriter = TraceFeatureMessageFileWriter(
        outputPath, 
        { path: Path -> SystemFileSystem.sink(path).buffered() }
    )
    addMessageProcessor(fileWriter)
    
    // 仅追踪 LLM 调用
    fileWriter.setMessageFilter { message ->
        message is LLMCallStartingEvent || message is LLMCallCompletedEvent
    }
}

追踪特定事件到远程端点 ​

当你需要通过网络发送事件数据时，可以使用追踪到远程端点。一旦启动，追踪到远程端点会在指定的端口号启动一个轻量级服务器，并通过 Kotlin Server-Sent Events (SSE) 发送事件。

kotlin
// 创建代理
val agent = AIAgent(
    promptExecutor = simpleOllamaAIExecutor(),
    llmModel = OllamaModels.Meta.LLAMA_3_2,
) {
    val connectionConfig = DefaultServerConnectionConfig(host = host, port = port)
    val writer = TraceFeatureMessageRemoteWriter(
        connectionConfig = connectionConfig
    )

    install(Tracing) {
        addMessageProcessor(writer)
    }
}
// 运行代理
agent.run(input)
// 当代码块退出时，writer 将自动关闭

在客户端，你可以使用 FeatureMessageRemoteClient 来接收事件并将其反序列化。

kotlin
val clientConfig = DefaultClientConnectionConfig(host = host, port = port, protocol = URLProtocol.HTTP)
val agentEvents = mutableListOf<DefinedFeatureEvent>()

val clientJob = launch {
    FeatureMessageRemoteClient(connectionConfig = clientConfig, scope = this).use { client ->
        val collectEventsJob = launch {
            client.receivedMessages.consumeAsFlow().collect { event ->
                // 从服务器收集事件
                agentEvents.add(event as DefinedFeatureEvent)

                // 在代理结束时停止收集事件
                if (event is AgentCompletedEvent) {
                    cancel()
                }
            }
        }
        client.connect()
        collectEventsJob.join()
        client.healthCheck()
    }
}

listOf(clientJob).joinAll()

API 文档 ​

Tracing 特性遵循模块化架构，包含以下关键组件：

  1. Tracing：拦截代理流水线中事件的主要特性类。
  2. TraceFeatureConfig：用于自定义特性行为的配置类。
  3. 消息处理器：处理并输出追踪事件的组件：

Copyright © 2025 Open AIDoc.