Koog(8)——Agent工程化:自定义 Feature、事件追踪与测试

前言

上一篇文章把一次模型调用的输入、控制和输出讲完了。但那篇文章的 3.6 节留了一个尾巴:onLLMStreamingFrameReceived 这类事件钩子"属于事件体系的用法,第八篇讲可观测性时一并展开"。更早的第 6 篇 1.4 节也只讲了怎么 install 一个现成的 feature——用你熟悉的 Ktor 插件类比带过了安装,没有讲 feature 本身是什么、怎么自己写一个。

这篇把这两笔账一起算清。主线是一条:Agent 的事件/拦截器底座。自定义 feature、事件处理、Tracing 和 OpenTelemetry 都建立在这套机制上;内容审核则是模型调用层提供的独立能力,不需要先安装一个“审核 feature”。随后再补序列化和测试。

本文继续以 Koog 1.3.0 正式版的 Kotlin API 为基准,Kotlin 2.4.10、JDK 21 编译运行。和第七篇不同,本篇不需要 koog-agents-additions,使用的 Koog 依赖统一为 1.3.0 正式版,另需相应功能依赖,且本篇验证不需要真实模型——feature、事件、追踪这些机制验证的是框架行为,用一个不注册任何厂商客户端的离线替身就能完整跑通,输出可复现。有两个例外会明确标注:内容审核一节只有编译验证(DeepSeek 没有审核端点,见 5.3);第七章直接给出完整的 mock 测试类,可独立保存和运行。

示例除 koog-agents:1.3.0 外,还显式使用 agents-features-event-handler、agents-features-trace、agents-features-opentelemetry、serialization-jackson(均为 1.3.0),以及 kotlinx-coroutines-core:1.10.2 和 opentelemetry-exporter-logging:1.61.0。测试依赖见 7.1。源码中的 @Serializable 还需要 Kotlin serialization 编译插件。

官方页面与 1.3.0 发布源码存在个别差异,下面按核实到的具体 API 说明;“有差异”不等于已经确认它属于哪个新版本。

一、Feature 机制:从 install 到自己写一个

1.1 回顾与定位

第 6 篇 1.4 讲过:feature 是挂在 agent 上的扩展点,install(ChatMemory) 就像 Ktor 里 install(ContentNegotiation)。官方文档给 feature 的定位是四件事:加新能力、拦截并修改 agent 行为、记录与监控执行、在同一个 feature 里为同一事件注册多个处理器。

Koog 开箱提供六个 feature:EventHandler(事件处理)、Tracing(追踪)、ChatMemory(会话记忆)、LongTermMemory(长期记忆,beta)、Persistence(持久化)、OpenTelemetry。本篇重点讲 EventHandler、Tracing 和 OpenTelemetry;ChatMemory、Persistence 已在第六篇讲过,LongTermMemory 的完整用法留给第九篇。这里列的是官网 Features 概览中的主要功能,不是全部 feature 的穷举。

用和没用的区别在哪?没有 feature 机制,这些横切逻辑往往要散落在业务流程里;有了它,能力是外挂的:不装就没有,装了才生效,但能否安装在某类 agent 上,取决于它实现了哪些 feature 接口。这也是为什么 Tracing、OpenTelemetry、EventHandler 的官方实现和我们接下来要写的自定义 feature 在结构上是同一套东西。

1.2 三种管道,三个接口

第二篇讲过 Koog 的三种 agent 类型:graph(策略图)、functional(函数式)、planner。feature 机制对应地提供了三个接口:

接口 install 的管道参数 可用拦截器
AIAgentGraphFeature AIAgentGraphPipeline 公共拦截器 + node/subgraph 拦截器
AIAgentFunctionalFeature AIAgentFunctionalPipeline 公共拦截器
AIAgentPlannerFeature AIAgentPlannerPipeline 公共拦截器

"公共拦截器"声明在三者共同的抽象基类 AIAgentPipeline 上,覆盖 agent、strategy、LLM 调用、流式、工具调用五组生命周期;node 和 subgraph 级别的拦截器只在 Graph 管道上存在——函数式和 planner 策略没有"节点"概念,自然也没有节点事件。

一个 feature 想在三种 agent 上都能装,就三个接口都实现;只想服务 graph agent,实现一个就够。1.3.0 没有"一个 install 适配所有管道"的统一入口,三套管道各有一个 install(config, pipeline) 重载——官方文档的 Custom features 页面在这点上与 1.3.0 一致。

1.3 写一个日志 feature

直接上完整代码。这个 LoggingFeature 在 agent 启动/结束、LLM 调用前后打日志,graph agent 上额外拦截节点执行:

import ai.koog.agents.core.agent.config.AIAgentConfig
import ai.koog.agents.core.agent.entity.createStorageKey
import ai.koog.agents.core.feature.AIAgentFunctionalFeature
import ai.koog.agents.core.feature.AIAgentGraphFeature
import ai.koog.agents.core.feature.AIAgentPlannerFeature
import ai.koog.agents.core.feature.config.FeatureConfig
import ai.koog.agents.core.feature.pipeline.AIAgentFunctionalPipeline
import ai.koog.agents.core.feature.pipeline.AIAgentGraphPipeline
import ai.koog.agents.core.feature.pipeline.AIAgentPipeline
import ai.koog.agents.core.feature.pipeline.AIAgentPlannerPipeline

class LoggingConfig : FeatureConfig() {
    var tag: String = "LoggingFeature"
}

object LoggingFeature :
    AIAgentGraphFeature<LoggingConfig, LoggingFeature>,
    AIAgentFunctionalFeature<LoggingConfig, LoggingFeature>,
    AIAgentPlannerFeature<LoggingConfig, LoggingFeature> {

    // 唯一 storage key:feature 在 agent 内部按 key 存取
    override val key = createStorageKey<LoggingFeature>("koog8-logging")

    override fun createInitialConfig(agentConfig: AIAgentConfig): LoggingConfig = LoggingConfig()

    override fun install(config: LoggingConfig, pipeline: AIAgentGraphPipeline): LoggingFeature {
        registerCommon(config, pipeline)
        // node 级拦截器只有 Graph 管道有
        pipeline.interceptNodeExecutionStarting(this) { ctx ->
            println("[${config.tag}] node.start    ${ctx.node.name} input=${ctx.input}")
        }
        pipeline.interceptNodeExecutionCompleted(this) { ctx ->
            println("[${config.tag}] node.complete ${ctx.node.name} output=${ctx.output}")
        }
        return LoggingFeature
    }

    override fun install(config: LoggingConfig, pipeline: AIAgentFunctionalPipeline): LoggingFeature {
        registerCommon(config, pipeline)
        return LoggingFeature
    }

    override fun install(config: LoggingConfig, pipeline: AIAgentPlannerPipeline): LoggingFeature {
        registerCommon(config, pipeline)
        return LoggingFeature
    }

    private fun registerCommon(config: LoggingConfig, pipeline: AIAgentPipeline) {
        pipeline.interceptAgentStarting(this) { ctx ->
            println("[${config.tag}] agent.start   id=${ctx.agent.id} runId=${ctx.runId}")
        }
        pipeline.interceptAgentCompleted(this) { ctx ->
            println("[${config.tag}] agent.complete runId=${ctx.runId} result=${ctx.result}")
        }
        pipeline.interceptLLMCallStarting(this) { ctx ->
            println("[${config.tag}] llm.start     model=${ctx.model.id}")
        }
        pipeline.interceptLLMCallCompleted(this) { ctx ->
            println("[${config.tag}] llm.complete  response=${ctx.response?.parts?.size} parts")
        }
    }
}

结构上有五个要素,对照着看:

  1. Config 类继承 FeatureConfig,装 feature 时通过 lambda 配置(install(LoggingFeature) { tag = "graph" })。
  2. 本例直接用 object 实现 feature 接口,类型参数为 <Config, FeatureImpl>,并在 install 中返回自身。另一种常见写法是由 feature 类的 companion object 实现安装接口,再为每次安装创建一个运行时实例。Config 用于安装参数,不应把所有运行时状态都塞进共享的单例;需要跨事件保存状态时,可在 install 中创建实例并由回调持有。
  3. key 用 createStorageKey 创建,是 feature 在 agent 内部注册表里的唯一标识。1.3.0 的 createStorageKey 本身是公开 API,不需要为它添加 @OptIn(InternalAgentsApi::class)。key 用于区分 feature,而不承担不同 agent 之间的状态隔离。
  4. createInitialConfig 提供默认配置。
  5. 每个管道一个 install,在里面注册拦截器并返回 feature 实例。公共拦截器抽成 registerCommon 避免三份重复——这也是官方日志示例的组织方式。

将上面的定义保存为 LoggingFeature.kt。下面是完整的 LoggingFeatureDemo.kt,与它及附录的 OfflineExecutor.kt 放在同一默认 package 中运行;各文件的 import 分别放在文件顶部:

import ai.koog.agents.core.agent.AIAgent
import ai.koog.agents.core.agent.config.AIAgentConfig
import ai.koog.agents.core.dsl.builder.*
import ai.koog.prompt.Prompt
import kotlinx.coroutines.runBlocking

fun main() = runBlocking {
    val executor = OfflineExecutor()
    val agentConfig = AIAgentConfig(prompt = Prompt.Empty, model = OfflineModel, maxAgentIterations = 10)
    val graph = strategy<String, String>("graph-demo") {
        val echo by node<String, String> { input ->
            llm.writeSession {
                appendPrompt { user(input) }
                requestLLM().toString()
            }
        }
        nodeStart then echo then nodeFinish
    }
    val graphAgent = AIAgent(promptExecutor = executor, agentConfig = agentConfig, strategy = graph) {
        install(LoggingFeature) { tag = "graph" }
    }
    graphAgent.run("讲个故事")
    graphAgent.close()
    Unit
}

这份程序通过离线执行器运行一次 graph agent。下面节选本次日志,省略 UUID 与较长的 Assistant 元信息;它们每次运行都会变化:

[graph] agent.start   id=448d5611-… runId=cb7c34b6-…
[graph] node.start    __start__ input=讲个故事
[graph] node.complete __start__ output=讲个故事
[graph] node.start    echo input=讲个故事
[graph] llm.start     model=offline-model
[graph] llm.complete  response=1 parts
[graph] node.complete echo output=Assistant(parts=[Text(text=离线回复:从前有一座山。, …)…
[graph] agent.complete runId=cb7c34b6-… result=Assistant(…

另一个对照实验在 functional agent 上安装了相同 feature,只出现公共生命周期日志,没有 Graph 的节点日志。本篇运行验证覆盖 Graph 和 Functional 两种安装路径;Planner 重载仅检查编译,没有运行 planner 策略。

1.4 拦截器矩阵

install 里能注册的拦截器,按生命周期分五组公共的加一组 graph 专属的:

组 拦截器
Agent 生命周期 interceptEnvironmentCreated / interceptAgentStarting / interceptAgentCompleted / interceptAgentExecutionFailed / interceptAgentClosing
Strategy interceptStrategyStarting / interceptStrategyCompleted
LLM 调用 interceptLLMCallStarting / interceptLLMCallFailed / interceptLLMCallCompleted
LLM 流式 interceptLLMStreamingStarting / ...FrameReceived / ...Failed / ...Completed
工具调用 interceptToolCallStarting / interceptToolValidationFailed / interceptToolCallFailed / interceptToolCallCompleted
Graph 专属 interceptNodeExecutionStarting / ...Completed / ...Failed;interceptSubgraphExecutionStarting / ...Completed / ...Failed

两点提醒。第一,Kotlin 侧生命周期回调是 suspend lambda,环境拦截器则是返回新环境的转换器。回调会被执行流程等待,慢网络操作会拉长 agent 耗时;suspend 也不会自动让阻塞 IO 变成非阻塞。回调异常可能影响主流程,监控逻辑应控制耗时并明确错误策略。第二,官方文档特别强调只注册需要的拦截器——每个拦截器都有调用开销,全量注册在长运行 agent 上不是免费的。第六篇讲 Persistence 时看到的 interceptStrategyStarting(恢复检查点用的),现在你知道它就是这张表里 Strategy 组的一员。

1.5 事件过滤

装 feature 的人可能只想让它处理部分事件。FeatureConfig.setEventFilter 提供这个口子:

import ai.koog.agents.core.feature.handler.AgentLifecycleEventType

// 局部片段:放在 agent 的 feature 配置块中。
install(LoggingFeature) {
    setEventFilter { context ->
        context.eventType is AgentLifecycleEventType.LLMCallStarting ||
            context.eventType is AgentLifecycleEventType.LLMCallCompleted
    }
}

反过来,如果 feature 的实现依赖完整事件流,安装方的过滤会破坏它的逻辑。写 feature 的人可以在 Config 里覆盖 setEventFilter 直接抛异常来禁用过滤:

import ai.koog.agents.core.feature.config.FeatureConfig
import ai.koog.agents.core.feature.handler.AgentLifecycleEventContext

class MyFeatureConfig : FeatureConfig() {
    override fun setEventFilter(filter: (AgentLifecycleEventContext) -> Boolean) {
        throw UnsupportedOperationException("Event filtering is not allowed.")
    }
}

官方举的例子就是 OpenTelemetry:span 层级靠完整事件结构组装,被过滤就断了。4.2 会再碰到它。过滤由管道按已注册 feature 的配置判断,当前 LoggingFeature 不需要在每个回调里再手动调用过滤器。

二、Agent 事件与 EventHandler

2.1 事件体系

自定义 feature 的拦截器是"我主动伸手要事件";这一节换成框架的另一种供给方式——事件对象。事件定义在 ai.koog.agents.core.feature.model.events 包里,按主体分七类:

类别 事件(部分)
Agent AgentStartingEvent / AgentCompletedEvent / AgentExecutionFailedEvent / AgentClosingEvent
Strategy GraphStrategyStartingEvent / FunctionalStrategyStartingEvent / StrategyCompletedEvent
Node NodeExecutionStartingEvent / NodeExecutionCompletedEvent / NodeExecutionFailedEvent
Subgraph SubgraphExecutionStartingEvent / ...CompletedEvent / ...FailedEvent
LLM 调用 LLMCallStartingEvent / LLMCallCompletedEvent / LLMCallFailedEvent
LLM 流式 LLMStreamingStartingEvent / LLMStreamingFrameReceivedEvent / ...FailedEvent / ...CompletedEvent
工具 ToolCallStartingEvent / ToolCallCompletedEvent / ToolValidationFailedEvent / ToolCallFailedEvent

这里列出的内置生命周期事件带有 eventId、executionInfo 和时间戳,executionInfo.parent 描述嵌套执行路径。与某次 run 相关的事件通常带 runId;但 AgentClosingEvent 只有 agentId,没有 runId,它描述的是 agent 关闭,不等于某次 run 完成。失败事件中的 AIAgentError 提供 message、stackTrace、cause。按字段关联事件时,应区分 agent、run 与事件配对 ID,不能假设每种事件字段完全相同。

2.2 handleEvents:最省事的监听方式

大多数场景不想写整个 feature,只想挂几个回调。handleEvents 会安装并配置 EventHandler。下面是完整的 EventHandlerDemo.kt,只依赖附录的离线执行器;它包含日志里用到的全部回调:

import ai.koog.agents.core.agent.AIAgent
import ai.koog.agents.core.agent.config.AIAgentConfig
import ai.koog.agents.core.dsl.builder.*
import ai.koog.agents.features.eventHandler.feature.handleEvents
import ai.koog.agents.core.feature.handler.node.NodeExecutionStartingContext
import ai.koog.agents.core.feature.handler.streaming.LLMStreamingFrameReceivedContext
import ai.koog.prompt.Prompt
import kotlinx.coroutines.runBlocking

fun main() = runBlocking {
    val executor = OfflineExecutor()

    var llmCalls = 0
    var streamFrames = 0

    val graph = strategy<String, String>("events-demo") {
        val talk by node<String, String> { input ->
            llm.writeSession {
                appendPrompt { user(input) }
                // 一次普通调用 + 一次流式调用,分别触发 LLM call 与 streaming 事件
                val answer = requestLLM()
                requestLLMStreaming().collect { }
                answer.toString()
            }
        }
        nodeStart then talk then nodeFinish
    }

    val agent = AIAgent(
        promptExecutor = executor,
        agentConfig = AIAgentConfig(prompt = Prompt.Empty, model = OfflineModel, maxAgentIterations = 10),
        strategy = graph,
    ) {
        handleEvents {
            onAgentStarting { ctx ->
                println("[onAgentStarting] agentId=${ctx.agent.id}")
            }
            onAgentCompleted { ctx ->
                println("[onAgentCompleted] result=${ctx.result}")
            }
            onAgentClosing { ctx ->
                println("[onAgentClosing] agentId=${ctx.agent.id}")
            }
            onNodeExecutionStarting { ctx ->
                println("[onNodeExecutionStarting] node=${ctx.node.name}")
            }
            onNodeExecutionCompleted { ctx ->
                println("[onNodeExecutionCompleted] node=${ctx.node.name}")
            }
            onLLMCallStarting { ctx ->
                llmCalls++
                println("[onLLMCallStarting] model=${ctx.model.id} promptMessages=${ctx.prompt.messages.size}")
            }
            onLLMCallCompleted { ctx ->
                println("[onLLMCallCompleted] response=${ctx.response != null}")
            }
            onLLMStreamingFrameReceived { ctx ->
                streamFrames++
                println("[onLLMStreamingFrameReceived] frame=${ctx.streamFrame::class.simpleName}")
            }
            onLLMStreamingCompleted { ctx ->
                println("[onLLMStreamingCompleted] runId=${ctx.runId}")
            }
            onToolCallStarting { ctx ->
                println("[onToolCallStarting] tool=${ctx.toolName}")
            }
        }
    }

    try {
        val result = agent.run("讲个故事")
        check(llmCalls >= 1) { "expected >=1 LLM call event, got $llmCalls" }
        check(streamFrames >= 3) { "expected >=3 streaming frames, got $streamFrames" }
        println("result=$result")
        println("llmCalls=$llmCalls streamFrames=$streamFrames")
        println("Demo2 PASS")
    } finally {
        agent.close()
        executor.close()
    }
    Unit
}

一个完整程序里同时做一次普通调用和一次流式调用,事件的到达顺序(节选):

[onAgentStarting] agentId=4549d041-…
[onNodeExecutionStarting] node=__start__
[onNodeExecutionStarting] node=talk
[onLLMCallStarting] model=offline-model promptMessages=1
[onLLMCallCompleted] response=true
[onLLMStreamingFrameReceived] frame=TextDelta
[onLLMStreamingFrameReceived] frame=TextDelta
[onLLMStreamingFrameReceived] frame=TextComplete
[onLLMStreamingFrameReceived] frame=End
[onLLMStreamingCompleted] runId=95b6bb38-…
[onNodeExecutionCompleted] node=talk
[onAgentCompleted] result=Assistant(…
[onAgentClosing] agentId=4549d041-…

第七篇 3.6 预告的 onLLMStreamingFrameReceived 就是它:每个 frame 到达触发一次,四次流式帧(两个 TextDelta、一个 TextComplete、一个 End)对应四条回调。

区分回调上下文和可传输的 Event 对象:onLLMCallCompleted 接收的是 LLMCallCompletedContext,1.3.0 通过 response 取得单个、可空的 Message.Assistant。同版本的 LLMCallCompletedEvent 也使用单数 response;官网 Agent events 表格里的复数 responses 与该发布版本不一致,不能据此推断回调也返回一个响应列表。

2.3 FeatureMessageProcessor:接收事件对象

1.5 的拦截器和 2.2 的回调都是"函数式"消费;事件对象(2.1 的那些 Event 类)则通过 FeatureMessageProcessor 消费。JVM 上继承它只需覆写两个方法:

import ai.koog.agents.core.agent.AIAgent
import ai.koog.agents.core.agent.config.AIAgentConfig
import ai.koog.agents.core.dsl.builder.*
import ai.koog.agents.core.feature.message.FeatureMessage
import ai.koog.agents.core.feature.message.FeatureMessageProcessor
import ai.koog.agents.features.tracing.feature.Tracing
import ai.koog.prompt.Prompt
import kotlinx.coroutines.runBlocking

class EventCollectorProcessor : FeatureMessageProcessor() {
    val collected = mutableListOf<String>()
    override fun handleMessage(message: FeatureMessage) {
        collected += message::class.simpleName ?: "?"
        println("[collector] ${message::class.simpleName}")
    }
    override fun handleClose() {
        println("[collector] closed, total=${collected.size}")
    }
}

fun main() = runBlocking {
    val executor = OfflineExecutor()
    val collector = EventCollectorProcessor()
    val graph = strategy<String, String>("processor-demo") {
        val talk by node<String, String> { input ->
            llm.writeSession {
                appendPrompt { user(input) }
                requestLLM().toString()
            }
        }
        nodeStart then talk then nodeFinish
    }
    val agent = AIAgent(
        promptExecutor = executor,
        agentConfig = AIAgentConfig(prompt = Prompt.Empty, model = OfflineModel, maxAgentIterations = 10),
        strategy = graph,
    ) {
        install(Tracing) {
            addMessageProcessor(collector)
        }
    }
    try {
        agent.run("讲个故事")
        agent.close()
        println("total=${collector.collected.size} kinds=${collector.collected.distinct().size}")
    } finally { executor.close() }
    Unit
}

本例由 Tracing 将事件对象转发给 collector,不是 EventHandler 回调直接把对象推入这个集合。处理器类本身也可以被其他生产者复用;并非定义一个 processor 就自动订阅了所有事件。示例使用可变列表,只用于这份串行演示,若扩展到并行运行应检查线程安全。

跑一次普通调用,收集到 13 条事件、9 种类型:

[collector] AgentStartingEvent
[collector] GraphStrategyStartingEvent
[collector] NodeExecutionStartingEvent
[collector] NodeExecutionCompletedEvent
[collector] NodeExecutionStartingEvent
[collector] LLMCallStartingEvent
[collector] LLMCallCompletedEvent
[collector] NodeExecutionCompletedEvent
[collector] NodeExecutionStartingEvent
[collector] NodeExecutionCompletedEvent
[collector] StrategyCompletedEvent
[collector] AgentCompletedEvent
[collector] AgentClosingEvent
[collector] closed, total=13

这段序列值得读一遍:一次"start → LLM → finish"的图运行,从 AgentStartingEvent 到 AgentClosingEvent,事件流能反映这次运行的主要生命周期,适合监控与排障;但它不自动成为完整审计或可重放日志。过滤、截断、序列化及外部工具副作用都会影响完整性,任务恢复和补偿仍要使用第六篇讲的 Persistence 等机制。

三、Tracing

3.1 架构

Tracing 将管道回调转换为事件消息,再交给注册的 processor。这里有两种不同过滤:FeatureConfig.setEventFilter 决定 feature 接受哪些生命周期上下文;每个 processor 的 setMessageFilter 则决定它处理哪些 FeatureMessage。两者作用层不同,不要混为一个全局过滤器。三个常用 writer 都是 processor 的实现:

Writer 输出去向 说明
TraceFeatureMessageLogWriter 日志 走 slf4j/kotlin-logging
TraceFeatureMessageFileWriter 文件 本例显式提供 targetPath 和 sinkOpener;也有 create 工厂
TraceFeatureMessageRemoteWriter 远端 SSE 启动一个轻量服务,通过 Server-Sent Events 发送

还有一个容易忽略的行为:不注册任何 processor 时,Tracing 只打一条警告,事件照常拦截但不输出到任何地方。装了 Tracing 却看不到输出时,先检查是不是忘了加 processor。

3.2 文件落盘实测

下面是完整的 TraceFileDemo.kt,与附录执行器一起运行。程序关闭 agent 使 writer 完成写入后,再读取 trace 文件:

import ai.koog.agents.core.agent.AIAgent
import ai.koog.agents.core.agent.config.AIAgentConfig
import ai.koog.agents.core.dsl.builder.*
import ai.koog.agents.features.tracing.feature.Tracing
import ai.koog.agents.features.tracing.writer.TraceFeatureMessageFileWriter
import ai.koog.prompt.Prompt
import kotlinx.io.asSink
import kotlinx.io.buffered
import java.nio.file.Files
import java.nio.file.Path
import kotlin.io.path.readText
import kotlinx.coroutines.runBlocking

fun main() = runBlocking {
    val executor = OfflineExecutor()
    val traceFile: Path = Files.createTempFile("koog8-trace", ".txt")
    val graph = strategy<String, String>("trace-file-demo") {
        val talk by node<String, String> { input ->
            llm.writeSession {
                appendPrompt { user(input) }
                requestLLM().toString()
            }
        }
        nodeStart then talk then nodeFinish
    }
    val agent = AIAgent(
        promptExecutor = executor,
        agentConfig = AIAgentConfig(prompt = Prompt.Empty, model = OfflineModel, maxAgentIterations = 10),
        strategy = graph,
    ) {
        install(Tracing) {
            addMessageProcessor(
                TraceFeatureMessageFileWriter(
                    targetPath = traceFile,
                    sinkOpener = { path -> Files.newOutputStream(path).asSink().buffered() },
                )
            )
        }
    }
    try {
        agent.run("讲个故事")
        agent.close()
        val content = traceFile.readText()
        check("AgentStartingEvent" in content)
        content.lineSequence().take(6).forEach { println(it) }
    } finally { executor.close() }
    Unit
}

两个类型细节:本例把 writer 的路径泛型选择为 java.nio.file.Path,并非 writer 只能接受这个路径类型;sinkOpener 返回的是 kotlinx-io 的 Sink,所以有 asSink().buffered() 这串转换。跑完后文件内容开头:

AgentStartingEvent (agent id: 3d43065d-…, run id: ebeb1419-…)
GraphStrategyStartingEvent (run id: ebeb1419-…, strategy: trace-file-demo)
NodeExecutionStartingEvent (run id: ebeb1419-…, node: __start__, input: "讲个故事")
NodeExecutionCompletedEvent (run id: ebeb1419-…, node: __start__, input: "讲个故事", output: "讲个故事")
NodeExecutionStartingEvent (run id: ebeb1419-…, node: talk, input: "讲个故事")
LLMCallStartingEvent (run id: ebeb1419-…, prompt: id: default, messages: [{role: User, parts: type: Text, text: 讲个故事}], temperature: null, model: Ollama, tools: [])

示例 writer 把事件格式化为文本,多数运行事件包含 run id,但 AgentClosingEvent 没有。它可以辅助归档与排障;生产审计还需设计脱敏、访问控制、保留期限和完整性保障,不能仅靠这份文本满足。生产上文件会很大,官方建议配合 message filter(比如只要工具事件)和文件轮转使用。

TraceFeatureMessageRemoteWriter(SSE 远端)本文未验证,接入前请单独测试。

四、OpenTelemetry

4.1 概念映射

Tracing 输出的是 Koog 自己的事件文本;OpenTelemetry feature 做的事是把这些事件翻译成 OTel span,交给任意 OTel 后端。一次图运行产生的 span 层级:

create_agent
└── invoke_agent
    └── strategy <name>
        └── node …(每个节点一个)
            └── chat <model>(LLM 调用)

属性遵循 OTel 的 GenAI 语义约定(gen_ai.* 前缀):gen_ai.request.model、gen_ai.response.finish_reasons、gen_ai.usage.input_tokens 等,Koog 自己的补充属性(如 koog.node.id)放在 koog. 命名空间下。service.name 默认 ai.koog,service.version 默认当前 Koog 版本,可用 setServiceInfo 覆盖。

4.2 安装、导出与生命周期

依赖上,feature 本体是 agents-features-opentelemetry:1.3.0;想把 span 打到本地日志,还要 OTel Java SDK 的 io.opentelemetry:opentelemetry-exporter-logging(LoggingSpanExporter 在这个包里,不在 sdk 包——实测确认过)。

下面是完整的 OpenTelemetryDemo.kt,与附录执行器一起运行;采用同步 processor 便于观察导出,不需要启动 collector:

import ai.koog.agents.core.agent.AIAgent
import ai.koog.agents.core.agent.config.AIAgentConfig
import ai.koog.agents.core.dsl.builder.*
import ai.koog.agents.features.opentelemetry.feature.OpenTelemetry
import ai.koog.prompt.Prompt
import io.opentelemetry.exporter.logging.LoggingSpanExporter
import io.opentelemetry.kotlin.ExperimentalApi
import io.opentelemetry.kotlin.tracing.export.simpleSpanProcessor
import io.opentelemetry.kotlin.tracing.export.toOtelKotlinSpanExporter
import kotlinx.coroutines.runBlocking

@OptIn(ExperimentalApi::class)
fun main() = runBlocking {
    val executor = OfflineExecutor()
    val graph = strategy<String, String>("otel-demo") {
        val talk by node<String, String> { input ->
            llm.writeSession {
                appendPrompt { user(input) }
                requestLLM().toString()
            }
        }
        nodeStart then talk then nodeFinish
    }
    val agent = AIAgent(
        promptExecutor = executor,
        agentConfig = AIAgentConfig(prompt = Prompt.Empty, model = OfflineModel, maxAgentIterations = 10),
        strategy = graph,
    ) {
        install(OpenTelemetry) {
            setServiceInfo("koog8-check", "1.0.0")
            setVerbose(true)
            addSpanProcessor { simpleSpanProcessor(LoggingSpanExporter.create().toOtelKotlinSpanExporter()) }
            setShutdownOnAgentClose(true)
        }
    }
    try {
        agent.run("讲个故事")
        agent.close()
    } finally { executor.close() }
    Unit
}

1.3.0 内部使用 Kotlin OTel SDK,Java exporter 通过 toOtelKotlinSpanExporter() 桥接。addSpanExporter(...) 默认使用批处理路径;上面的 simpleSpanProcessor 则在 span 结束时导出,方便短程序观察。不能由一次短程序没看到日志,就断言批处理必然不工作,也不能因为生产进程长活就保证不会丢 span。使用批处理时应检查 flush/shutdown、导出结果、队列和进程退出时机。

本次还核对了实际解析到的 Kotlin OTel SDK 0.3.0:其 batch processor 的 shutdown 路径先关闭 exporter,再取消后台处理协程,没有先排空待导出队列。本地立即关闭实验中,batch 路径的 exporter 实际导出 0 条,simple 路径导出 7 条。因此这里不仅是“等待时间太短”的问题,结束时的尾批也可能丢失。这是该依赖版本的具体限制,不应推广到所有 OTel 实现。若选择批处理,应在 SDK shutdown 前有序完成 span 并检查显式刷新结果;本文不把一次 forceFlush 成功等同于整个关闭过程可靠。

示例将 OTel 的关闭与 agent 关闭绑定;若多个 agent 共享外部 telemetry 实例,需另行设计其生命周期。

上面的 Kotlin OTel 桥接与 processor API 标有 ExperimentalApi,示例通过显式 @OptIn 使用它们;Koog 模块为正式版,不等于其所有底层 API 都没有实验性标记。

LoggingSpanExporter 使用 java.util.logging,本例采用的 1.61.0 在 INFO 级别输出 span,不要求把全局 root logger 改为 FINE。如果已有应用日志配置屏蔽了 INFO,再检查具体 logger 与 handler 的级别。

本例开启 setVerbose(true),日志可能包含 prompt、回答和节点数据,仅用于本地观察。生产中应按数据敏感度关闭详细内容或做脱敏,并限制日志访问和保留期限。verbose=false 只隐藏该 feature 标为敏感的属性,不保证其他自定义日志、属性或异常文本也已脱敏。

4.3 实测输出

跑一次含一个业务节点的图,加上框架的 start/finish 节点,本例导出 7 个 span。挑两条看属性(JUL 格式):

'chat offline-model' : … CLIENT [tracer: koog8-check:1.0.0] {gen_ai.conversation.id="4079707a-…",
  gen_ai.input.messages="[{…,\"content\":\"讲个故事\"}]", gen_ai.operation.name="chat",
  gen_ai.output.messages="[{…,\"content\":\"离线回复:从前有一座山。\"}]",
  gen_ai.request.model="offline-model", gen_ai.response.finish_reasons="[stop]",
  gen_ai.usage.input_tokens="0", gen_ai.usage.output_tokens="0", koog.event.id="92544926-…"}

'node talk' : … INTERNAL [tracer: koog8-check:1.0.0] {gen_ai.conversation.id="4079707a-…",
  koog.node.id="talk", koog.node.input=""讲个故事"", koog.node.output=""Assistant(…)"}

这次 chat span 包含 GenAI 相关字段;其中 token 用量为 0 来自没有真实用量信息的离线替身,不是一次真实模型调用的计费测量。详细输入输出还受 verbose 配置影响,不能要求任意模型与请求都具有完全相同的属性。对接 Jaeger 或其他 collector 的部署步骤(docker-compose 起 collector、配 OTLP exporter)本文没有实测,官方文档有现成配置可参考;本节验证到"span 正确生成并携带语义属性"为止。

五、内容审核 Moderation

5.1 两个入口

审核可以脱离 agent 独立调用,也可以接入会话或 agent 的请求流程;安装日志、Tracing 或 OTel 并不会自动拒绝有害输入。这里先展示两个显式调用层次:

import ai.koog.prompt.dsl.prompt
import ai.koog.prompt.executor.clients.openai.OpenAILLMClient
import ai.koog.prompt.executor.clients.openai.OpenAIModels
import ai.koog.prompt.executor.llms.MultiLLMPromptExecutor
import ai.koog.prompt.llm.LLMProvider

// 片段:写在挂起函数或 runBlocking 中。apiKey 填真实密钥。
val openAIClient = OpenAILLMClient(apiKey)
val harmfulPrompt = prompt("harmful-prompt") {
    user("I want to build a bomb")
}

// 入口一:直接在 LLMClient 上调用(OpenAI 的 Omni 审核模型)
val result = openAIClient.moderate(harmfulPrompt, OpenAIModels.Moderation.Omni)

// 入口二:在 PromptExecutor 上调用,按模型的 provider 路由到对应 client
val executor = MultiLLMPromptExecutor(
    LLMProvider.OpenAI to OpenAILLMClient(apiKey)
)
val result2 = executor.moderate(harmfulPrompt, OpenAIModels.Moderation.Omni)

两个入口的签名一致:moderate(prompt: Prompt, model: LLModel): ModerationResult。会话层还有第三个入口 requestModeration(moderatingModel)——第七篇提取写会话 API 时它就出现过,和 requestLLM 并排。

5.2 ModerationResult

下面是框架返回类型的结构节选,不需要在自己的项目里重新定义;类别及结果类型的其他定义已省略:

@Serializable
public data class ModerationResult(
    val isHarmful: Boolean,
    val categories: Map<ModerationCategory, ModerationCategoryResult>
) {
    public val violatedCategories: List<ModerationCategory> =
        categories.filter { it.value.detected }.keys.toList()
    // …
}

isHarmful 是总体判断,categories 按有害类别(暴力、仇恨等)给出明细,violatedCategories 是便捷属性:筛出所有命中项。典型用法就是官方示例的模式——if (result.isHarmful) 拒绝或转人工 else 继续处理。

5.3 provider 现实:本节只有编译验证

审核依赖客户端的审核实现与相应模型,不一定有单独的 HTTP 审核端点:OpenAI 使用专用 Moderation API,Ollama 则调用审核模型并解析其 safe/unsafe 文本。1.3.0 的以下组合可供选择,本篇没有调用其在线服务:

  • OpenAI:OpenAIModels.Moderation.Omni 走 OpenAI Moderation API,需要有效凭据;OpenAI 客户端不要求 AWS Bedrock 的 Guardrails 配置,不能混淆两种服务。
  • Ollama:OllamaModels.Meta.LLAMA_GUARD_3,用 Llama Guard 3 模型本地审核,需要本机装 Ollama 并拉取模型。
  • DeepSeek:没有审核端点。本文系列的示例工程用的是 DeepSeek,审核一节因此只有编译验证,没有真实调用——上面的调用片段在 1.3.0 下编译通过;它被放在验证程序从不调用的挂起函数内,未验证在线审核返回值。

如果你的服务也用 DeepSeek,这个限制是真实的:要么接 OpenAI/Ollama 做审核通道,要么自己实现内容过滤。选择取决于业务,同一个多 provider executor 可以让聊天和审核使用不同模型,但要给它注册对应客户端;调用方还需决定审核失败、超时和命中后的拒绝策略。本文只核对 1.3.0 的接口,不对未来版本的 API 稳定性作保证。

六、序列化

6.1 一层薄抽象

Koog 在两处需要 JSON 序列化:工具的参数与结果(第 4 篇)、Persistence 的节点输入输出(第 6 篇)。这两处都走同一个抽象——serialization-core 模块的 JSONSerializer 接口,四个抽象核心方法(encode/decode 各自到 String 和 Koog 的 JSONElement,均带 TypeToken 参数),另有两个 JSONElement 与字符串互转的默认方法。JSONElement 是 Koog 的抽象,不是 kotlinx.serialization 的 JsonElement。设计动机写在官方文档里:这层是 library-agnostic 的,换序列化库不动任何工具和 agent 代码。

默认实现是 KotlinxSerializer(kotlinx-serialization)。JVM 上可以换成 JacksonSerializer(jackson-databind),入口在 AIAgentConfig:

val config = AIAgentConfig(
    prompt = Prompt.Empty,
    model = model,
    maxAgentIterations = 10,
    serializer = JacksonSerializer(),   // 默认是 KotlinxSerializer()
)

6.2 切换实测

下面的完整 SerializationDemo.kt 对同一个对象分别编码和解码,检查两个实现各自的 round-trip,不调用 agent 或模型:

import ai.koog.serialization.jackson.JacksonSerializer
import ai.koog.serialization.kotlinx.KotlinxSerializer
import ai.koog.serialization.typeToken
import kotlinx.serialization.Serializable

@Serializable
data class Sample(var question: String = "", var n: Int = 0)

fun main() {
    val kotlinx = KotlinxSerializer()
    val jackson = JacksonSerializer()
    val sample = Sample(question = "山", n = 3)
    val kJson = kotlinx.encodeToString(sample, typeToken<Sample>())
    val jJson = jackson.encodeToString(sample, typeToken<Sample>())
    println("kotlinx.encodeToString = $kJson")
    println("jackson.encodeToString = $jJson")
    check(kotlinx.decodeFromString<Sample>(kJson, typeToken<Sample>()) == sample)
    check(jackson.decodeFromString<Sample>(jJson, typeToken<Sample>()) == sample)
    println("PASS round-trip")
}

这份样本的编码结果一致,两次解码断言通过;这里不据此断言任意对象的 JSON 字段顺序相同,也没有验证所有工具或 Persistence 组合:

kotlinx.encodeToString = {"question":"山","n":3}
jackson.encodeToString = {"question":"山","n":3}
PASS round-trip

实测出两个依赖与行为细节,官方文档都没写:

  • serialization-jackson 不是 koog-agents 的传递依赖。使用 Jackson 时,本例显式添加 ai.koog:serialization-jackson:1.3.0。
  • 默认 Jackson 配置不自动理解所有 Kotlin 构造器。本例用全默认参数和可写属性,使 Jackson 可以通过无参构造再设置属性;全默认参数本身就能生成无参构造,不必额外加 @JvmOverloads。对没有默认值、没有显式 creator 的普通 Kotlin data class,应给 ObjectMapper 注册匹配版本的 Kotlin 模块,或显式配置 @JsonCreator/@JsonProperty 等;仅将依赖放入 classpath 不等于已经注册模块。能否编解码还取决于类型、注解和 mapper 配置,不能把所有失败都归结为没有无参构造。

结论和官方文档一致:默认场景留 KotlinxSerializer,需要 Jackson 生态(比如已有 Spring 的 ObjectMapper 配置)时再切,切换成本就是一行配置加上面的注意点。

七、测试

7.1 agents-test 模块

前面的替身都是为文章验证临时写的;给业务 agent 写测试,用官方的 ai.koog:agents-test:1.3.0(本次已成功解析和运行)。它提供 mock PromptExecutor、工具行为替换及图测试 API。Kotlin/JVM 测试还需 testImplementation(kotlin("test")),并使用匹配的测试运行器;本文工程通过 tasks.test { useJUnitPlatform() } 使用 JUnit Platform。只解析到 agents-test 不等于已经有可执行的测试引擎。

先说一个好消息:本篇到这里的所有机制(feature、事件、Tracing、OTel)验证时用的都是空客户端替身,而 agents-test 提供的是官方维护、语义更完整的同类设施——业务测试通常可以优先复用它;需要验证特殊传输行为或自定义执行器边界时,手写替身仍有价值。

7.2 Mock 执行器

import ai.koog.agents.testing.tools.getMockExecutor
import ai.koog.agents.testing.tools.mockLLMAnswer
import ai.koog.utils.time.KoogClock
import kotlin.time.Instant

val fixedClock = KoogClock { Instant.fromEpochSeconds(1_700_000_000) }
val mockExecutor = getMockExecutor(clock = fixedClock) {
    // 按请求内容匹配:包含 "hello" 时返回固定回答
    mockLLMAnswer("你好,我是 mock 回答!") onRequestContains "hello"
    // 兜底:所有未匹配的请求
    mockLLMAnswer("这是默认兜底回答。").asDefaultResponse
}

mockLLMAnswer 的匹配条件有 onRequestContains / onRequestEquals / onCondition 三种,asDefaultResponse 标记兜底。工具侧对应 mockTool(Tool) alwaysReturns value、returns value onArguments args(精确参数)和 returns value onArgumentsMatching { args -> … }(谓词匹配) 等组合。这里传入的 clock 是固定的 KoogClock——原因见 7.4。

mock 执行器可以直接当 promptExecutor 传给 AIAgent,端到端跑通整个策略。下面是局部片段,完整的模型定义、策略和测试类见 7.3:

@Test
fun `mock 执行器驱动 agent 完整运行`() = runBlocking {
    val agent = AIAgent(promptExecutor = mockExecutor, llmModel = mockModel, strategy = strategy)
    assertEquals("你好,我是 mock 回答!", agent.run("hello koog"))
}

7.3 结构与行为断言

withTesting { graph { ... } } 开启图测试配置,testGraph(name) { ... } 则是结构检查的便捷入口。仅调用 withTesting() 不会自动生成图断言;还需要配置检查,并由 agent.run(...) 触发执行。

下面直接给出完整的 src/test/kotlin/koog/testing/AgentsTestDemoTest.kt。它包含两个端到端回答测试、一个节点输出和出边测试、一个结构可达性测试,合计四个。行为测试显式设置节点执行需要的上下文,没有省略决定能否运行的配置。

package koog.testing

import ai.koog.agents.core.agent.AIAgent
import ai.koog.agents.core.agent.config.AIAgentConfig
import ai.koog.agents.core.agent.context.AIAgentLLMContext
import ai.koog.agents.core.agent.entity.AIAgentStateManager
import ai.koog.agents.core.agent.entity.AIAgentStorage
import ai.koog.agents.core.dsl.builder.strategy
import ai.koog.agents.core.dsl.extension.nodeLLMRequest
import ai.koog.agents.core.tools.ToolRegistry
import ai.koog.agents.testing.agent.agentExecutionInfo
import ai.koog.agents.testing.feature.assistantMessage
import ai.koog.agents.testing.feature.graph
import ai.koog.agents.testing.feature.testGraph
import ai.koog.agents.testing.feature.withTesting
import ai.koog.agents.testing.tools.getMockExecutor
import ai.koog.agents.testing.tools.mockLLMAnswer
import ai.koog.agents.testing.tools.MockEnvironment
import ai.koog.prompt.llm.LLMCapability
import ai.koog.prompt.llm.LLMProvider
import ai.koog.prompt.llm.LLModel
import ai.koog.prompt.message.Message
import ai.koog.prompt.Prompt
import ai.koog.serialization.kotlinx.KotlinxSerializer
import ai.koog.utils.time.KoogClock
import kotlin.test.Test
import kotlin.test.assertEquals
import kotlin.time.Instant
import kotlinx.coroutines.runBlocking

/**
 * 第 8 篇(测试章节)配套演示:用 ai.koog:agents-test 的 mock 执行器做离线测试。
 * 不调用真实模型、不读任何 API Key。
 */
class AgentsTestDemoTest {

    // 固定时钟:让 mock 响应与断言构造的 Message.Assistant 时间戳一致,才能用 assertEquals 比较
    private val fixedClock = KoogClock { Instant.fromEpochSeconds(1_700_000_000) }

    private val mockModel = LLModel(
        provider = LLMProvider.Ollama,
        id = "mock-echo",
        capabilities = listOf(LLMCapability.Completion),
        contextLength = 8_000,
    )

    // 最小图策略:start -> askLLM(nodeLLMRequest) -> finish
    private fun echoStrategy() = strategy<String, String>("mock-echo-strategy") {
        val askLLM by nodeLLMRequest()
        edge(nodeStart forwardTo askLLM)
        edge(askLLM forwardTo nodeFinish transformed { it.textContent() })
    }

    private fun echoExecutor(): ai.koog.prompt.executor.model.PromptExecutor =
        getMockExecutor(clock = fixedClock) {
            mockLLMAnswer("你好,我是 mock 回答!") onRequestContains "hello"
            mockLLMAnswer("这是默认兜底回答。").asDefaultResponse
        }

    @Test
    fun `mock 执行器驱动 agent 完整运行`() = runBlocking {
        val agent = AIAgent(
            promptExecutor = echoExecutor(),
            llmModel = mockModel,
            strategy = echoStrategy(),
        )
        val result = agent.run("hello koog")
        assertEquals("你好,我是 mock 回答!", result)
    }

    @Test
    fun `mock 执行器按请求内容匹配不同回答`() = runBlocking {
        val agent = AIAgent(
            promptExecutor = echoExecutor(),
            llmModel = mockModel,
            strategy = echoStrategy(),
        )
        val result = agent.run("完全无关的输入")
        assertEquals("这是默认兜底回答。", result)
    }

    @Test
    fun `withTesting 断言图结构与节点输出`() = runBlocking {
        val mockExecutor = echoExecutor()
        val agentConfig = AIAgentConfig(prompt = Prompt.Empty, model = mockModel, maxAgentIterations = 10)
        val agent = AIAgent(
            promptExecutor = mockExecutor,
            llmModel = mockModel,
            strategy = echoStrategy(),
        ) {
            withTesting {
                clock = fixedClock
                graph {
                    verifyStrategy<String, String>("mock-echo-strategy") {
                        assertNodes {
                            config = agentConfig
                            stateManager = AIAgentStateManager()
                            storage = AIAgentStorage(KotlinxSerializer())
                            executionInfo = agentExecutionInfo("mock-echo-strategy")
                            llm = AIAgentLLMContext(
                                tools = emptyList(),
                                toolRegistry = ToolRegistry.EMPTY,
                                prompt = Prompt.Empty,
                                model = mockModel,
                                responseProcessor = null,
                                promptExecutor = mockExecutor,
                                environment = MockEnvironment(ToolRegistry.EMPTY, mockExecutor, KotlinxSerializer()),
                                config = agentConfig,
                                clock = fixedClock,
                            )
                            assertNodeByName<String, Message.Assistant>("askLLM")
                                .withInput("hello koog")
                                .outputs(assistantMessage("你好,我是 mock 回答!"))
                        }
                        assertEdges {
                            config = agentConfig
                            stateManager = AIAgentStateManager()
                            storage = AIAgentStorage(KotlinxSerializer())
                            executionInfo = agentExecutionInfo("mock-echo-strategy")
                            assertNodeByName<String, Message.Assistant>("askLLM")
                                .withOutput(assistantMessage("你好,我是 mock 回答!"))
                                .goesTo(finishNode())
                        }
                    }
                }
            }
        }
        // 断言在 strategyStarting 阶段执行,run() 触发整个校验流程
        agent.run("hello koog")
        Unit
    }

    @Test
    fun `testGraph 便捷入口断言结构可达性`() = runBlocking {
        val agent = AIAgent(
            promptExecutor = echoExecutor(),
            llmModel = mockModel,
            strategy = echoStrategy(),
        ) {
            testGraph<String, String>("mock-echo-strategy") {
                val start = startNode()
                val finish = finishNode()
                val askLLM = assertNodeByName<String, Message.Assistant>("askLLM")
                assertReachable(start, askLLM)
                assertReachable(askLLM, finish)
            }
        }
        agent.run("hello koog")
        Unit
    }
}

执行 ./gradlew --offline cleanTest test 后,JUnit XML 记录为 tests="4" skipped="0" failures="0" errors="0"。这是本次实际执行的测试文件;不同项目首次运行前仍需解析好依赖,离线模式不会下载它们。

7.4 官网测试文档与 1.3.0 的出入(重点)

测试页是本文发现的文档漂移最大的一节,以下以 1.3.0 源码为准:

  1. getMockExecutor 没有 toolRegistry / eventHandler 参数(1.3.0 签名是 getMockExecutor(serializer, clock, tokenizer, handleLastAssistantMessage) { … }),照文档抄编译不过。
  2. AIAgent 工厂没有 eventHandler 参数——事件处理是独立 feature,走 handleEvents 或 install(EventHandler)。
  3. ToolCalls / ReceivedToolResults 在 1.3.0 中存在,且是列表包装 data class,不是 typealias,位于 ai.koog.agents.core.dsl.extension。前者包装 List<MessagePart.Tool.Call>,后者包装 List<ReceivedToolResult>;nodeExecuteTools 的输入输出就是这两个包装类型。不能把它们替换成单个元素或裸 List。
  4. nodeExecuteTool / nodeLLMSendToolResult(单数)不存在,1.3.0 是 nodeExecuteTools / nodeLLMSendToolResults / nodeExecuteSingleTool;nodeLLMRequest(allowToolCalls = …) 参数已删。
  5. 一个文档完全没提的隐坑:行为断言执行节点或变换时,需要提供该路径实际访问的上下文。上面 askLLM 的节点断言设置了 config、stateManager、storage、executionInfo、llm;省略必要项会触发 NotImplementedError。但不能推导成所有 assertEdges 都要求 llm:本例出边断言不访问 LLM,因此只配置所需的其余字段,也能通过。storage 的构造是 AIAgentStorage(KotlinxSerializer())。
  6. assertEquals 比较两个 Message.Assistant 时,metaInfo 里的时间戳参与相等判断——若比较完整消息对象,建议让 mock 执行器与断言使用返回相同时间值的固定时钟。不要求同一个时钟对象,两个实例只要返回相同时间也可以;若只关心文本,也可以比较提取后的文本来避免时间戳参与。这就是 7.2 代码里 fixedClock 的由来。

第 5、6 条是复现本次完整消息断言所需的上下文,不能从前面的简短 DSL 形状推断这些配置可以省略。写测试卡在断言失败或 NotImplementedError 时,先回来查这张单子。

后记

回顾本篇,feature、事件处理和追踪共享生命周期扩展机制,审核、序列化与测试则补充了不同的工程能力:

能力 底座用法 一句话记住
自定义 feature 拦截器 三套管道三个接口,公共拦截器抽成 registerCommon
事件与 EventHandler 事件对象 handleEvents 最省事;事件流是 agent 执行史
Tracing 事件转发 拦截 → 过滤 → processor;没有 processor 就没有输出
OpenTelemetry span 翻译 示例用同步导出;批处理需正确处理刷新与关闭
内容审核 独立调用能力 需要客户端支持审核实现与模型;DeepSeek 客户端不支持
序列化 薄抽象 AIAgentConfig 换实现;Jackson 记得处理 Kotlin 构造器
测试 mock + 断言 配齐测试上下文;完整消息比较时控制时间戳

使用文档示例时,先核对项目依赖版本,再判断差异来自版本、文档错误还是上下文省略。本文说明的是 1.3.0 源码与本次执行结果,不能把所有不一致都归结为“新版 API”,也不能假定升级后差异一定消失。

下一篇进入知识增强:Embeddings、文档存储与 RAG,以及 LongTermMemory 的完整讲法。

附录:离线替身

前面的日志、事件与追踪演示共用这份执行器替身;纯序列化实验不需要它,审核片段只编译不执行,测试章节使用官方 mock 执行器。它不注册任何厂商客户端,模型也是自定义的——顺带说明一个 1.3.0 的事实:DeepSeekModels 这类模型目录在正式版 koog-agents 里不存在(在 additions beta 里),不用 additions 时自定义 LLModel 即可。

import ai.koog.prompt.executor.llms.MultiLLMPromptExecutor
import ai.koog.prompt.executor.model.PromptExecutorOperation
import ai.koog.prompt.executor.model.ResolvedModel
import ai.koog.prompt.llm.LLMCapability
import ai.koog.prompt.llm.LLMProvider
import ai.koog.prompt.llm.OllamaLLMProvider
import ai.koog.prompt.llm.LLModel
import ai.koog.prompt.message.Message
import ai.koog.prompt.message.MessagePart
import ai.koog.prompt.message.ResponseMetaInfo
import ai.koog.prompt.streaming.StreamFrame
import kotlinx.coroutines.flow.Flow
import kotlinx.coroutines.flow.flowOf
import kotlin.time.Clock

val OfflineModel = LLModel(
    provider = OllamaLLMProvider,
    id = "offline-model",
    capabilities = listOf(LLMCapability.Completion, LLMCapability.Tools, LLMCapability.Temperature),
)

class OfflineExecutor : MultiLLMPromptExecutor(llmClients = emptyMap()) {
    var calls = 0

    override suspend fun resolveModel(model: LLModel, promptExecutorOperation: PromptExecutorOperation) =
        ResolvedModel(effectiveModel = model)

    // 必须覆盖 ResolvedModel 版 execute:LLModel 版会走 resolveModel → ResolvedModel 版 → clientFor,
    // 只覆盖 LLModel 版会被父类绕过(报 "No client found for provider")。
    override suspend fun execute(
        prompt: ai.koog.prompt.Prompt,
        model: ResolvedModel,
        tools: List<ai.koog.agents.core.tools.ToolDescriptor>,
    ): Message.Assistant {
        calls++
        return Message.Assistant(
            parts = listOf(MessagePart.Text("离线回复:从前有一座山。")),
            metaInfo = ResponseMetaInfo(timestamp = Clock.System.now()),
        )
    }

    override fun executeStreaming(
        prompt: ai.koog.prompt.Prompt,
        resolvedModel: ResolvedModel,
        tools: List<ai.koog.agents.core.tools.ToolDescriptor>,
    ): Flow<StreamFrame> = flowOf(
        StreamFrame.TextDelta("从前有"),
        StreamFrame.TextDelta("一座山。"),
        StreamFrame.TextComplete("从前有一座山。"),
        StreamFrame.End(finishReason = "Stop", metaInfo = ResponseMetaInfo(timestamp = Clock.System.now())),
    )
}

第七章已经列出完整的测试代码。将测试类保存为 src/test/kotlin/koog/testing/AgentsTestDemoTest.kt,配齐 7.1 的测试依赖后执行 ./gradlew test 即可;不需要另外寻找配套工程中的实现。

参考资料

posted @ 2026-10-20 20:51  SharpCJ  阅读(22)  评论(0)    收藏  举报