Koog(2) —— Koog Agent 的编程模型 - SharpCJ
内容提要
本文介绍 Koog 编程模型：先以最小 Agent 示例说明如何创建 LLM Client 与 Model，再创建 AIAgent 并调用 run。Koog Agent 由 prompt executor、strategy、tools、features 构成，可通过构造参数或 AIAgentConfig 配置 system prompt、temperature、maxIterations 等。Agent 类型包括 Basic、Graph-based、Functional、Planner（LLM 与 GOAP），适用于不同场景。
延伸解读
从最小示例理解 Koog 的编程模型
文章给出的最小 Agent 示例展示了 Koog 的核心调用链：先创建 LLM Client 和 LLModel，再构造 AIAgent，最后调用 run。这体现了 Koog 将模型调用、Agent 执行和结果返回分离的设计。读者可以借此快速验证本地或在线模型是否可用，并理解 promptExecutor 与 llmModel 是 Agent 运行的必要输入。
配置 Agent 的两种方式与关键参数
Koog 支持通过构造参数或 AIAgentConfig 配置 Agent。systemPrompt 用于设定角色和任务上下文，temperature 控制生成随机性，maxIterations 限制执行步数以避免无限循环。文章示例显示，修改 systemPrompt 后模型输出明显变化，说明这些参数直接影响 Agent 行为。统一使用 AIAgentConfig 可以更细粒度地管理提示、模型和执行参数。
不同 Agent 类型的适用场景与取舍
Basic Agent 使用预定义策略，适合常见场景和入门理解。Graph-based Agent 将行为建模为显式状态机，节点表示 LLM 调用或工具执行，边表示数据流，适合需要明确工作流和状态持久化的场景。Functional Agent 用函数描述逻辑，原型开发更快，但可控性较弱。Planner Agent 分为 LLM-based 和 GOAP，适合多步骤复杂任务，其中 GOAP 基于预定义目标和动作进行算法规划，可控性较高但灵活性较低。
工具调用与事件处理的实际作用
文章通过 likeDog 工具示例展示了 Koog 的 tools 机制：在 LLModel 中声明 LLMCapability.Tools，并通过 ToolRegistry 注册工具。Agent 可根据 systemPrompt 引导调用工具，并将结果返回给 LLM 生成最终回答。EventHandler feature 则用于调试和链式交互，例如 onToolCallStarting 可以打印工具调用信息，帮助观察 Agent 内部执行过程。
Q&A
Koog Agent 由哪些核心概念构成？
Koog Agent 围绕四个核心概念构建：prompt executor 负责模型调用，strategy 定义流程，tools 提供外部能力，features 提供运行时增强。
如何创建一个最小可运行的 Koog Agent？
核心步骤：创建 LLM Client 和 LLM Model，然后创建 AIAgent，最后调用 agent.run()。示例中先创建 OpenAILLMClient 和 LLModel，再创建 AIAgent 并运行。
Koog 中如何配置 Agent 的 system prompt 和 temperature？
可以通过 AIAgent 构造方法参数传入 systemPrompt 和 temperature，也可以通过创建 AIAgentConfig 来配置，后者支持更细粒度地定义 prompts、LLM 参数等。
Koog 的 maxIterations 参数有什么作用？
maxIterations 用于限制 Agent 执行的最大步骤数，默认 50，避免无限循环。如果预计需要更多步骤（如 tool calls 和 LLM requests），可以增加此限制；对于简单任务也可以降低。
Koog 支持哪些类型的 Agent？分别适用于什么场景？
Koog 提供 Basic Agent（预定义 strategy，适合常见场景）、Graph-based Agent（显式状态机，适合需要明确工作流、状态持久化和组合式结构的场景）、Functional Agent（将逻辑实现为函数，适合快速原型开发）、Planner Agent（包括 LLM-based 和 GOAP，适合复杂多步骤任务）。
GOAP Planner 和 LLM-based Planner 有什么区别？
LLM-based Planner 使用 LLM 生成和评估计划；GOAP Planner 使用算法式规划（类似 A* 搜索），基于预定义的目标和动作自动发现最优动作序列，不依赖 LLM。
在 Koog 中如何为 Agent 添加工具（tools）？
使用 @Tool 和 @LLMDescription 注解定义工具函数，然后在创建 AIAgent 时通过 toolRegistry = ToolRegistry { tool(::函数名) } 注册，同时需要在 LLModel 的 capabilities 中声明 LLMCapability.Tools。
Koog 的 EventHandler feature 有什么用途？如何安装？
EventHandler 用于辅助测试和调试，并为链式 agent 交互创建 hooks。在 agent 构造函数 lambda 中调用 handleEvents() 函数安装并注册事件处理器，例如 onToolCallStarting 可以监听工具调用。
