XXAgent 开发 Koog 选型与使用指南

本文面向 XXAgent 开发覆盖两部分① 为什么选 Koog技术选型② Koog 是什么、怎么用、在本项目怎么落地并附实测踩坑。适用版本ai.koog:koog-agents 1.2.0见gradle/libs.versions.toml。一、技术选型为什么是 Koog立项阶段对比了 5 个 Kotlin / 端侧 Agent 框架结论是选用JetBrains Koog——它是这批里唯一同时满足 A2A 可当 Server、有 MCP、有 OpenAI 兼容 provider 三条架构基线且成熟度与依赖体积都更适合车机的方案。1.1 横向对比维度Koogadk-kotlinDeliteAIMalikClawZorvAI形态Agent 框架Agent 框架端侧推理平台个人助手引擎手机端 App语言/栈Kotlin 多平台Kotlin 多平台C PythonGoKotlin版本/成熟度1.2.0 stableABI 校验1.1.0 stable528★停更 1 年1188 commits个人项目Android 集成✅ KMP 目标✅ KMP 目标✅ SDK❌ 仅 Termux CLI是 App 本身A2A Server✅ 有❌ 只能当 Client❌❌❌MCP✅✅ 原生一等公民❌❌✅OpenAI 兼容 / 自定义 endpoint✅ OpenAI/DeepSeek/Ollama/OpenRouter❌ 内置只 Gemini 系—✅—依赖重量极轻协程序列化datetime较重GenAI SDK Ktor需带 Python 运行时10MB 但 Go—许可Apache 2.0Apache 2.0Apache 2.0—未明1.2 为什么选 KoogA2A 这关只有它过。车控 Agent 要被语音 Agent 调必须当 A2A Serveradk-kotlin 官方文档原话 “cannot expose an agent over A2A yet”直接出局或得自己补。Koog 代码库里有a2a模块方向对得上。火山接入最省事。Koog provider 列表含 OpenAI / DeepSeek / Ollama / OpenRouter——火山方舟是 OpenAI 兼容接口改个 baseUrl 即可可能连自定义 Model 都不用写。adk-kotlin 那边得自己写VolcanoModel : Model。依赖轻车机友好。Koog 传递依赖只有 kotlinx 三件套adk-kotlin 的 core 会拖进 GenAI SDK 和 Ktor在座舱 APK 里是实打实的包体和冷启动成本。企业级特性对上车控场景。图工作流、状态检查点持久化车机掉电/进程被杀后恢复会话、历史压缩省 token、Streaming API 支持并行工具调用。JetBrains 出品 semver CI 拦破坏性 API 变更供应商风险比 Google 那个标 Experimental 的 A2A 低。实现说明选型时看重 Koog 的 A2A 能力但 CarAgent 当前 A2A 暴露层用Ktor 自研:a2a模块便于与 Master Agent 协议对齐、跨团队协商 AgentCard 字段Koog 负责Agent 内核 工具编排。两者职责不冲突。1.3 其余四个为什么不用ZorvAI—— 参考素材不是框架。手机端 AI 助手 App120 工具、Shizuku/ROOT 特权分级定位控制手机无车控/Vehicle HAL 接口许可证未写明。值得借鉴的是它的工具分级授权设计可引入护栏层。MalikClaw—— 语言栈不对。Go 写的只有 Termux CLI 和 Go 库嵌入无 Android SDK/AAR定位个人助手 15 个消息渠道网关与车机无关。DeliteAI—— 方向对Apache 2.0README 明确 automobile 场景端侧隐私推理但最后一次提交停在 2025-08一年多没动。车机量产不敢押注停更项目且带端侧 Python 运行时车机塞 Python 解释器需掂量。adk-kotlin—— 不是不能用。MCP 比 Koog 更强若偏 Google 生态或未来用 LiteRT-LM 跑端侧 Gemma 仍有价值。但A2A 只能当 Client这条与设计直接冲突。1.4 落地建议语音 Agent ──A2A──▶ 车控 Agent (Koog AIAgent GraphWorkflow) │ ├─ LLM: 火山方舟OpenAI 兼容 provider改 baseUrl ├─ 控车: MCP Client 调「车机能力 MCP Server」 ├─ 护栏: Koog 拦截器 / 自定义工具封装层 └─ 记忆/检查点: Koog 持久化支撑掉电恢复二、Koog 是什么项说明出品JetBrains 官方开源GitHub:JetBrains/koog语言100% Kotlin基于 Kotlin MultiplatformKMP编译产物库不是应用。坐标ai.koog:koog-agents通过 Gradle 引入编译进 JVM / Android 应用产物为jar/ KMP 的klib可运行目标JVM、Android、iOS、JS、WasmJS —— “一次编写多端部署”定位让 Kotlin 开发者用原生 DSL 写会调工具、能跑工作流的 AI Agent不必拼 Python 或手搓 HTTP一句话Koog Kotlin AI Agent 工具 工作流 可观测性全部塞进一个依赖里。三、核心概念概念Koog 原语本项目对应Agent自主 LLM 调用者AIAgentCarControlAgent.create()Executor绑定 LLM 服务商simpleOpenAIExecutor/MultiLLMPromptExecutorVolcanoArk.createExecutor()LLM 模型描述LLModelVolcanoArk.createModel()工具LLM 可调用函数Tool/Tool/ToolRegistry空调 MCP 工具set_hvac等系统提示词AIAgent(systemPrompt…)CarControlAgent.SYSTEM_PROMPT策略多步编排singleRunStrategy/strategy { … }图默认单轮工具调用maxIterations12四、主要功能原生 Kotlin DSL 构 AgentAIAgent { … }类型安全。工具系统Tool注解的suspend函数或ToolRegistry框架自动生成 JSON Schema给 LLM。MCP 集成直接把 MCP Server 暴露的工具挂到 Agent。多 LLM 统一接入OpenAI / Anthropic / Google / Ollama / OpenRouter本地模型也支持。持久化记忆 历史压缩跨会话保留知识长对话自动压缩省 token。图工作流用节点边编排复杂多步逻辑含 GOAP 规划器。可观测性OpenTelemetry Langfuse / WB Weave追踪每次工具调用。流式 并行工具调用内置重试 / 超时 / 容错LLM 热切换不丢历史。五、快速上手5.1 引入依赖// build.gradle.ktsdependencies{implementation(ai.koog:koog-agents:1.2.0)}5.2 最简 Agentfunmain()runBlocking{valagentAIAgent(executorsimpleOpenAIExecutor(System.getenv(OPENAI_API_KEY)),systemPrompt你是一个简洁的车控助手。,llmModelOpenAIModels.Chat.GPT4o,)println(agent.run(把空调调到 24 度))}5.3 接入自定义 OpenAI 兼容端点valclientOpenAILLMClient(apiKeyapiKey,settingsOpenAIClientSettings(baseUrlhttps://api.siliconflow.cn,// ⚠️ 不带 /v1chatCompletionsPathv1/chat/completions,),)5.4 挂工具valagentAIAgent(executorexecutor,llmModelmodel,systemPromptprompt,toolRegistryToolRegistry{tool(setHvacTool)},)// 工具被调用后结果自动回填上下文Koog 自动继续下一轮直到给出自然语言结论六、在 CarAgent 中的集成6.1 模块归属:core依赖koog-agents 1.2.0是车控 Agent 的大脑。:core同时依赖:hvac-mcpMCP 工具实现与 MCP SDK 0.11.1Koog 传递要求。双宿主复用:server桌面 Netty与:app车机 CIO共用同一份:core零重复。这正是 Koog 的KMP 特性带来的好处。6.2 LLM 接入 ——core/.../llm/VolcanoArk.ktVolcanoArk是历史命名最初接火山方舟本质是通用 OpenAI 兼容适配器当前指向硅基流动。// 构造指向 OpenAI 兼容端点的 Koog 客户端funcreateClient(apiKey:String?null,baseUrl:String?null):OpenAILLMClient{valsettingsOpenAIClientSettings(baseUrlresolveBaseUrl(baseUrl),// 默认 https://api.siliconflow.cnchatCompletionsPathv1/chat/completions,)returnOpenAILLMClient(apiKeyresolveApiKey(apiKey),settingssettings,httpClientFactoryKtorKoogHttpClient.Factory(),// 显式指定避免 ServiceLoader 多后端冲突)}// 构造多 provider 执行器funcreateExecutor(apiKey:String?null,modelId:String?null):MultiLLMPromptExecutor{valclientcreateClient(apiKey)modelId?.let{createModel(it)}returnMultiLLMPromptExecutor(LLMProvider.OpenAItoclient)}三级覆盖换服务商不必重编译baseUrlARK_BASE_URL环境变量 ark.baseUrl系统属性 常量modelARK_MODELark.model 常量Qwen/Qwen3.5-4BkeyARK_API_KEYark.apiKey 常量兜底仅用于本地骨架自测生产务必走环境变量6.3 Agent 构建 ——core/.../agent/CarControlAgent.ktfuncreate(executor:MultiLLMPromptExecutorVolcanoArk.createExecutor(),llmModel:LLModelVolcanoArk.createModel(),toolRegistry:ToolRegistry?null,maxIterations:Int12,):AIAgentString,StringAIAgent(promptExecutorexecutor,llmModelllmModel,systemPromptSYSTEM_PROMPT,// 车控话术 硬性安全护栏temperature0.0,// 车控要稳定可复现不需要创造性toolRegistrytoolRegistry,maxIterationsmaxIterations,)SYSTEM_PROMPT含硬性安全护栏越界值拒绝、行驶态敏感操作提示停车、敏感操作先确认不依赖模型自觉。temperature0.0车控指令解析要稳定。maxIterations12防工具调用陷入死循环。6.4 工具接入MCP空调能力由:hvac-mcp以 MCP 工具暴露set_hvac/get_hvac_status经HvacMcpConnector接入:core桌面/联调stdio 子进程或进程内内存管道自研InProcessMcpTransport车机生产经 AIDL 调用黄乾的 VehicleMcpServer见docs/车控调用MCP Client集成指南.md。七、关键踩坑点本项目实测baseUrl 绝不能带/v1Koog 的chatCompletionsPath已含v1最终 URL baseUrl / chatCompletionsPath。带/v1会拼成/v1/v1/chat/completions→ 404。服务商文档给的url含/v1是调用方视角基址接入时要剥掉末尾/v1。LLModel能力声明必须同时写全capabilitieslistOf(LLMCapability.Completion,// 通用补全执行链前置检查LLMCapability.OpenAIEndpoint.Completions,// 指明走 /v1/chat/completions缺了报 Cannot determine proper LLM paramsLLMCapability.Tools,// 车控依赖 Function CallingLLMCapability.Temperature,)只写Completion漏OpenAIEndpoint.Completions报错信息像模型不认识实为没声明走哪个端点极易误判。maxOutputTokens不要调太小若模型是推理模型思维链 token 与正文 token 共用该额度。额度不足时思考过程吃光额度content返回空串且finish_reasonlength表现得像模型不说话。实测 32 翻车保持4_096。显式指定 HTTP 后端OpenAILLMClient(..., httpClientFactory KtorKoogHttpClient.Factory())。Koog 的 ServiceLoader 自动发现要求 classpath “有且只有一个” HTTP 后端显式指定可避免引入 OkHttp / JDK HttpClient 时冲突。Android 离线 KMP 适配:app需强制 KMP 变体为 jvm放afterEvaluateKGP 会覆盖顶层写法、排除kotlinx-coroutines-android、排除 OkHttp multi-release jar 冲突。绝不能排除*.kotlin_module与META-INF/services/*。详见app/build.gradle.kts注释。八、版本与依赖对齐库版本关系koog-agents1.2.0Agent 内核传递要求 MCP SDK 0.11.1ktor3.3.3A2A 通信层:serverNetty /:appCIOmcp kotlin sdk0.11.1车控工具层与 Koog 传递版本必须一致否则NoSuchMethodError换版本要连带验证Koog 内部依赖特定 Ktor 主版本MCP SDK 的协程/Kotlin 版本也要对齐。单独升级其中一个易引发运行时NoSuchMethodError或序列化不兼容统一在libs.versions.toml锁版本。九、参考资源官方概览https://jetbrains.github.io/koog-docsKotlin AI 应用开发https://kotlinlang.org/docs/kotlin-ai-apps-development-overview.html可观测性实践https://kotl.in/build-ai-agent-3本地模型Ollama / Docker Model Runnerhttps://www.docker.com/blog/build-a-recipe-ai-agent-with-koog-and-docker/