Koog(10) —— 生态集成:MCP、后端服务与 A2A
前言
前九篇围绕 Agent 内部展开:模型怎么调用,工具怎么执行,策略如何编排,状态、追踪和知识检索放在哪里。这一篇走到应用边界:工具在另一个进程里怎么办,前端怎样调用 Agent,独立部署的两个 Agent 又怎样交换任务?
这三个问题分别对应 MCP、后端集成和 A2A。先从最熟悉的工具开始,再把 Agent 提供给业务系统,最后讨论跨服务协作。
本文继续固定 Koog 核心 1.3.0。以下集成使用预览模块,不能把官网的版本占位符全部替换成正式版:
| 内容 | 本文版本 |
|---|---|
koog-agents 核心 |
1.3.0 |
| MCP、Ktor、Spring Boot 与 A2A 集成 | 1.3.0-beta |
| MCP Kotlin SDK | 0.11.1 |
| Ktor | 3.3.3 |
| Spring Boot BOM | 3.5.14 |
示例采用 JDK 21。MCP 和 A2A 例子使用 Kotlin 2.4.10,后端例子另以 Kotlin 2.3.20 验证;这不是要求一个项目混用两个 Kotlin 插件版本。
本篇验证的重点是真实协议与框架接入:MCP 使用两个本地 JVM 进程,Ktor 使用真实 HTTP 请求,A2A 使用真实 HTTP JSON-RPC。业务逻辑故意保持确定性,不调用模型。真实 DeepSeek 接入代码另外编译,API Key 统一用 "xxxxxxx";没有将协议成功说成真实模型调用成功。
一、MCP:从本地工具到外部工具
1.1 MCP 与 Koog Tool 是什么关系
第四篇的工具一般由 Kotlin 函数或 Tool 对象实现,Agent 在当前应用里执行。MCP 把工具提供方与使用方分开:服务端发布工具描述和调用入口,客户端发现并调用,Koog 再把这些描述适配到自己的 ToolRegistry。
链路是:
Koog Agent → ToolRegistry → MCP Client → MCP Server → 工具实现
MCP 不替代 Agent 策略,也不等于模型自动有了外部访问能力。连接哪些服务器、允许哪些工具、给哪些凭据,仍由应用决定。协议还包含其他能力,但本文核验的是工具接入,不能据此宣称 prompts/resources 也自动进入了 Koog。
1.2 传输方式与依赖
本文固定的 MCP beta 模块支持三种入口:
| 传输 | 适合的接入方式 | 本篇验证 |
|---|---|---|
| stdio | 应用启动本地子进程,以标准输入输出通信 | 实际运行 |
| SSE | 连接使用旧式 HTTP+SSE 传输的服务 | API 编译与源码核查 |
| Streamable HTTP | 连接实现该传输的 HTTP 服务 | API 编译与源码核查 |
SSE 和 Streamable HTTP 不是同一个入口。这个版本已经有 streamableHttp,但官网 MCP 页面主要展示 stdio/SSE,不能只凭页面没写就断定不支持。
下面两个 Kotlin 文件构成完整的本地例子。服务端额外使用 MCP SDK server;仅连接已有 MCP 服务时,不需要为了客户端添加 server SDK。build.gradle.kts 如下:
plugins {
kotlin("jvm") version "2.4.10"
application
}
repositories { mavenCentral() }
dependencies {
implementation("ai.koog:koog-agents:1.3.0")
implementation("ai.koog:agents-mcp:1.3.0-beta")
implementation("ai.koog:prompt-executor-deepseek-client:1.3.0-beta")
implementation("io.modelcontextprotocol:kotlin-sdk-server:0.11.1")
}
kotlin { jvmToolchain(21) }
application { mainClass.set("mcpdemo.ClientMainKt") }
tasks.register<JavaExec>("stdioDemo") {
classpath = sourceSets.main.get().runtimeClasspath
mainClass.set("mcpdemo.ClientMainKt")
}
首次构建需要解析依赖;缓存齐全后才适合加 --offline。settings.gradle.kts 可以只设置项目名。
1.3 服务端:发布一个 add 工具
保存为 src/main/kotlin/mcpdemo/ServerMain.kt。这个文件由客户端启动为独立进程,不需要另外开终端。
stdio 的 stdout 属于协议,不能往里面随意打印调试日志。这里把协议追踪写入 stderr,由父进程保存;调试真实业务时也应避免把凭据和敏感参数写入追踪。
schema 用于描述参数,handler 仍显式检查。这个简单工具返回 Int 相加结果,不是任意精度计算器:
package mcpdemo
import io.modelcontextprotocol.kotlin.sdk.server.Server
import io.modelcontextprotocol.kotlin.sdk.server.ServerOptions
import io.modelcontextprotocol.kotlin.sdk.server.StdioServerTransport
import io.modelcontextprotocol.kotlin.sdk.shared.Transport
import io.modelcontextprotocol.kotlin.sdk.shared.TransportSendOptions
import io.modelcontextprotocol.kotlin.sdk.types.*
import kotlinx.coroutines.CompletableDeferred
import kotlinx.coroutines.runBlocking
import kotlinx.io.asSink
import kotlinx.io.asSource
import kotlinx.io.buffered
import kotlinx.serialization.json.*
// Trace only on stderr: stdout belongs exclusively to the MCP protocol.
private class TracedTransport(private val delegate: Transport) : Transport by delegate {
override suspend fun send(message: JSONRPCMessage, options: TransportSendOptions?) {
System.err.println("S>C " + McpJson.encodeToString(JSONRPCMessage.serializer(), message))
delegate.send(message, options)
}
override fun onMessage(block: suspend (JSONRPCMessage) -> Unit) {
delegate.onMessage { message ->
System.err.println("C>S " + McpJson.encodeToString(JSONRPCMessage.serializer(), message))
block(message)
}
}
}
fun main() = runBlocking {
val server = Server(
Implementation("local-kotlin-tools", "1.0.0"),
ServerOptions(ServerCapabilities(tools = ServerCapabilities.Tools(listChanged = false)))
)
server.addTool(
name = "add",
description = "Add two integers locally.",
inputSchema = ToolSchema(
properties = buildJsonObject {
put("a", buildJsonObject { put("type", "integer") })
put("b", buildJsonObject { put("type", "integer") })
},
required = listOf("a", "b")
)
) { request ->
val args = request.params.arguments
val a = args?.get("a")?.jsonPrimitive?.intOrNull
val b = args?.get("b")?.jsonPrimitive?.intOrNull
if (a == null || b == null) {
CallToolResult(content = listOf(TextContent("a and b must be integers")), isError = true)
} else {
CallToolResult(content = listOf(TextContent((a + b).toString())), isError = false)
}
}
val transport = TracedTransport(StdioServerTransport(
System.`in`.asSource().buffered(), System.out.asSink().buffered()
))
val closed = CompletableDeferred<Unit>()
transport.onClose { closed.complete(Unit) }
try {
server.createSession(transport)
closed.await()
} finally {
server.close()
}
Unit
}
1.4 客户端:发现工具,再经过 Koog 调用
保存为 src/main/kotlin/mcpdemo/ClientMain.kt。客户端不是直接调用 Kotlin 的加法函数,而是经过 ToolRegistry、MCP 工具适配和 stdio 往返到服务端。
按名字查找会擦除工具泛型,所以示例在已经确认的 SDK 返回类型上恢复泛型。生产代码不应对未知工具随意套用这个 cast。
package mcpdemo
import ai.koog.agents.core.tools.ToolBase
import ai.koog.agents.core.tools.ToolCallMetadata
import ai.koog.agents.mcp.McpToolRegistryProvider
import ai.koog.agents.mcp.defaultStdioTransport
import ai.koog.agents.mcp.metadata.McpServerInfo
import ai.koog.serialization.JSONObject
import ai.koog.serialization.kotlinx.KotlinxSerializer
import ai.koog.serialization.kotlinx.toKoogJSONObject
import io.modelcontextprotocol.kotlin.sdk.client.Client
import io.modelcontextprotocol.kotlin.sdk.types.CallToolResult
import io.modelcontextprotocol.kotlin.sdk.types.Implementation
import io.modelcontextprotocol.kotlin.sdk.types.TextContent
import kotlinx.coroutines.runBlocking
import kotlinx.coroutines.withTimeout
import kotlinx.serialization.json.*
import java.io.File
import java.util.concurrent.TimeUnit
fun main() = runBlocking {
val java = File(System.getProperty("java.home"), "bin/java").absolutePath
val process = ProcessBuilder(java, "-cp", System.getProperty("java.class.path"), "mcpdemo.ServerMainKt")
.redirectError(File("protocol.log"))
.start()
val client = Client(Implementation("koog-local-check", "1.0.0"))
try {
withTimeout(15_000) {
client.connect(McpToolRegistryProvider.defaultStdioTransport(process))
println("CONNECTED ${client.serverVersion?.name}")
// fromClient performs a real tools/list request, then adapts descriptors.
val registry = McpToolRegistryProvider.fromClient(client, McpServerInfo(command = "local-kotlin-server"))
println("DISCOVERED " + registry.tools.joinToString { it.name })
check(registry.tools.map { it.name } == listOf("add"))
// Cast only because a name lookup intentionally erases the generic types.
@Suppress("UNCHECKED_CAST")
val add = registry.getTool("add") as ToolBase<JSONObject, CallToolResult?>
println("SCHEMA " + add.descriptor.requiredParameters.joinToString { "${it.name}:${it.type}" })
val serializer = KotlinxSerializer()
val good = add.execute(buildJsonObject { put("a", 7); put("b", 5) }.toKoogJSONObject(), ToolCallMetadata.EMPTY)
check(good?.isError == false)
check((good.content.single() as TextContent).text == "12")
println("CALL add(7,5) " + add.encodeResultToString(good, serializer))
val bad = add.execute(buildJsonObject { put("a", 7) }.toKoogJSONObject(), ToolCallMetadata.EMPTY)
check(bad?.isError == true)
println("CALL add(7,missing) " + add.encodeResultToString(bad, serializer))
println("NO_MODEL_REQUESTS")
}
} finally {
// Close the child stdin FIRST: unblock the JVM's blocking read at EOF.
process.outputStream.close()
if (!process.waitFor(5, TimeUnit.SECONDS)) {
process.destroy()
if (!process.waitFor(2, TimeUnit.SECONDS)) {
process.destroyForcibly()
check(process.waitFor(2, TimeUnit.SECONDS))
}
}
client.close()
println("CLOSED childAlive=${process.isAlive} exit=${process.exitValue()}")
}
Unit
}
运行:
./gradlew clean compileKotlin stdioDemo --console=plain
本次实际输出,省略 Gradle 和日志初始化信息:
CONNECTED local-kotlin-tools
DISCOVERED add
SCHEMA a:Integer, b:Integer
CALL add(7,5) {"content":[{"text":"12","type":"text"}],"isError":false}
CALL add(7,missing) Error: a and b must be integers
NO_MODEL_REQUESTS
CLOSED childAlive=false exit=0
这次执行还记录到了 initialize、initialized、tools/list 和两次工具调用。成功路径返回 12,缺参数路径返回 isError=true,Koog 编码为错误文本。工具声明有 schema,不意味着远端业务错误不会发生。
关闭顺序也值得保留:先关闭子进程 stdin,让阻塞读取遇到 EOF;等待退出,超时才终止进程,最后关闭 MCP Client。这个顺序是本例 JVM stdio 生命周期的实际验证结果,不是所有传输都照搬的通用模板。
1.5 把 MCP 工具交给模型
前面手动调用工具,是为了把协议验证和模型决策分开。拿到 registry 后,Agent 的安装方式与本地工具相同:
package mcpdemo
import ai.koog.agents.core.agent.AIAgent
import ai.koog.agents.core.tools.ToolRegistry
import ai.koog.prompt.executor.clients.deepseek.DeepSeekLLMClient
import ai.koog.prompt.executor.clients.deepseek.DeepSeekModels
import ai.koog.prompt.executor.llms.MultiLLMPromptExecutor
// COMPILE ONLY. No main() calls this function; no secret is read.
// The caller owns the MCP Client and child process for the entire agent run.
private suspend fun deepSeekAgentCompileOnly(toolRegistry: ToolRegistry): String {
val executor = MultiLLMPromptExecutor(DeepSeekLLMClient("xxxxxxx"))
try {
val agent = AIAgent(
promptExecutor = executor,
llmModel = DeepSeekModels.DeepSeekV4Flash,
toolRegistry = toolRegistry,
systemPrompt = "需要计算时调用 add 工具,不要猜测工具结果。"
)
try {
return agent.run("请使用工具计算 7 + 5。")
} finally {
agent.close()
}
} finally {
executor.close()
}
}
这段函数只编译,没有被上面的 main 调用;要实际请求模型,必须提供有效凭据并在 MCP 连接仍存活时调用。提示词要求使用 add,也不是程序级强制调用保证;若业务必须经过工具,应在策略中明确安排工具节点。
1.6 连接、发现与安全的边界
- registry 是本次工具发现的快照。固定版本 provider 没有自动刷新,也没有遍历 tools/list 分页 cursor;工具很多时要核对实际发现数量。
- 描述解析失败的工具可能被跳过。成功构造 registry 不等于发现了服务端全部工具。
- ToolRegistry 没有 close。便捷入口隐藏了 SDK Client;需要明确生命周期时,像本文一样保留 Client 并用
fromClient。 - 核心
AIAgentBase.close()在本版本没有负责关闭 executor 的实现。MCP Client、HTTP Client 和子进程都不能寄希望于 agent.close 自动清理。 - stdio 服务进程可以继承应用权限,远端工具则可能接触业务数据。应限制命令、服务器地址、工具和凭据,不能让模型任意指定可执行程序或访问地址。
- 工具描述与结果是不可信输入。MCP 是互操作协议,不是提示词注入防护、授权系统或业务幂等机制。
二、后端集成:把 Agent 提供给业务系统
2.1 框架负责承载,不负责替你设计业务
接入 MCP 后,Agent 能使用外部工具,但还没有业务系统可以调用的 HTTP 入口。Ktor 和 Spring Boot 集成解决组件装配与调用问题,不会自动生成 /chat 路由、鉴权、会话存储或限流。
本篇不要求同时使用两个后端框架。Ktor 给出完整 HTTP 例子,Spring Boot 展示对应配置和注入方式。
本节两种方式在一个验证上下文中编译,依赖如下;实际应用只保留所选框架的依赖即可:
plugins {
kotlin("jvm") version "2.3.20"
application
}
repositories { mavenCentral() }
kotlin { jvmToolchain(21) }
dependencies {
implementation("ai.koog:koog-agents:1.3.0")
implementation("ai.koog:koog-ktor:1.3.0-beta")
implementation("io.ktor:ktor-server-cio:3.3.3")
implementation(platform("org.springframework.boot:spring-boot-dependencies:3.5.14"))
implementation("ai.koog:koog-spring-boot-starter:1.3.0-beta")
implementation("org.springframework.boot:spring-boot-starter-web")
implementation("org.jetbrains.kotlinx:kotlinx-coroutines-reactor:1.10.2")
}
application { mainClass.set("demo.BackendKt") }
tasks.register("classpath") { doLast { file("classpath.txt").writeText(sourceSets.main.get().runtimeClasspath.asPath) } }
其中 classpath 任务只是便于独立验证,不是 Koog 要求的配置。Ktor 和 Spring starter 在本文固定发布物中使用 1.3.0-beta,核心仍使用 1.3.0;本节没有验证 Spring Boot 4。
2.2 Ktor:完整的 HTTP → Agent 路径
保存为 src/main/kotlin/demo/Backend.kt。安装官方 Koog 插件,在路由里通过 aiAgent 创建 Agent,再执行普通 Kotlin 节点。
图里没有 LLM 请求节点。构造时填写模型元数据,不等于已经请求了这个模型;也不需要为此准备 OpenAI 凭据。200ms、slow/fail 输入是为了测试分支,不是建议生产接口只允许 200ms。
package demo
import ai.koog.agents.core.dsl.builder.*
import ai.koog.ktor.Koog
import ai.koog.ktor.aiAgent
import ai.koog.ktor.llm
import ai.koog.prompt.executor.clients.openai.OpenAIModels
import io.ktor.http.HttpStatusCode
import io.ktor.server.application.*
import io.ktor.server.cio.CIO
import io.ktor.server.engine.embeddedServer
import io.ktor.server.request.receiveText
import io.ktor.server.response.respondText
import io.ktor.server.routing.*
import kotlinx.coroutines.*
// 全部是普通 Kotlin 逻辑;这个图没有 requestLLM 节点。
private val localStrategy = strategy<String, String>("local") {
val normalize by node<String, String> { input ->
when (input) {
"fail" -> error("deliberate failure")
"slow" -> delay(1_000)
}
"runId=$runId;result=${input.trim().uppercase()}"
}
edge(nodeStart forwardTo normalize)
edge(normalize forwardTo nodeFinish)
}
fun Application.localModule() {
install(Koog) {
agentConfig {
maxAgentIterations = 10
prompt("backend") { system("本地验证,不请求模型") }
}
}
// 1.3.0-beta 插件源码没有自动关闭 executor 的停机钩子;由应用明确负责。
val executor = plugin(Koog).promptExecutor
monitor.subscribe(ApplicationStopped) {
executor.close()
}
routing {
post("/local") {
val input = call.receiveText()
if (input.isBlank() || input.length > 100) {
call.respondText("invalid input", status = HttpStatusCode.BadRequest)
return@post
}
// 实际业务应从已认证身份映射会话;这里固定演示值,不是鉴权或历史存储。
val sessionId = "article-local-session"
try {
val output = withTimeoutOrNull(200) {
aiAgent(localStrategy, OpenAIModels.Chat.GPT4_1) { agent ->
agent.run(input, sessionId)
}
}
if (output == null) {
call.respondText("agent timeout", status = HttpStatusCode.GatewayTimeout)
} else {
call.respondText(output)
}
} catch (e: CancellationException) {
throw e
} catch (e: Exception) {
// 不把内部异常、提示词或密钥直接回给客户端。
call.respondText("agent failed", status = HttpStatusCode.InternalServerError)
}
}
get("/executor") {
call.respondText("shared=${llm() === call.application.plugin(Koog).promptExecutor}")
}
}
}
fun main() {
embeddedServer(CIO, host = "127.0.0.1", port = 18080) { localModule() }.start(wait = true)
}
启动后,可以实际请求:
./gradlew run
# 另一个终端
curl -sS -X POST http://127.0.0.1:18080/local --data ' koog '
响应正文:
runId=article-local-session;result=KOOG
本次还逐项检查了空输入得到 400、fail 得到 500、slow 得到 504,以及超时后下一次请求仍可成功;另外发送 16 个不同输入的并发请求,均得到对应结果。这些检查不使用聊天历史,不能用来证明共享会话存储没有竞争。
llm() 返回应用插件持有的共享 executor;aiAgent(...){...} 每次创建 Agent。共享不捕获可变业务状态的策略描述,与共享带有可变状态的工具或 Feature,不是同一回事。
2.3 接入真实模型,以及 Spring 的对应方式
下面的文件保留两种接入方式:私有 Ktor module 没有挂载到上面的服务器,Spring Controller 也没有发起模型调用。它们已编译,但不在本篇协议验证中请求收费模型。
实际部署应选择其中一种;server-authorized-session 只是说明参数传递位置,绝不能让不同用户真的共用这个固定值:
package demo
import ai.koog.agents.core.agent.AIAgent
import ai.koog.ktor.Koog
import ai.koog.ktor.aiAgent
import ai.koog.ktor.llm
import ai.koog.prompt.dsl.prompt
import ai.koog.prompt.executor.clients.deepseek.DeepSeekModels
import ai.koog.prompt.executor.model.PromptExecutor
import io.ktor.server.application.*
import io.ktor.server.request.receiveText
import io.ktor.server.response.respondText
import io.ktor.server.routing.*
import kotlinx.coroutines.CancellationException
import org.springframework.beans.factory.annotation.Qualifier
import org.springframework.web.bind.annotation.*
// 编译验证,不被 main 调用、不挂载到本地服务。不读环境变量,不调用真实模型。
private fun Application.realModelModuleCompileOnly() {
install(Koog) {
llm { deepSeek(apiKey = "xxxxxxx") }
agentConfig {
maxAgentIterations = 10
prompt("backend") { system("请用中文回答") }
}
}
val executor = plugin(Koog).promptExecutor
monitor.subscribe(ApplicationStopped) {
executor.close()
}
routing {
post("/chat") {
val input = call.receiveText()
val result = aiAgent(model = DeepSeekModels.DeepSeekV4Flash) { agent ->
agent.run(input, sessionId = "server-authorized-session")
}
call.respondText(result)
}
post("/direct") {
val input = call.receiveText()
val response = llm().execute(prompt("direct") { user(input) }, DeepSeekModels.DeepSeekV4Flash)
call.respondText(response.textContent())
}
}
}
// Starter 提供 executor bean;Controller、Agent 和 HTTP 路由仍由应用编写。
@RestController
@RequestMapping("/api/chat")
class SpringChatController(
@param:Qualifier("deepSeekExecutor") private val executor: PromptExecutor
) {
@PostMapping
suspend fun chat(@RequestBody input: String): String {
require(input.isNotBlank() && input.length <= 4_000)
val agent = AIAgent(
promptExecutor = executor,
llmModel = DeepSeekModels.DeepSeekV4Flash,
systemPrompt = "请用中文回答",
maxIterations = 10
)
return try {
agent.run(input, sessionId = "server-authorized-session")
} catch (e: CancellationException) {
throw e
} finally {
agent.close() // 不关闭由 Spring 容器共享的 executor
}
}
}
Spring 配置示例,保存到应用配置中;凭据为占位值:
ai.koog.deepseek.enabled=true
ai.koog.deepseek.api-key=xxxxxxx
ai.koog.deepseek.base-url=https://api.deepseek.com
Starter 提供 DeepSeek 客户端和 executor Bean,Controller 由应用编写。多个 executor 同时存在时,使用 @Qualifier("deepSeekExecutor") 明确注入对象,不依赖参数名碰巧匹配。Spring 应用还需要常规的 Boot 启动类和组件扫描配置,这段 Controller 本身不是完整的可启动应用。
本次另外建立了不启动 Web 服务的 Spring Context,验证属性绑定、条件 Bean、Qualifier 注入和 Context 关闭;没有把这个结果称为 Spring HTTP 服务已运行。Ktor 使用 koog.deepseek.apikey 等配置名,Spring 使用 ai.koog.deepseek.api-key,两套配置不能混用。
还有一个官网与固定 API 的差异:PromptExecutor.execute 在 1.3.0 返回单个 Message.Assistant,取文本用 textContent(),不能照抄旧例中的 joinToString 或 first().content。
2.4 生命周期、会话与取消
Ktor 插件的固定版本源码没有注册关闭 executor 的停机钩子,因此本文显式订阅 ApplicationStopped。应用共享 executor 不要在每个请求中关闭;Spring 容器共享 Bean 同理,应由其所有者管理。
aiAgent(strategy, model, input) 便捷重载传入 null sessionId;需要指定标识时使用 block 重载。sessionId 决定 runId,不自动提供 ChatMemory、登录身份绑定或用户授权。第六篇的历史机制必须另行配置,同一会话并发读写还需要串行化或版本控制。
本例保留外部 CancellationException 的传播,只把自己的 timeout 转成 504。模型取消、客户端断连、代理和引擎的组合需要另测,不能由这一个本地请求推断全部生效。
最后,provider fallback 不等于所有 429、超时和供应商故障都会自动跨供应商重试。本版本相关 fallback 主要处理请求 provider 未配置时的替代选择;业务异常切换需要另行设计,不能吞掉取消。路由中的输入长度检查也不替代 HTTP 层的请求体上限。
三、A2A:与独立 Agent 服务协作
3.1 为什么不是再加一个 MCP 工具
MCP 主要围绕工具和上下文接入。A2A 面向独立 Agent 服务之间的能力发现与通信:调用方提交消息,对方可以即时回复,也可以创建具有状态和产物的任务。
两者会有使用场景重叠,但抽象不同。普通 HTTP 接口也能完成业务调用;只有需要相应的互操作约定时才引入协议。第五篇进程内多 Agent 策略不会因为节点多就自动变成 A2A。
本文模块实现对应 A2A 0.3.0,不宣称兼容所有后续协议版本。
3.2 先分清 Card、Message、Task 与 Artifact
| 对象 | 作用 |
|---|---|
| AgentCard | 描述名称、地址、技能、输入输出与能力 |
| Message | 带 role、parts、messageId 等信息的通信消息 |
| Task | 带标识和状态的工作实体,可包含历史和产物 |
| Artifact | 任务产物,例如文本或其他结果片段 |
不是每条 Message 都必须产生 Task,也不是每次请求都返回字符串。Card 里的能力描述不会替你实现业务,更不会自动配置认证。
3.3 完整闭环:发现、消息、任务与查询
下面的单文件例子实际启动 HTTP JSON-RPC 服务。服务端自己实现 AgentExecutor,在每次请求中创建 Koog Agent,安装 A2AAgentServer;策略只执行大写转换,不创建模型客户端。
普通输入返回 Message;以 task: 开头的输入则依次发送 Working、Artifact 和 Completed 事件。客户端通过真实 HTTP 发现 AgentCard,再验证两种结果。
依赖:
dependencies {
implementation("ai.koog:koog-agents:1.3.0")
implementation("ai.koog:agents-features-a2a-server:1.3.0-beta")
implementation("ai.koog:a2a-client:1.3.0-beta")
implementation("ai.koog:a2a-transport-server-jsonrpc-http:1.3.0-beta")
implementation("ai.koog:a2a-transport-client-jsonrpc-http:1.3.0-beta")
implementation("io.ktor:ktor-server-cio:3.3.3")
implementation("io.ktor:ktor-client-cio:3.3.3")
}
本例采用 Kotlin JVM/application 插件与 JDK 21,mainClass 设为 verify.A2ACheckKt。保存为 src/main/kotlin/verify/A2ACheck.kt:
package verify
import ai.koog.a2a.client.A2AClient
import ai.koog.a2a.client.UrlAgentCardResolver
import ai.koog.a2a.model.*
import ai.koog.a2a.server.A2AServer
import ai.koog.a2a.server.agent.AgentExecutor
import ai.koog.a2a.server.session.RequestContext
import ai.koog.a2a.server.session.SessionEventProcessor
import ai.koog.a2a.transport.Request
import ai.koog.a2a.transport.RequestId
import ai.koog.a2a.transport.client.jsonrpc.http.HttpJSONRPCClientTransport
import ai.koog.a2a.transport.server.jsonrpc.http.HttpJSONRPCServerTransport
import ai.koog.agents.a2a.server.feature.A2AAgentServer
import ai.koog.agents.a2a.server.feature.withA2AAgentServer
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.dsl.prompt
import ai.koog.prompt.executor.llms.MultiLLMPromptExecutor
import ai.koog.prompt.executor.clients.openai.OpenAIModels
import io.ktor.client.HttpClient
import io.ktor.client.engine.cio.CIO as ClientCIO
import io.ktor.server.cio.CIO as ServerCIO
import kotlinx.coroutines.runBlocking
import kotlinx.coroutines.withTimeout
// No LLM clients exist. The graph performs only deterministic local computation.
private class DeterministicKoogExecutor : AgentExecutor {
override suspend fun execute(
context: RequestContext<MessageSendParams>,
eventProcessor: SessionEventProcessor,
) {
val executor = MultiLLMPromptExecutor(emptyMap())
val agent = AIAgent(
promptExecutor = executor,
agentConfig = AIAgentConfig(
prompt = prompt("offline") { system("Unused: deterministic graph.") },
model = OpenAIModels.Chat.GPT4o,
maxAgentIterations = 5,
),
strategy = strategy<Message, Unit>("deterministic-a2a") {
val respond by node<Message, Unit> { incoming ->
val text = incoming.parts.filterIsInstance<TextPart>().joinToString("") { it.text }
val answer = "local-result: ${text.uppercase()}"
withA2AAgentServer {
if (text.startsWith("task:")) {
eventProcessor.sendTaskEvent(Task(
id = context.taskId, contextId = context.contextId,
status = TaskStatus(TaskState.Working),
))
eventProcessor.sendTaskEvent(TaskArtifactUpdateEvent(
taskId = context.taskId, contextId = context.contextId,
artifact = Artifact("result", parts = listOf(TextPart(answer))),
append = false, lastChunk = true,
))
eventProcessor.sendTaskEvent(TaskStatusUpdateEvent(
taskId = context.taskId, contextId = context.contextId,
status = TaskStatus(TaskState.Completed), final = true,
))
} else {
eventProcessor.sendMessage(Message(
messageId = "reply-${incoming.messageId}", role = Role.Agent,
parts = listOf(TextPart(answer)), contextId = context.contextId,
))
}
}
}
edge(nodeStart forwardTo respond)
edge(respond forwardTo nodeFinish)
},
) {
install(A2AAgentServer) {
this.context = context
this.eventProcessor = eventProcessor
}
}
try { agent.run(context.params.message) } finally { agent.close(); executor.close() }
}
// No cancel override: the default rejects cancellation.
}
private fun messageRequest(text: String, id: String) = Request(
data = MessageSendParams(
message = Message(messageId = id, role = Role.User, parts = listOf(TextPart(text))),
configuration = MessageSendConfiguration(blocking = true, historyLength = 10),
),
id = RequestId.StringId(id),
)
fun main() = runBlocking {
val base = "http://127.0.0.1:18761"
val card = AgentCard(
name = "Deterministic Koog", description = "Offline graph; no model requests",
url = "$base/a2a", version = "1.0.0", protocolVersion = "0.3.0",
preferredTransport = TransportProtocol.JSONRPC,
capabilities = AgentCapabilities(streaming = false, pushNotifications = false),
defaultInputModes = listOf("text/plain"), defaultOutputModes = listOf("text/plain"),
skills = listOf(AgentSkill("uppercase", "Uppercase", "Deterministic uppercase", listOf("local"))),
)
val server = A2AServer(agentExecutor = DeterministicKoogExecutor(), agentCard = card)
val serverTransport = HttpJSONRPCServerTransport(server)
val baseClient = HttpClient(ClientCIO)
val clientTransport = HttpJSONRPCClientTransport("$base/a2a", baseClient)
val client = A2AClient(clientTransport, UrlAgentCardResolver(base, baseHttpClient = baseClient))
try {
serverTransport.start(ServerCIO, port = 18761, path = "/a2a", agentCard = card)
withTimeout(30_000) {
client.connect() // Actual HTTP GET /.well-known/agent-card.json
val discovered = client.cachedAgentCard()
check(discovered.url == "$base/a2a")
println("DISCOVERY name=${discovered.name} protocol=${discovered.protocolVersion} url=${discovered.url}")
val reply = client.sendMessage(messageRequest("hello koog", "message-1")).data as Message
val text = reply.parts.filterIsInstance<TextPart>().single().text
check(text == "local-result: HELLO KOOG")
println("MESSAGE kind=${reply.kind} role=${reply.role} text=$text")
val task = client.sendMessage(messageRequest("task: hello", "message-2")).data as Task
check(task.status.state == TaskState.Completed)
val result = task.artifacts!!.single().parts.filterIsInstance<TextPart>().single().text
check(result == "local-result: TASK: HELLO")
println("TASK state=${task.status.state} artifacts=${task.artifacts!!.size} text=$result")
val reread = client.getTask(Request(TaskQueryParams(id = task.id, historyLength = 10))).data
// 1.3.0-beta A2AServer.onGetTask explicitly uses includeArtifacts=false.
check(reread.artifacts == null)
check(reread.status.state == TaskState.Completed)
println("GET_TASK state=${reread.status.state} artifacts=${reread.artifacts} (1.3.0-beta omits artifacts)")
println("PASS local HTTP discovery + message/send + task artifacts + tasks/get; no LLM configured")
}
} finally {
clientTransport.close()
baseClient.close()
serverTransport.stop()
}
Unit
}
运行 ./gradlew run 后,本次实际业务输出为:
DISCOVERY name=Deterministic Koog protocol=0.3.0 url=http://127.0.0.1:18761/a2a
MESSAGE kind=message role=Agent text=local-result: HELLO KOOG
TASK state=Completed artifacts=1 text=local-result: TASK: HELLO
GET_TASK state=Completed artifacts=null (1.3.0-beta omits artifacts)
PASS local HTTP discovery + message/send + task artifacts + tasks/get; no LLM configured
这里有几处不能省略:
- 自定义 DeterministicKoogExecutor 是本文的适配代码,不是框架里可以直接 new 的 KoogAgentExecutor。Feature 不会自动启动 HTTP server,也不会把图的最终返回值自动变成 A2A 回复;节点必须发送协议消息或事件。
start(..., agentCard=card)才注册公开发现路由。只给 A2AServer 传 card 不够。Card URL、实际 RPC 地址和客户端地址必须一致。client.connect()在本例通过 HTTP 获取并缓存 Card,不是建立一个永久会话连接。blocking=true选择当前请求事件流的最后结果。本版本不能把未设置 blocking 的 sendMessage 说成必定等待任务完成。- 本例先创建 Task,再更新 artifact 和终态。一个 session 不能随意混发 Message 与 TaskEvent;发送 final/终态后也不能继续追加。
最容易误写的是查询:这个 beta 版本的 tasks/get 明确排除了 artifacts。所以 sendMessage 返回一项产物,之后 getTask 得到 Completed 但 artifacts=null,是固定实现的实际行为,不是日志漏打印。不要承诺“完成后随时用 tasks/get 下载全部产物”。
3.4 让另一个 Koog Agent 调用远端 Agent
前面使用 A2AClient 直接测试协议。若调用方也有 Koog 图,可以安装 A2AAgentClient,把已连接的客户端按名字提供给节点。服务端 Feature 使用 context/eventProcessor,客户端 Feature 使用 a2aClients 映射,两者不能混用。
下面函数返回一个只委派远端请求的 Agent;调用者先连接 client,并负责在 Agent 使用完后关闭 transport/HTTP Client。这个接入函数只编译核验,未另做一次远端委派运行:
package verify
import ai.koog.a2a.client.A2AClient
import ai.koog.a2a.model.CommunicationEvent
import ai.koog.a2a.model.Message
import ai.koog.a2a.model.MessageSendConfiguration
import ai.koog.a2a.model.MessageSendParams
import ai.koog.a2a.transport.Request
import ai.koog.agents.a2a.client.feature.A2AAgentClient
import ai.koog.agents.a2a.client.feature.a2aClientOrThrow
import ai.koog.agents.a2a.client.feature.withA2AAgentClient
import ai.koog.agents.core.agent.AIAgent
import ai.koog.agents.core.dsl.builder.*
import ai.koog.prompt.executor.clients.openai.OpenAIModels
import ai.koog.prompt.executor.llms.MultiLLMPromptExecutor
// 调用方负责 client 的连接和关闭;这里不创建模型客户端。
fun coordinator(client: A2AClient) = AIAgent(
promptExecutor = MultiLLMPromptExecutor(emptyMap()),
llmModel = OpenAIModels.Chat.GPT4o,
strategy = strategy<Message, CommunicationEvent>("remote-worker") {
val delegate by node<Message, CommunicationEvent> { message ->
withA2AAgentClient {
a2aClientOrThrow("worker").sendMessage(
Request(MessageSendParams(
message = message,
configuration = MessageSendConfiguration(blocking = true),
))
).data
}
}
edge(nodeStart forwardTo delegate)
edge(delegate forwardTo nodeFinish)
},
) {
install(A2AAgentClient) { a2aClients = mapOf("worker" to client) }
}
这个片段另需 ai.koog:agents-features-a2a-client:1.3.0-beta。A2A 返回 CommunicationEvent,后续节点应按 Message/Task 区分处理,不能直接 cast 成任意一种。它也不会因为安装 Feature 就自动发现所有远端 Agent 或让模型自主选择服务。
3.5 有 API,不等于已经有生产能力
本篇只实测 HTTP Card 发现、message/send 的 Message/Task 分支和 tasks/get。流式、重订阅、取消、push 和认证扩展卡仅核对接口与源码,未做端到端验证。
- 示例声明 streaming=false、pushNotifications=false。把字段改成 true 不会自动实现对应业务。
- 默认 AgentExecutor.cancel 会拒绝取消。需要真正取消任务时,应管理运行中的 job 并发布一致的终态。
- 默认内存任务存储不是持久化、跨实例共享或可靠队列。
- HTTP server transport 的这个 standalone start 没有 host 参数。示例虽用回环 URL 访问,不能据此认为服务只绑定回环地址;不要把未加固的测试服务直接暴露到公网。
- 协议里的上下文标识不替代身份授权。远端重试、重复任务、取消与产物保留策略仍需要业务设计。
四、其他生态:先知道它们解决什么问题
4.1 ACP:面向 IDE 和客户端
Agent Client Protocol 用于 Agent 与支持该协议的 IDE/客户端交互。Koog 的 JVM 适配桥接输入、工具与模型事件、执行同步和通知;它不是 MCP 工具服务器,也不是 A2A 的网络 Agent 发现机制。
如果目标是让 Agent 接入编辑器,再考虑 ACP。本篇不展开完整 session 和 stdio 生命周期,也没有实测 IDE 接入。
4.2 Bedrock AgentCore:AWS 的运行与记忆服务
AgentCore 不等于又一个模型供应商。Koog 相关集成分为 Runtime 与 Memory:前者提供 /invocations、/ping 等 Runtime HTTP 契约,后者衔接对话事件和长期记忆服务。
这和直接用 Bedrock 客户端调用模型是两层能力。AWS 部署、权限、region、记忆资源与云侧处理都不在本篇验证范围;安装依赖不意味着已经完成托管部署或持久化配置。
4.3 已有 Spring AI 项目怎么办
直接使用 koog-spring-boot-starter,通常由 Koog 客户端和 ai.koog 配置构造组件。另一条路线是 Spring AI 适配:复用已经配置好的 ChatModel、EmbeddingModel、ChatMemoryRepository 和 VectorStore,再交给 Koog 使用。
这对应四个 beta starter,不是把 Koog 的 Agent 编排替换成 Spring AI。工具的执行仍归 Koog 管理。适配也不保证无损:文本历史桥接不等于完整执行状态持久化,VectorStore 桥接的 namespace、按 id 读取和 update 语义也要逐项核对。本篇只说明定位,没有启动这些适配链路。
五、怎么组合,而不是全部都装
| 需求 | 起点 |
|---|---|
| 在已有后端提供 Agent 接口 | Ktor 或 Spring Boot 集成 |
| 使用已有外部工具服务 | MCP |
| 调用独立 Agent 能力或提供标准 Agent 服务 | A2A |
| 让 Agent 接入支持 ACP 的 IDE/客户端 | ACP |
| 采用 AWS Agent 托管运行或记忆服务 | AgentCore 相应集成 |
| 复用已有 Spring AI 基础设施 | Spring AI 适配 |
一个可能的组合是:
前端/业务系统
→ Ktor 或 Spring Boot 后端
→ Koog Agent
→ MCP 外部工具
→ A2A 远端 Agent
这不是推荐每个项目都采用的必选架构。后端直接调用 Koog 也完全成立;没有独立工具或 Agent 服务时,不需要为了“生态完整”增加协议层。
后记
到这里,系列从最初的模型调用、工具和图策略,走到了状态管理、工程化、知识增强和外部集成。最后一篇没有再引入一种包办所有问题的框架:协议负责互操作,后端负责承载,Koog 负责 Agent 的执行组织,业务仍负责事实、权限与状态边界。
本篇验证范围如下:
| 示例 | 已验证 | 没有验证 |
|---|---|---|
| MCP stdio | 握手、发现、经 Koog 调用工具、成功/错误返回、进程退出 | 模型自主调用、远端 SSE/Streamable HTTP 链路 |
| Ktor | 插件、HTTP 正常/异常/超时、无历史并发 | 真实模型、完整鉴权、生产负载、断连取消 |
| Spring Boot | 编译、属性绑定、条件 Bean、Qualifier 注入、Context 关闭 | Spring HTTP 启动与真实模型调用 |
| A2A | HTTP 发现、Message/Task、artifact 返回、tasks/get | 客户端 Feature 委派实跑、流式、取消、push、认证 |
| ACP/AgentCore/Spring AI 适配 | 官方定位与发布版源码核对 | IDE、AWS 或适配链路运行 |
所有可见输出来自实际执行,不用离线模型替身冒充联网回答。外部接口的版本状态、生命周期与缺省行为也应随着依赖升级重新核验。
参考资料
- MCP:https://docs.koog.ai/model-context-protocol/
- Ktor:https://docs.koog.ai/ktor-plugin/
- Spring Boot:https://docs.koog.ai/spring-boot/
- A2A:https://docs.koog.ai/a2a/
- A2A Server:https://docs.koog.ai/a2a/a2a-server/
- A2A Client:https://docs.koog.ai/a2a/a2a-client/
- A2A 与 Koog:https://docs.koog.ai/a2a/a2a-koog-integration/
- ACP:https://docs.koog.ai/agent-client-protocol/
- AgentCore:https://docs.koog.ai/amazon-bedrock-agentcore/
- Spring AI:https://docs.koog.ai/spring-ai-integration/

浙公网安备 33010602011771号