Koog(4)—— Agent Skills 和 Tools - SharpCJ
内容提要
本文介绍 Koog Agent 中 Skills 与 Tools 的用法。Skills 从文件系统发现可复用能力包并生成提示词；Tools 是执行器，分为内置、注解和基于类三种。内置工具用于人机交互，注解工具通过 @Tool 声明，基于类工具可完全自定义。文中还讲解了工具注册、调用、并行调用以及将子 Agent 包装为工具的方法。
延伸解读
Skills 与 Tools 的职责边界
文章用“说明书”和“执行器”来区分两者：Skills 从文件系统发现能力包并生成提示词，让模型知道有哪些招可用；Tools 则是真正动手的组件，负责调用程序、访问外部系统。这意味着 Skills 本身不执行动作，必须配合已注册的匹配工具才能生效。理解这一分工，有助于在设计 Agent 时把“能力描述”和“具体实现”分开管理，避免把提示词和工具逻辑混在一起。
三种工具类型的选型建议
Koog 提供内置、注解和基于类三种工具。内置工具随框架提供，定位在人机交互和对话管理，官方注明不用于生产，适合快速原型。注解工具通过 @Tool 声明，用反射自动生成参数 schema，适合把现成普通方法快速接入 LLM，但仅支持 JVM。基于类工具最底层、最灵活，支持 KMP 多平台，适合需要完全控制参数、元数据和执行逻辑的复杂场景。选型时应优先考虑平台兼容性和控制粒度。
并行调用与子 Agent 包装的适用场景
文章介绍了 toParallelToolCallsRaw 扩展，它能把参数流并发分发给同一个工具，只保留原始字符串结果，适合对 N 个输入做同样处理的批量查询或转换。另外，通过 AIAgentService.createAgentTool 可以把子 Agent 包装成工具，注册到主 Agent 的 ToolRegistry 中，形成层级式 Agent，让主 Agent 把子任务委托给专门子 Agent。这两种机制分别面向批量执行和任务分解，使用时需注意并发度和子 Agent 的职责划分。
Q&A
Koog Agent 中 Skills 和 Tools 有什么区别？
Skills 是“做什么的说明书 + 配套脚本”，允许 agent 从文件系统中发现可复用的能力包，并通过生成的 prompt 段落暴露给模型；Tools 是“具体动手的执行器”，用于执行特定任务或访问外部系统。模型靠 Skills prompt 知道有哪些招，靠 Tools 真正把招使出来。
如何在 Koog Agent 中使用 Skills？
使用 Skills 包含三个步骤：1. 调用 discoverSkills 从文件系统发现技能包；2. 调用 generateSkillsPrompt 生成技能提示词（如 XML 格式）；3. 将生成的提示词放入 agent 的 systemPrompt 中，并注册匹配的工具（如 ListDirectoryTool、ReadFileTool）以便 agent 列出和读取技能文件。
Koog 中有哪几种工具类型？
Koog 框架中有三种工具类型：1. 内置工具：框架预置的现成工具，用于人机交互和对话管理，需额外添加 agents-ext 依赖；2. 基于注解的工具：通过 @Tool 和 @LLMDescription 注解声明，仅支持 JVM；3. 基于类的工具：通过继承 Tool 或 SimpleTool 等基类实现，可完全自定义，支持 KMP 多平台。
如何将工具注册到 Koog Agent 中？
需要先创建 ToolRegistry 并将工具添加进去，例如：val toolRegistry = ToolRegistry { tools(myTool) }。合并多个注册表可使用 + 运算符。然后在创建 AIAgent 时通过 toolRegistry 参数传入该注册表。
Koog 中如何并行调用工具？
可以使用 AIAgentLLMWriteSession 上的 toParallelToolCallsRaw 扩展函数。它接收一个参数流，将每个参数并发地作为一次工具调用执行，并返回原始字符串结果的 Flow。例如：listOf(WeatherArgs("北京"), ...).asFlow().toParallelToolCallsRaw(WeatherTool::class, concurrency = 3)。适合批量查询或转换场景。
如何将子 Agent 包装成工具供其他 Agent 调用？
使用 AIAgentService 的 createAgentTool 方法。先创建 AIAgentService 实例，然后调用 createAgentTool 并传入 agentName、agentDescription、inputDescription、inputType 等参数，得到 Tool 对象。之后将该工具添加到另一个 Agent 的 ToolRegistry 中即可。调用时，子 Agent 会执行并返回结果。
