跟踪
本页面包含有关“跟踪 (Tracing)”功能的详细信息，该功能为 AI 智能体提供了全面的跟踪能力。
功能概览
跟踪功能是一个强大的监控和调试工具，可捕获有关智能体运行的详细信息，包括：
- 策略执行
- LLM 调用
- LLM 流式传输（开始、帧、完成、错误）
- 工具调用
- 智能体图内的节点执行
该功能通过拦截智能体流水线中的关键事件并将其转发到可配置的消息处理器来运行。这些处理器可以将跟踪信息输出到各种目的地，例如日志文件或文件系统中的其他类型文件，从而使开发者能够洞察智能体行为并有效地进行故障排除。
事件流
- 跟踪功能拦截智能体流水线中的事件。
- 根据配置的消息筛选器对事件进行筛选。
- 筛选后的事件被传递给注册的消息处理器。
- 消息处理器对事件进行格式化并将其输出到各自的目的地。
配置与初始化
基本设置
要使用跟踪功能，您需要：
- 拥有一个或多个消息处理器（可以使用现有的处理器或创建自己的处理器）。
- 在您的智能体中安装
Tracing。 - 配置消息筛选器（可选）。
- 将消息处理器添加到该功能中。
kotlin
// 定义一个将用作跟踪消息目的地的 logger/文件
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
}大容量跟踪
对于具有复杂策略或长时间运行执行的智能体，跟踪事件的数量可能会非常庞大。请考虑使用以下方法来管理事件量：
- 使用特定的消息筛选器以减少事件数量。
- 实现具有缓冲或采样功能的自定义消息处理器。
- 对日志文件使用文件轮转 (file rotation)，以防止其增长得过大。
依赖关系图
跟踪功能具有以下依赖项：
Tracing
├── AIAgentPipeline (用于拦截事件)
├── TraceFeatureConfig
│ └── FeatureConfig
├── Message Processors
│ ├── TraceFeatureMessageLogWriter
│ │ └── FeatureMessageLogWriter
│ ├── TraceFeatureMessageFileWriter
│ │ └── FeatureMessageFileWriter
│ └── TraceFeatureMessageRemoteWriter
│ └── FeatureMessageRemoteWriter
└── Event Types (来自 ai.koog.agents.core.feature.model)
├── AgentStartingEvent
├── AgentCompletedEvent
├── AgentExecutionFailedEvent
├── AgentClosingEvent
├── GraphStrategyStartingEvent
├── FunctionalStrategyStartingEvent
├── StrategyCompletedEvent
├── NodeExecutionStartingEvent
├── NodeExecutionCompletedEvent
├── NodeExecutionFailedEvent
├── SubgraphExecutionStartingEvent
├── SubgraphExecutionCompletedEvent
├── SubgraphExecutionFailedEvent
├── LLMCallStartingEvent
├── LLMCallCompletedEvent
├── LLMStreamingStartingEvent
├── LLMStreamingFrameReceivedEvent
├── LLMStreamingFailedEvent
├── LLMStreamingCompletedEvent
├── ToolCallStartingEvent
├── ToolValidationFailedEvent
├── ToolCallFailedEvent
└── ToolCallCompletedEvent示例与快速入门
到日志记录器的基本跟踪
kotlin
// 创建一个 logger
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 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 服务器发送事件 (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：在智能体流水线中拦截事件的主要功能类。
- TraceFeatureConfig：用于自定义功能行为的配置类。
- 消息处理器：处理并输出跟踪事件的组件：
- TraceFeatureMessageLogWriter：将跟踪事件写入日志记录器。
- TraceFeatureMessageFileWriter：将跟踪事件写入文件。
- TraceFeatureMessageRemoteWriter：将跟踪事件发送到远程服务器。