Kiro CLI Agent配置实战：从入门到多Agent编排

最近我把一堆自动化脚本迁到了 Kiro CLI 上，用下来最顺手的还是自定义 Agent 配置。老实说，一开始我只是把它当普通命令行工具用，跑跑预设命令就收工。后来真正动手写 agent.yaml，才意识到这工具的扩展性比想象中强很多。

如果你平时靠命令行处理重复任务，或者正在找一个能把 AI 能力固化进工作流的工具，Kiro CLI 的可自定义 Agent 值得研究。它解决的核心问题，是把“用什么模型、扮演什么角色、允许调用哪些工具、按什么格式输出”这些参数统一封装成一个可复用、可版本化的配置单元。开发者、运维、测试，包括做自动化流程的人，都能用得上。

这篇文章不会复述官方文档，更多是我在实际配置中踩坑后的整理。我会从 Agent 模型讲到安装初始化，再到完整配置一个 Agent，最后是工具扩展、多 Agent 编排和排错技巧。对没接触过 CLI Agent 的人来说，按文中步骤走一遍就能跑起来；对已经上手的人来说，后面几节的坑应该能帮你少走弯路。

1. Kiro CLI 的配置设计：先弄懂 Agent 模型

1.1 Agent 在 Kiro CLI 中的定位

在 Kiro CLI 里，Agent 不是一个神秘的概念，它就是一组配置的打包产物。一个 agent 文件会把这些内容封装在一起：模型标识、系统提示词、可调用工具、运行参数、上下文策略。当你在命令行执行kiro run <agent-name>的时候，CLI 会加载这个配置，构建出一个可交互的执行单元。

我习惯把它理解成“按需雇佣的临时员工”。你给它写清楚岗位描述（role），工作手册（prompt），再给它分配好办公工具（tools），然后它就能独立处理一类任务。和直接调用模型 API 相比，普通调用每次都像新招一个没经验的实习生，你需要重新交代背景、格式、边界；而自定义 Agent 相当于把背景和经验写进了员工手册，一次配好，反复用。

这里有一个容易被忽略的点：自定义并不是为了“造一个更聪明的模型”，而是为了让模型输出更贴合你的业务上下文。比如同一个 LLM 底座，用在不同项目里，行为可以完全不同——一个 Agent 被训练成只输出 RFC 风格文档，另一个 Agent 专注于找代码里的安全漏洞。Kiro CLI 的自定义机制，本质上是在模型外面包了一层可控的“工作协议”。

1.2 三层配置与加载优先级

Kiro CLI 的配置体系是分层的，我第一次用的时候没注意优先级，结果项目配置里写的参数始终不生效，排查半天才发现是被用户层配置覆盖了。整体来说有三层：

这个优先级的设计逻辑其实很合理：项目配置需要进 Git，方便团队共享；用户配置不进 Git，允许每个人在不改项目文件的前提下覆盖个人偏好。例如团队项目里锁定了temperature: 0.2，但你想在本地调试时用0.7，只要在用户配置里写同样的 key，加载时就会把项目设置顶掉。

我建议在排查配置问题时，先别急着改文件，而是用kiro config inspect之类的命令看看最终合并结果。多数“配置没生效”的情况，问题都出在这三层优先级上，而不是字段写错。

1.3 为什么我推荐把 Agent 配置写成文件

可能会有人问：Kiro CLI 难道不支持交互式配置？支持，但我强烈建议以文件为主。文件配置的核心价值不在“省事”，而在“可复现”。交互式设置适合临时微调，但没法进 Git，也没法做 code review。而 agent.yaml 写下来之后，你可以清晰地看到这个 Agent 的行为边界，可以对比历史版本，可以放到项目里让团队成员复用。

还有一点是注释。我在自己的 agent.yaml 里写满了注释：为什么 temperature 要设成 0.3，哪些工具是后来删掉的，prompt 里哪个段落是为了解决什么 case 才加的。三个月后回来看，这些注释比任何文档都有用。命令行交互配置做不到这一点。

文件配置还能顺便解决“环境一致性”问题。同一个 Agent 文件，在本机、CI、服务器上加载，行为完全一致，最多通过环境变量切换模型或密钥。这种可移植性，是自定义 Agent 能真正嵌入自动化流程的前提。

2. 安装与基础使用：从零开始跑通第一个 Agent

2.1 安装方式和版本选择

Kiro CLI 的安装方式很常规，我试过几种，简单列一下供参考。第一种是脚本安装，适合快速体验，官方文档会提供一条命令，复制到终端执行就行；第二种是二进制包下载，适合离线环境，下载后解压放到 PATH 目录即可；第三种是通过包管理器安装，适合本身就在特定发行版环境里的用户。

# 脚本安装示例（实际地址以官方文档为准） curl -sSL https://get.kiro.example/install.sh | bash

安装完成后先别急着用，检查一下版本：

kiro --version

我对这类工具的建议是：固定版本，不要盲目追求 latest。Kiro CLI 迭代节奏不算慢，新版本有时会调整配置格式或者命令名称。你在网上看到的教程也好，我自己写的这篇也好，都会因为版本不同出现细微偏差。固定版本之后，至少保证配置语法在一个时间段内是稳定的。

2.2 初始化项目工作区

每个项目单独建工作区，这是我踩过坑之后的结论。一开始我把所有 Agent 都放到全局目录，结果几个项目的 Agent 混在一起，命名冲突、上下文串扰，非常痛苦。后来规规矩矩在每个项目里执行初始化命令：

cd ~/projects/my-workflow kiro init

执行完成之后，项目下会多出一个.kiro/目录，结构类似下面这样：

.kiro/ ├── config.yaml ├── agents/ └── workflows/

config.yaml是这个项目的总配置，里面有几个关键项我会在写配置前先调整：默认模型、超时时间、日志级别。日志级别我通常先调成debug，因为排查问题的时候，debug 信息比什么文档都直白。等一切稳定之后，再切回info，避免刷屏。

2.3 常用命令与最小验证

跑通最小链路是学习任何工具的第一步。初始化之后，先确认核心命令能正常工作：

kiro ping kiro agent list

ping检查 CLI 自身和模型服务的连通性，agent list列出当前环境可用的所有 Agent。刚初始化时，Kiro CLI 通常会带一两个示例 Agent，可以直接拿它们验证链路。

kiro run sample-agent

执行之后，你会进入一个交互式会话。输入一句话，看看 Agent 能不能正常响应。如果这一步直接报错，大概率是模型相关配置缺失，比如没有指定模型、没有配置 API 地址。这时候不要急着写复杂的 Agent 配置，先把这条链路跑通，后面所有操作才有意义。

3. 自定义 Agent 核心配置：角色、模型与指令

3.1 一个最小可用的 Agent 配置实例

先给出一份可以直接照抄的最小配置。这个配置麻雀虽小，五脏俱全，适合用来理解字段之间的关系。

# .kiro/agents/code-review/agent.yaml name: code-review description: 项目代码审查助手，擅长发现潜在 bug 和风格问题 model: your-model-provider/your-model-name role: > 你是一名资深代码审查工程师，熟悉多种编程语言， 关注代码的可读性、可维护性和潜在缺陷。 prompt: | 你收到代码片段后，请按以下顺序输出： 1. 整体印象 2. 潜在问题 3. 改进建议 4. 总结 注意：不要输出与代码无关的内容。 temperature: 0.3 max_tokens: 2048

将文件放到.kiro/agents/code-review/目录下，然后执行kiro agent list，正常情况下列表中会出现新增的code-review。再执行kiro run code-review，给它贴一段代码，它就会按照 prompt 里定义的四个步骤输出。

我特意把temperature设成 0.3，因为代码审查是稳定性优先的任务，输出不要发散。如果你的 Agent 是做创意文案、头脑风暴之类的工作，再把温度调高，比如 0.7 到 0.9。

3.2 核心字段逐个讲透

下面这几个字段是自定义 Agent 的基础，我把它们整理成了一张速查表。

这里重点讲一下role和prompt的区别。很多人把这两个字段混在一起写，结果 Agent 行为不稳定。我的经验是：role是身份，用两三句话交代“你是谁”；prompt是操作指令，要像标准化作业指导书一样，定义输入、处理步骤、输出格式，必要的时候还要给示例。role给 Agent 提供了判断习惯，prompt给了它执行路径，两者各司其职。

3.3 用环境变量提升配置复用性

同一个 Agent 配置，在开发环境、测试环境、生产环境里往往要切换不同的模型、密钥或地址。如果这些信息直接写死在 agent.yaml 里，换环境就得改文件，很容易出错。推荐的做法是用环境变量插值，运行时不传，自动读取当前环境。

model: ${KIRO_DEFAULT_MODEL}

运行时这样指定：

export KIRO_DEFAULT_MODEL="your-model-provider/your-model-name" kiro run code-review

类似地，API 密钥、超时时间、某些开关都可以用这种方式管理。写配置时还可以给环境变量设默认值，比如timeout: ${KIRO_TIMEOUT:-60}，当环境变量没有设置时，自动用60。这个语法在 Kiro CLI 配置里很常见，活用之后，一套 Agent 配置可以适应多套环境，不用复制多份文件。

3.4 配置校验与常见报错

写完配置不要直接跑，先校验。Kiro CLI 有专门的校验命令，我很早之前不知道，每次都是运行时报错再回头改，浪费了不少时间。

kiro config validate kiro agent inspect code-review

validate负责检查整体格式，inspect能看到某一个 Agent 解析之后的最终配置，包括环境变量替换后的值。第一次用的时候，我把 YAML 缩进写错了，validate直接报出解析错误，才意识到该用编辑器统一格式化。

这里整理一些常见的配置报错，都是我在实际使用中遇到的：

配置校验这个习惯，建议从第一天就养成，能省掉很多低级错误排查时间。

4. 工具扩展与多 Agent 协作：把 Agent 真正用起来

4.1 自定义工具：把本地脚本暴露给 Agent

Agent 如果只能聊天，价值会大打折扣。Kiro CLI 最核心的扩展能力就是自定义工具——你可以把任意本地脚本封装成一个工具，让 Agent 在对话过程中按需调用。配合模型的能力，这等于给 Agent 装上了“手”，而不只是“嘴”。

定义工具的方式有两类：一是写在.kiro/tools/目录下的独立工具文件，二是在 agent.yaml 里直接声明。反过来，工具文件定义好后，需要让某个 Agent 用，就在该 Agent 的tools字段里引用。

先看一个最小工具定义：

# .kiro/tools/git-diff-summary.yaml name: git-diff-summary description: 获取当前 git diff 并生成变更摘要。当需要了解代码改动时使用。 command: "python3 scripts/diff_summary.py" input_schema: type: object properties: {}

然后在 agent.yaml 里声明：

tools: - git-diff-summary

这里有个非常关键的细节：description一定要写清楚“什么情况下使用”。Agent 决策是否调用工具，主要依据就是这个描述。描述太含混，它就会在错误场景调用工具，或者在正确场景下忘了调用。我把这个字段当成给 Agent 写的“工具使用说明书”，越具体越好。

4.2 多 Agent 流水线编排

单个 Agent 职责越单纯，行为越稳定。但实际业务往往需要多个能力叠加，这时候就轮到多 Agent 编排上场。

比如一个代码审查工作流，可以拆成三步：先由一个“变更分析 Agent”分析 diff，找出改动的文件和关键函数；再由一个“安全审计 Agent”针对分析结果检查安全隐患；最后由一个“报告生成 Agent”把前两步的结果整理成一份结构化的审查报告。

Kiro CLI 里可以通过 workflows 文件把这些 Agent 串起来，我常用的结构像下面这样：

# .kiro/workflows/review-pipeline.yaml name: review-pipeline description: 完整的代码审查流水线 steps: - agent: change-analyzer output_key: analysis - agent: security-auditor input_key: analysis output_key: security - agent: report-generator input_keys: [analysis, security]

每一步的输出会保存为上下文变量，下一步的 Agent 可以直接引用。这样一来，单个 Agent 不需要把所有逻辑都吞进去，整体能力反而通过流水线叠加起来。调试的时候也方便，哪一步输出不对，直接单独跑那一个 Agent 就行，不用整个链路重来。

4.3 记忆与上下文管理

很多实际场景要求 Agent 记住之前的对话内容，比如连续审查多个文件、用户在多轮对话里补充需求。Kiro CLI 的 memory 配置管的就是这件事。

memory: enabled: true window: 20 store_path: .kiro/memory/code-review.json strategy: sliding

window控制保留多少轮历史，滑出窗口的消息会被丢弃；strategy: sliding表示滑动窗口策略；store_path可以把记忆持久化到文件，下次运行还能恢复。这样 Agent 就具备了一定程度的“跨会话记忆”，非常适合有上下文依赖的工作流。

我的建议是：只有多轮对话确实需要时才开启 memory。单次任务场景，开着记忆反而浪费 token，还可能让旧上下文干扰新任务的判断。记住一句话：上下文不是越多越好，相关才重要。

5. 踩坑实录：常见问题与排查清单

5.1 Agent 输出不符合预期

这是使用 Kiro CLI 自定义 Agent 时最常遇到的问题。写好了 prompt，明确要求按格式输出，结果 Agent 还是会跑偏。我排查这类问题的顺序基本固定：先看temperature是不是太高，稳定任务高于 0.5 就容易发散；再看role和prompt是否冲突，身份设定和操作指令打架，Agent 就会摇摆；最后看 prompt 里有没有提供输出模板，越具体的模板，模型越容易模仿。

还有一个很容易忽略的因素是模型本身。同一个 prompt，在指令遵循能力强的模型上，输出可能很规范；换成另一个追求灵活性或对话风格的模型，输出就可能随意。自定义 Agent 配置里，模型选择也是行为约束的重要一环，不能只看价格和速度。

5.2 工具调用失败路径问题

自定义工具最常见的问题不是脚本本身写错，而是路径不对。Kiro CLI 执行工具命令时，它的工作目录不一定是你执行kiro run时的当前目录，尤其是当项目结构比较复杂时，相对路径经常会飘。

我的处理原则是：在command里尽量写绝对路径，或者先用cd切到项目目录再执行。比如：

command: "cd /path/to/project && python3 scripts/diff_summary.py"

另外，脚本权限也要注意。command直接指定脚本时，脚本得具备可执行权限。排查这类问题时，可以用 Kiro CLI 提供的工具测试命令单独验证，不带 Agent，直接看工具本身能不能跑通。这样能快速定位问题出在工具定义上，还是出在 Agent 的决策逻辑上。

5.3 配置优先级导致的困惑

分层配置设计虽然合理，但也给排查增加了难度。我遇到过一次很典型的案例：项目里的 Agent 配好了模型，运行后却始终用的是另一个模型，查了半天，最后发现是用户配置里的一段覆盖设置。原因是用户配置的优先级高于项目配置，两个文件里都有model字段，后者的生效值替换了前者。

这个问题的解法很简单：不要靠肉眼判断生效值，直接用kiro config inspect看合并之后的结果。配置文件多的时候，人的记忆是不可靠的，工具的输出才是唯一标准。

5.4 性能与成本优化

Agent 配置越来越复杂之后，性能和成本问题会逐渐浮出水面。我有几个实际优化经验：

第一，限制工具数量。工具列表越长，Agent 决策时需要考虑的选项就越多，响应延迟和出错率都会上升。把用不到的工具从列表里移除，效果立竿见影。

第二，控制上下文大小。开 memory 或传长文本时，token 消耗会快速上涨。纯单次任务就别开记忆，输入内容尽量只保留必要部分，避免把整个知识库塞进对话。

第三，利用缓存。Kiro CLI 有响应的缓存开关，相同输入、相同配置的情况下，可以直接命中缓存，省掉一次模型调用。对于反复测试的场景，这个开关能节约不少时间和成本。

最后，任务拆分也会影响成本和延迟。一个大而全的 Agent 可能一次调用就完成任务，但输出质量不稳定；拆成多个小 Agent 串行执行，单次调用成本低了，整体延迟却可能变高。没有绝对最优方案，只能根据你的实际业务取舍。

写到最后，分享一点个人体会。刚开始用 Kiro CLI 的时候，我总想配置一个万能 Agent，结果它什么都做不好，每次输出都像隔靴搔痒。后来学会了拆：一个 Agent 只做一件事，把职责收敛清楚，行为反而稳定得多。自定义 Agent 的本质，不是把智能堆在一起，而是把流程拆到可管理。

再分享一个小技巧：每次调整配置后，把当时的输入输出对保存成样例，放在 agent 目录的examples/下。下次要调试时，直接跑样例就能判断这次改动有没有改坏，不用重新设计测试输入。这个习惯帮我节约了大量反复测试的时间。