追蹤
此頁面包含關於「追蹤」功能的詳細資訊，該功能為 AI 代理提供全面的追蹤能力。
功能概覽
「追蹤」功能是一個強大的監控與偵錯工具，可擷取代理執行的詳細資訊，包括：
- 策略執行
- LLM 呼叫
- LLM 串流（開始、影格、完成、錯誤）
- 工具呼叫
- 代理圖中的節點執行
此功能透過攔截代理管線中的關鍵事件，並將其轉發至可配置的訊息處理器來運作。這些處理器可以將追蹤資訊輸出到各種目的地，例如記錄檔或檔案系統中的其他類型檔案，讓開發人員能夠深入瞭解代理行為並有效地排查問題。
事件流程
- 「追蹤」功能攔截代理管線中的事件。
- 根據配置的訊息篩選器對事件進行篩選。
- 篩選後的事件被傳遞給註冊的訊息處理器。
- 訊息處理器對事件進行格式化並輸出到各自的目的地。
配置與初始化
基本設定
若要使用「追蹤」功能，您需要：
- 擁有一個或多個訊息處理器（您可以使用現有的處理器或建立自己的處理器）。
- 在您的代理中安裝
Tracing。 - 配置訊息篩選器（選擇性）。
- 將訊息處理器新增至該功能。
kotlin
// Defining a logger/file that will be used as a destination of trace messages
val logger = KotlinLogging.logger { }
val outputPath = Path("/path/to/trace.log")
// Creating an agent
val agent = AIAgent(
promptExecutor = simpleOllamaAIExecutor(),
llmModel = OllamaModels.Meta.LLAMA_3_2,
) {
install(Tracing) {
// Configure message processors to handle trace events
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)
// Filter for LLM-related events only
fileWriter.setMessageFilter { message ->
message is LLMCallStartingEvent || message is LLMCallCompletedEvent
}
// Filter for tool-related events only
fileWriter.setMessageFilter { message ->
message is ToolCallStartingEvent ||
message is ToolCallCompletedEvent ||
message is ToolValidationFailedEvent ||
message is ToolCallFailedEvent
}
// Filter for node execution events only
fileWriter.setMessageFilter { message ->
message is NodeExecutionStartingEvent || message is NodeExecutionCompletedEvent
}大量追蹤量
對於具有複雜策略或長時間執行執行的代理，追蹤事件的量可能會很大。請考慮使用以下方法來管理事件量：
- 使用特定的訊息篩選器來減少事件數量。
- 實作具有緩衝或取樣功能的自訂訊息處理器。
- 對記錄檔使用檔案輪替，以防止檔案過大。
相依圖
「追蹤」功能具有以下相依性：
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
├── AgentClosingEvent
├── GraphStrategyStartingEvent
├── FunctionalStrategyStartingEvent
├── StrategyCompletedEvent
├── NodeExecutionStartingEvent
├── NodeExecutionCompletedEvent
├── NodeExecutionFailedEvent
├── SubgraphExecutionStartingEvent
├── SubgraphExecutionCompletedEvent
├── SubgraphExecutionFailedEvent
├── LLMCallStartingEvent
├── LLMCallCompletedEvent
├── LLMStreamingStartingEvent
├── LLMStreamingFrameReceivedEvent
├── LLMStreamingFailedEvent
├── LLMStreamingCompletedEvent
├── ToolCallStartingEvent
├── ToolValidationFailedEvent
├── ToolCallFailedEvent
└── ToolCallCompletedEvent範例與快速入門
基本追蹤至記錄器
kotlin
// Create a logger
val logger = KotlinLogging.logger { }
fun main() {
runBlocking {
// Create an agent with tracing
val agent = AIAgent(
promptExecutor = simpleOllamaAIExecutor(),
llmModel = OllamaModels.Meta.LLAMA_3_2,
) {
install(Tracing) {
addMessageProcessor(TraceFeatureMessageLogWriter(logger))
}
}
// Run the agent
agent.run("Hello, agent!")
}
}錯誤處理與邊緣情況
無訊息處理器
如果沒有訊息處理器被新增至「追蹤」功能，系統將記錄一條警告：
Tracing Feature. No feature out stream providers are defined. Trace streaming has no target.該功能仍會攔截事件，但不會被處理或輸出至任何地方。
資源管理
訊息處理器可能會持有需要正確釋放的資源（例如檔案控制代碼）。使用 use 擴充函式來確保正確的清理作業：
kotlin
// Creating an agent
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)
}
}
// Run the agent
agent.run(input)
// Writer will be automatically closed when the block exits追蹤特定事件至檔案
kotlin
install(Tracing) {
val fileWriter = TraceFeatureMessageFileWriter(
outputPath,
{ path: Path -> SystemFileSystem.sink(path).buffered() }
)
addMessageProcessor(fileWriter)
// Only trace LLM calls
fileWriter.setMessageFilter { message ->
message is LLMCallStartingEvent || message is LLMCallCompletedEvent
}
}追蹤特定事件至遠端端點
當您需要透過網路發送事件資料時，可以使用追蹤至遠端端點的功能。啟動後，追蹤至遠端端點會在指定的連接埠號碼啟動一個輕量級伺服器，並透過 Kotlin 伺服器傳送事件 (SSE) 發送事件。
kotlin
// Creating an agent
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)
}
}
// Run the agent
agent.run(input)
// Writer will be automatically closed when the block exits在客戶端，您可以使用 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 ->
// Collect events from server
agentEvents.add(event as DefinedFeatureEvent)
// Stop collecting events on agent finished
if (event is AgentCompletedEvent) {
cancel()
}
}
}
client.connect()
collectEventsJob.join()
client.healthCheck()
}
}
listOf(clientJob).joinAll()API 文件
「追蹤」功能遵循模組化架構，包含以下關鍵組件：
- Tracing：攔截代理管線事件的主要功能類別。
- TraceFeatureConfig：用於自訂功能行為的配置類別。
- 訊息處理器：處理並輸出追蹤事件的組件：
- TraceFeatureMessageLogWriter：將追蹤事件寫入記錄器。
- TraceFeatureMessageFileWriter：將追蹤事件寫入檔案。
- TraceFeatureMessageRemoteWriter：將追蹤事件發送至遠端伺服器。