Skip to content

Agent 事件 ​

Agent 事件是作為 Agent 工作流(workflow)一部分發生的操作或互動。它們包括:

  • Agent 生命週期事件
  • 策略(Strategy)事件
  • 節點(Node)執行事件
  • LLM 呼叫事件
  • LLM 串流事件
  • 工具(Tool)執行事件

註:功能事件定義在 agents-core 模組中,並位於套件 ai.koog.agents.core.feature.model.events 下。諸如 agents-features-trace 和 agents-features-event-handler 等功能會取用這些事件,以處理並轉發 Agent 執行期間建立的訊息。

預定義事件類型 ​

Koog 提供預定義的事件類型,可用於自訂訊息處理器。根據其相關的實體,預定義事件可分為以下幾類:

Agent 事件 ​

AgentStartingEvent ​

代表 Agent 執行的開始。包含以下欄位:

名稱資料型別必填預設值描述
eventIdString是事件或事件組的唯一識別碼。
executionInfoAgentExecutionInfo是提供與此事件關聯的執行上下文資訊。
agentIdString是AI Agent 的唯一識別碼。
runIdString是AI Agent 執行的唯一識別碼。

AgentCompletedEvent ​

代表 Agent 執行的結束。包含以下欄位:

名稱資料型別必填預設值描述
eventIdString是事件或事件組的唯一識別碼。
executionInfoAgentExecutionInfo是提供與此事件關聯的執行上下文資訊。
agentIdString是AI Agent 的唯一識別碼。
runIdString是AI Agent 執行的唯一識別碼。
resultString是Agent 執行的結果。如果沒有結果,可以為 null。

AgentExecutionFailedEvent ​

代表 Agent 執行期間發生的錯誤。包含以下欄位:

名稱資料型別必填預設值描述
eventIdString是事件或事件組的唯一識別碼。
executionInfoAgentExecutionInfo是提供與此事件關聯的執行上下文資訊。
agentIdString是AI Agent 的唯一識別碼。
runIdString是AI Agent 執行的唯一識別碼。
errorAIAgentError是Agent 執行期間發生的特定錯誤。欲了解更多資訊,請參閱 AIAgentError。

AgentClosingEvent ​

代表 Agent 的關閉或終止。包含以下欄位:

名稱資料型別必填預設值描述
eventIdString是事件或事件組的唯一識別碼。
executionInfoAgentExecutionInfo是提供與此事件關聯的執行上下文資訊。
agentIdString是AI Agent 的唯一識別碼。

AIAgentError 類別提供有關 Agent 執行期間發生錯誤的更多詳細資訊。包含以下欄位:

名稱資料型別必填預設值描述
messageString是提供有關特定錯誤的詳細資訊訊息。
stackTraceString是到最後執行程式碼為止的堆疊記錄集合。
causeString否null錯誤原因(如果可用)。

AgentExecutionInfo 類別提供有關執行路徑的上下文資訊,以便追蹤 Agent 執行中的巢狀執行上下文。包含以下欄位:

名稱資料型別必填預設值描述
parentAgentExecutionInfo否null對父級執行上下文的引用。如果為 null,則代表根執行層級。
partNameString是代表當前執行部分或片段名稱的字串。

策略事件 ​

GraphStrategyStartingEvent ​

代表基於圖(graph-based)的策略執行的開始。包含以下欄位:

名稱資料型別必填預設值描述
eventIdString是事件或事件組的唯一識別碼。
executionInfoAgentExecutionInfo是提供與此事件關聯的執行上下文資訊。
runIdString是策略執行的唯一識別碼。
strategyNameString是策略的名稱。
graphStrategyEventGraph是代表策略工作流的圖結構。

FunctionalStrategyStartingEvent ​

代表函數式(functional)策略執行的開始。包含以下欄位:

名稱資料型別必填預設值描述
eventIdString是事件或事件組的唯一識別碼。
executionInfoAgentExecutionInfo是提供與此事件關聯的執行上下文資訊。
runIdString是策略執行的唯一識別碼。
strategyNameString是策略的名稱。

StrategyCompletedEvent ​

代表策略執行的結束。包含以下欄位:

名稱資料型別必填預設值描述
eventIdString是事件或事件組的唯一識別碼。
executionInfoAgentExecutionInfo是提供與此事件關聯的執行上下文資訊。
runIdString是策略執行的唯一識別碼。
strategyNameString是策略的名稱。
resultString是執行的結果。如果沒有結果,可以為 null。

節點事件 ​

NodeExecutionStartingEvent ​

代表節點執行的開始。包含以下欄位:

名稱資料型別必填預設值描述
eventIdString是事件或事件組的唯一識別碼。
executionInfoAgentExecutionInfo是提供與此事件關聯的執行上下文資訊。
runIdString是策略執行的唯一識別碼。
nodeNameString是開始執行的節點名稱。
inputJsonElement否null節點的輸入值。

NodeExecutionCompletedEvent ​

代表節點執行的結束。包含以下欄位:

名稱資料型別必填預設值描述
eventIdString是事件或事件組的唯一識別碼。
executionInfoAgentExecutionInfo是提供與此事件關聯的執行上下文資訊。
runIdString是策略執行的唯一識別碼。
nodeNameString是結束執行的節點名稱。
inputJsonElement否null節點的輸入值。
outputJsonElement否null節點產生的輸出值。

NodeExecutionFailedEvent ​

代表節點執行期間發生的錯誤。包含以下欄位:

名稱資料型別必填預設值描述
eventIdString是事件或事件組的唯一識別碼。
executionInfoAgentExecutionInfo是提供與此事件關聯的執行上下文資訊。
runIdString是策略執行的唯一識別碼。
nodeNameString是發生錯誤的節點名稱。
inputJsonElement否null提供給節點的輸入資料。
errorAIAgentError是節點執行期間發生的特定錯誤。欲了解更多資訊,請參閱 AIAgentError。

子圖事件 ​

SubgraphExecutionStartingEvent ​

代表子圖(subgraph)執行的開始。包含以下欄位:

名稱資料型別必填預設值描述
eventIdString是事件或事件組的唯一識別碼。
executionInfoAgentExecutionInfo是提供與此事件關聯的執行上下文資訊。
runIdString是策略執行的唯一識別碼。
subgraphNameString是開始執行的子圖名稱。
inputJsonElement否null子圖的輸入值。

SubgraphExecutionCompletedEvent ​

代表子圖執行的結束。包含以下欄位:

名稱資料型別必填預設值描述
eventIdString是事件或事件組的唯一識別碼。
executionInfoAgentExecutionInfo是提供與此事件關聯的執行上下文資訊。
runIdString是策略執行的唯一識別碼。
subgraphNameString是結束執行的子圖名稱。
inputJsonElement否null子圖的輸入值。
outputJsonElement否null子圖產生的輸出值。

SubgraphExecutionFailedEvent ​

代表子圖執行期間發生的錯誤。包含以下欄位:

名稱資料型別必填預設值描述
eventIdString是事件或事件組的唯一識別碼。
executionInfoAgentExecutionInfo是提供與此事件關聯的執行上下文資訊。
runIdString是策略執行的唯一識別碼。
subgraphNameString是發生錯誤的子圖名稱。
inputJsonElement否null提供給子圖的輸入資料。
errorAIAgentError是子圖執行期間發生的特定錯誤。欲了解更多資訊,請參閱 AIAgentError。

LLM 呼叫事件 ​

LLMCallStartingEvent ​

代表 LLM 呼叫的開始。包含以下欄位:

名稱資料型別必填預設值描述
eventIdString是事件或事件組的唯一識別碼。
executionInfoAgentExecutionInfo是提供與此事件關聯的執行上下文資訊。
runIdString是LLM 執行的唯一識別碼。
promptPrompt是傳送給模型的提示。欲了解更多資訊,請參閱 Prompt。
modelModelInfo是模型資訊。請參閱 ModelInfo。
toolsList<String>是模型可以呼叫的工具列表。

Prompt 類別代表提示的資料結構,由訊息列表、唯一識別碼和語言模型設定的選用參數組成。包含以下欄位:

名稱資料型別必填預設值描述
messagesList<Message>是組成提示的訊息列表。
idString是提示的唯一識別碼。
paramsLLMParams否LLMParams()控制 LLM 產生內容方式的設定。

ModelInfo 類別代表有關語言模型的資訊,包括其提供者、模型識別碼和特性。包含以下欄位:

名稱資料型別必填預設值描述
providerString是提供者識別碼(例如 "openai"、"google"、"anthropic")。
modelString是模型識別碼(例如 "gpt-4"、"claude-3")。
displayNameString否null選用的模型易讀顯示名稱。
contextLengthLong否null模型可以處理的最大權杖(tokens)數量。
maxOutputTokensLong否null模型可以產生的最大權杖數量。

LLMCallCompletedEvent ​

代表 LLM 呼叫的結束。包含以下欄位:

名稱資料型別必填預設值描述
eventIdString是事件或事件組的唯一識別碼。
executionInfoAgentExecutionInfo是提供與此事件關聯的執行上下文資訊。
runIdString是LLM 執行的唯一識別碼。
promptPrompt是呼叫中使用的提示。
modelModelInfo是模型資訊。請參閱 ModelInfo。
responsesList<Message.Response>是模型傳回的一或多個回應。
moderationResponseModerationResult否null稽核回應(如果有)。

LLMCallFailedEvent ​

代表 LLM 呼叫期間發生的錯誤。包含以下欄位:

名稱資料型別必填預設值描述
eventIdString是事件或事件組的唯一識別碼。
executionInfoAgentExecutionInfo是提供與此事件關聯的執行上下文資訊。
runIdString是LLM 執行的唯一識別碼。
promptPrompt是傳送給模型的提示。
modelModelInfo是模型資訊。請參閱 ModelInfo。
toolsList<String>是模型可以呼叫的工具列表。
errorAIAgentError是呼叫期間發生的特定錯誤。欲了解更多資訊,請參閱 AIAgentError。

LLM 串流事件 ​

LLMStreamingStartingEvent ​

代表 LLM 串流呼叫的開始。包含以下欄位:

名稱資料型別必填預設值描述
eventIdString是事件或事件組的唯一識別碼。
executionInfoAgentExecutionInfo是提供與此事件關聯的執行上下文資訊。
runIdString是LLM 執行的唯一識別碼。
promptPrompt是傳送給模型的提示。
modelModelInfo是模型資訊。請參閱 ModelInfo。
toolsList<String>是模型可以呼叫的工具列表。

LLMStreamingFrameReceivedEvent ​

代表從 LLM 收到的串流影格(frame)。包含以下欄位:

名稱資料型別必填預設值描述
eventIdString是事件或事件組的唯一識別碼。
executionInfoAgentExecutionInfo是提供與此事件關聯的執行上下文資訊。
runIdString是LLM 執行的唯一識別碼。
promptPrompt是傳送給模型的提示。
modelModelInfo是模型資訊。請參閱 ModelInfo。
frameStreamFrame是從串流收到的影格。

LLMStreamingFailedEvent ​

代表 LLM 串流呼叫期間發生的錯誤。包含以下欄位:

名稱資料型別必填預設值描述
eventIdString是事件或事件組的唯一識別碼。
executionInfoAgentExecutionInfo是提供與此事件關聯的執行上下文資訊。
runIdString是LLM 執行的唯一識別碼。
promptPrompt是傳送給模型的提示。
modelModelInfo是模型資訊。請參閱 ModelInfo。
errorAIAgentError是串流期間發生的特定錯誤。欲了解更多資訊,請參閱 AIAgentError。

LLMStreamingCompletedEvent ​

代表 LLM 串流呼叫的結束。包含以下欄位:

名稱資料型別必填預設值描述
eventIdString是事件或事件組的唯一識別碼。
executionInfoAgentExecutionInfo是提供與此事件關聯的執行上下文資訊。
runIdString是LLM 執行的唯一識別碼。
promptPrompt是傳送給模型的提示。
modelModelInfo是模型資訊。請參閱 ModelInfo。
toolsList<String>是模型可以呼叫的工具列表。

工具執行事件 ​

ToolCallStartingEvent ​

代表模型呼叫工具的事件。包含以下欄位:

名稱資料型別必填預設值描述
eventIdString是事件或事件組的唯一識別碼。
executionInfoAgentExecutionInfo是提供與此事件關聯的執行上下文資訊。
runIdString是策略/Agent 執行的唯一識別碼。
toolCallIdString否null工具呼叫的識別碼(如果可用)。
toolNameString是工具的名稱。
toolArgsJsonObject是提供給工具的引數。

ToolValidationFailedEvent ​

代表工具呼叫期間發生的驗證錯誤。包含以下欄位:

名稱資料型別必填預設值描述
eventIdString是事件或事件組的唯一識別碼。
executionInfoAgentExecutionInfo是提供與此事件關聯的執行上下文資訊。
runIdString是策略/Agent 執行的唯一識別碼。
toolCallIdString否null工具呼叫的識別碼(如果可用)。
toolNameString是驗證失敗的工具名稱。
toolArgsJsonObject是提供給工具的引數。
toolDescriptionString否null遇到驗證錯誤的工具描述。
messageString否null描述驗證錯誤的訊息。
errorAIAgentError是發生的特定錯誤。欲了解更多資訊,請參閱 AIAgentError。

ToolCallFailedEvent ​

代表執行工具失敗。包含以下欄位:

名稱資料型別必填預設值描述
eventIdString是事件或事件組的唯一識別碼。
executionInfoAgentExecutionInfo是提供與此事件關聯的執行上下文資訊。
runIdString是策略/Agent 執行的唯一識別碼。
toolCallIdString否null工具呼叫的識別碼(如果可用)。
toolNameString是工具的名稱。
toolArgsJsonObject是提供給工具的引數。
toolDescriptionString否null失敗的工具描述。
errorAIAgentError是嘗試呼叫工具時發生的特定錯誤。欲了解更多資訊,請參閱 AIAgentError。

ToolCallCompletedEvent ​

代表成功的工具呼叫並傳回結果。包含以下欄位:

名稱資料型別必填預設值描述
eventIdString是事件或事件組的唯一識別碼。
executionInfoAgentExecutionInfo是提供與此事件關聯的執行上下文資訊。
runIdString是執行的唯一識別碼。
toolCallIdString否null工具呼叫的識別碼。
toolNameString是工具的名稱。
toolArgsJsonObject是提供給工具的引數。
toolDescriptionString否null已執行工具的描述。
resultJsonElement否null工具呼叫的結果。

常見問題與疑難排解 ​

以下部分包含與追蹤(Tracing)功能相關的常見問題及解答。

如何僅追蹤 Agent 執行的特定部分? ​

使用 messageFilter 屬性來篩選事件。例如,僅追蹤節點執行:

kotlin
install(Tracing) {
    val fileWriter = TraceFeatureMessageFileWriter.create(outputPath)
    addMessageProcessor(fileWriter)

    // 僅追蹤 LLM 呼叫
    fileWriter.setMessageFilter { message ->
        message is LLMCallStartingEvent || message is LLMCallCompletedEvent
    }
}
java
.install(Tracing.Feature, config -> {
    var fileWriter = TraceFeatureMessageFileWriter.create(outputPath);
    config.addMessageProcessor(fileWriter);

    // 僅追蹤 LLM 呼叫
    fileWriter.setMessageFilter(message ->
        message instanceof LLMCallStartingEvent || message instanceof LLMCallCompletedEvent
    );
})

我可以使用多個訊息處理器嗎? ​

可以,您可以新增多個訊息處理器,同時將追蹤記錄傳送到不同的目的地:

kotlin
install(Tracing) {
    addMessageProcessor(TraceFeatureMessageLogWriter(logger))
    addMessageProcessor(TraceFeatureMessageFileWriter.create(outputPath))
    addMessageProcessor(TraceFeatureMessageRemoteWriter(connectionConfig))
}
java
.install(Tracing.Feature, config -> {
    config.addMessageProcessor(TraceFeatureMessageLogWriter.create(logger));
    config.addMessageProcessor(TraceFeatureMessageFileWriter.create(outputPath));
    config.addMessageProcessor(new TraceFeatureMessageRemoteWriter());
})

如何建立自訂訊息處理器? ​

實作 FeatureMessageProcessor 介面:

kotlin
class CustomTraceProcessor : FeatureMessageProcessor() {

    override suspend fun processMessage(message: FeatureMessage) {
        // 自訂處理邏輯
        if (message is NodeExecutionStartingEvent) {
            // 處理節點啟動事件
        } else if (message is LLMCallCompletedEvent) {
            // 處理 LLM 呼叫結束事件
        } else {
            // 處理其他事件類型
        }
    }

    override suspend fun close() {
        // 關閉已建立的連線
    }
}

val agent = AIAgent(
    promptExecutor = simpleOllamaAIExecutor(),
    llmModel = OllamaModels.Meta.LLAMA_3_2,
) {
    install(Tracing) {
        // 使用您的自訂處理器
        addMessageProcessor(CustomTraceProcessor())
    }
}
java
class CustomTraceProcessor extends FeatureMessageProcessor {

    @Override
    protected void handleMessage(FeatureMessage message) {
        // 自訂處理邏輯
        if (message instanceof NodeExecutionStartingEvent) {
            // 處理節點啟動事件
        } else if (message instanceof LLMCallCompletedEvent) {
            // 處理 LLM 呼叫結束事件
        } else {
            // 處理其他事件類型
        }
    }

    @Override
    public void handleClose() {
        // 關閉已建立的連線
    }
}

var agent = AIAgent.builder()
    .promptExecutor(PromptExecutor.builder().ollama().build())
    .llmModel(OllamaModels.Meta.LLAMA_3_2)

    .install(Tracing.Feature, config -> {
        // 使用您的自訂處理器
        config.addMessageProcessor(new CustomTraceProcessor());
    })
    .build();

欲了解更多可由訊息處理器處理的現有事件類型資訊,請參閱 預定義事件類型。