Kiro CLI 自定义 Agent 完整指南：从配置文件到实战调优

这两年命令行工具越来越像瑞士军刀各种自动化脚本、AI 辅助工具层出不穷但真正能让你把 Agent 用出生产力的不是开箱即用的默认行为而是自定义配置的能力。Kiro CLI 这个工具我断断续续用了小半年越用越觉得它在「自定义 Agent」这件事上下足了功夫。一句话说清楚它是什么Kiro CLI 是一个跑在终端里的命令行框架用来定义、调试、运行你自己的 Agent。你可以把平时反复手写的一套提示词、工具调用、上下文策略固化成一个配置文件然后像执行命令一样随时调起来跑。它不是那种装完就帮你干活的傻瓜工具而是给你一块画布让你把自己脑子里那套处理任务的思路翻译成 Agent 能理解、能执行的规则。配置完成后Agent 的行为边界、工具选择、对话策略都是你说了算。适合谁用我个人的建议是如果你经常写脚本处理文本、定期整理数据、或者需要跟各种 API 打交道并且厌倦了每次重新写一套提示词那 Kiro CLI 值得你花一下午研究。接下来我把这段时间的实践整理成这篇指南从配置文件结构、核心参数到底层逻辑、踩坑实录都在里面了。1. 先从使用场景说起Kiro CLI 到底在解决什么问题1.1 没有 Agent 框架时我们的日常工作是什么样的回想一下以前没有这类工具时我是怎么处理任务的。当前我需要定期把几十个 Markdown 文档里的小标题提取出来按层级生成一份目录摘要。这个过程本身不复杂但我每次都得打开编辑器复制一段自己存了不知道多久的提示词模板替换掉文件名和输出路径然后粘贴到某个对话窗口里等结果出来再手动整理成文件。麻烦而且极其容易出错——提示词里有一个引号没转义或者文档里出现了特殊字符整个输出就乱了。我一度想过写死一个脚本来处理但问题在于任务需求经常变有时候只需要一级标题有时候需要带上链接锚点有时候还要统计每个标题下面的段落字数。写死脚本的逻辑改一次需求就要改一次代码灵活度太低。1.2 Kiro CLI 换了一种组织方式配置即 AgentKiro CLI 的思路完全不一样。它把Agent这件事拆成几个可以独立配置的模块模型参数、系统提示词、工具列表、上下文策略。每个模块不是硬编码在代码里的而是写在配置文件里用一份 YAML 就可以完整描述一个 Agent 的人设和能力边界。拿刚才那个场景举例我在 Kiro 里定义一个叫md-toc-agent的 Agent配置里写明它的职责是提取 Markdown 文档目录结构同时给出一段详细的规则说明告诉它在什么样的情况下应该保留标题层级、什么样的情况下应该忽略。然后给这个 Agent 挂上文件读取工具和文档解析工具。一切就绪后我在终端里敲一行命令传一个文档路径进去这个 Agent 就用我预设好的行为逻辑去处理了。这个过程解决了一个核心痛点把隐性经验变成了显性配置。过去我要记住每个任务对应的提示词套路现在只要看配置文件就知道某个 Agent 会怎么处理问题。长期积累下来配置文件本身就成了一笔可复用的资产。1.3 一个合适的使用边界有一点我得说清楚Kiro CLI 不是万能的自动化平台它不适合做大规模的数据处理流水线也不适合替代完整的编程框架。它的优势区间在需要大模型理解和判断的、有一定流程结构的任务上。比如你让它总结一批文档、让它在多个数据源里检索后给出对比、让它在日志里找出异常并生成报告——这些任务有清晰目标但具体执行路径需要根据内容实时调整正好是 Agent 模式发挥价值的地方。而如果你的任务是纯粹的文本替换、文件搬运那老老实实写个 Shell 脚本就够了没必要引进一个 Agent 框架增加额外开销。这个边界想清楚了用起来才会顺手。2. 配置文件基础先搞清楚 Kiro CLI 的目录结构与核心字段2.1 初始化与目录布局Kiro CLI 安装完成后第一件事是执行kiro init。它会问几个基本问题工作目录放哪里、默认模型用什么、是否启用工具沙箱。回答完之后目录里会生成这样一个结构~/.kiro/ ├── config.yaml # 全局配置默认模型、超时时间、日志级别 ├── agents/ # 每个子目录对应一个 Agent │ └── md-toc/ │ ├── agent.yaml # Agent 的定义文件 │ └── assets/ # 存放该 Agent 专用的资源文件 └── logs/ # 运行日志这个布局我挺喜欢全局配置只管基础设施agents 目录里每个 Agent 独占一个文件夹互不干扰。如果你想和朋友共享某个 Agent,直接把md-toc这个目录拷给他就行不需要动全局配置。2.2 agent.yaml 的三块核心区域打开一个agent.yaml第一感觉是字段不算少但梳理清楚后会发现其实就三大块描述 Agent 自身行为、定义运行方式、声明工具与权限。# 示例一个最简单的 agent.yaml agent: name: md-toc description: 提取 Markdown 文档的目录结构 persona: 你是一个文档结构分析专家擅长识别 Markdown 的标题层级。 instruction: | 只输出目录不要输出任何解释。 忽略代码块中的 # 字符。 model: provider: default name: default-model temperature: 0.2 runtime: max_rounds: 5 max_tokens: 2000 memory: enabled: true window_size: 20 tools: include: - file.read - markdown.parse allowlist: - workspace: ~/docs/**agent块定义的是这个 Agent 是谁、有什么职责。persona是系统提示词的一部分用来设定整体角色instruction则是你希望它执行的更具体的规则可以写很多条。runtime块定义的是这个 Agent 怎么运行。max_rounds限制它最多执行多少轮工具调用的循环防止它在一个问题上转圈max_tokens限制单次生成的输出长度memory控制上下文窗口的策略。tools块最直白告诉 Kiro 这个 Agent 能用哪些工具。这是一个安全边界也是一个职责边界。你不可能让一个负责文档结构分析的 Agent 去执行 Shell 命令那纯粹是给自己找麻烦。2.3 配置文件之间的优先级实际使用中难免会遇到一个 Agent 想用另一个 Agent 的配置或者全局配置和 Agent 配置冲突的情况。Kiro CLI 的处理规则很明确Agent 级配置覆盖全局配置命令行参数覆盖 Agent 级配置。也就是说Agent 的agent.yaml里可以指定自己的temperature覆盖全局的默认值而你在运行命令时手动指定的参数优先级最高。这个规则记住了后面很多为什么我改了配置没生效的问题就迎刃而解了。我见过有人在全局配置里把温度调到 0.8却忘了某个 Agent 自己的配置文件里写死了 0.2结果跑出来风格完全不对排查了半天才发现是作用域没搞清楚。3. 关键参数逐项拆解每个配置背后其实都是一个取舍3.1 persona 和 instruction把话说透别让 Agent 猜在自定义 Agent 这件事上我最想强调的一点是persona决定风格instruction决定边界二者各司其职不要混着写。persona我习惯写成一段两三行的角色设定用来说明 Agent 以什么身份处理问题。比如你是一名资深的数据分析师擅长从结构化数据中发现问题你的回答风格是简洁、准确优先给出可操作的结论。这段文字会被放进系统提示词的最前面帮助模型建立一个稳定的角色框架。而instruction才是真正干活的规则。它不需要文采但需要精确。我在实践里总结出一个经验规则要写怎么做而不是写不要做。不要输出多余内容这种话模型很难把握尺度但如果你写只输出最终的 Markdown 列表不要输出解释性文字如果文档没有可提取的标题输出一行 UPDATE_NEEDED模型的执行准确度会明显提升。另外一个非常实用的技巧是在instruction里为边界情况准备好明确的兜底动作。比如上面例子里的UPDATE_NEEDED这个动作的意义在于当 Agent 遇到无法处理的情况时它不是随便糊弄一个结果而是给出一个标准化的信号方便你后续做自动化判断。这个习惯能省掉很多调试时间。3.2 model 参数temperature 不是越小越好temperature参数看起来简单但不少人理解有偏差。它不是智商或者准确度调节器而是控制采样随机性的旋钮。值越低每次输出越保守、越接近概率最大的序列值越高输出越发散、可能更有创造性。对于大多数自定义 Agent 的任务比如文档解析、结构化提取我建议设到 0.2 左右。但如果你在做的是头脑风暴类的 Agent比如基于给定主题生成十个可能的标题方向那 0.2 就太无趣了这时候调到 0.7 到 0.9 会更合适。还有max_tokens。这个限制很多人忽略直到某一次 Agent 输出到一半被截断了才意识到问题。长文本生成任务尤其要注意Kiro 的max_tokens限制的是单轮生成的最大 token 数不是整个任务的总预算。如果你的任务需要多轮输出要结合runtime.max_rounds一起规划否则容易出现任务还没结束前面生成的中间结果已经占满预算的尴尬局面。3.3 memory 与上下文策略从小窗口到滑动窗口Agent 的上下文处理策略直接决定了它在复杂任务里的表现。Kiro 的memory模块有两种基本模式关闭和开启。关闭时每一轮工具调用之间不会保留历史消息记录。好处是节省上下文空间、降低 token 消耗坏处很明显——Agent 不记得它自己上一步干了什么一旦任务需要连续多步操作就会出现一步一断的问题。开启时你可以设置window_size比如 20。这个参数表示 Model 在处理新一轮输入时能回看最近 20 条消息。它相当于给 Agent 装了一个短期记忆。实际项目中我习惯分场景处理如果 Agent 做的事情是一次性的文本分析例如读完这个文件后告诉我它讲了什么那我直接关掉 memory跑完即忘干净利落。如果 Agent 要做的是一个多阶段任务比如先读取这个文档提取要点再根据要点生成摘要最后把摘要中提到的所有数据整理成 JSON那window_size至少给到 30 到 50。Kiro 还支持设置更精确的 memory 策略比如只保留包含特定关键词的历史消息这个高级功能我后面会提到。3.4 关于 max_rounds 的讨论防止 Agent 原地转圈max_rounds这个参数我单独拿出来说因为它直接关系到任务能否收敛。有过 Agent 开发经验的人都知道模型在得到工具返回结果后有时候会进入一种循环怪圈——它觉得自己还没拿到足够信息于是一遍又一遍地调用同一个工具每次都得到相同的结果然后继续尝试。如果没有轮数上限这个循环会一直持续到 token 耗尽。设置合理的max_rounds本质上就是在告诉 Agent你来来回回做同样的事情最多只能做几次。超过这个数说明你需要换一种思路或者直接交出手头已有的结果。我在实践里的经验是大多数文档处理类任务max_rounds设置在 5 到 8 就足够了如果某个 Agent 频繁触发这个上限应该回头检查它的instruction是不是写得不够明确而不是简单地调大上限。4. 工具接入与权限边界给 Agent 装上手脚并拴上绳子4.1 内置工具与自定义工具的选择Kiro CLI 自带了一批内置工具涵盖文件读写、目录遍历、文本解析、HTTP 请求等常见能力。在配置文件中声明tools.include时尽量从这些内置工具里挑选够用的出来。当内置工具不够用比如你需要 Agent 能够访问某个内部接口或者解析某种特殊格式的文件那就要写自定义工具。自定义工具本质上是一个可执行文件或脚本Kiro 负责在 Agent 调用工具时把参数传进来再把执行结果返回给模型。在配置里定义时需要写明调用方式、参数格式和返回格式。下面是一个示例tools: custom: - name: health_check description: 检查服务健康状态 exec: python3 /Users/me/scripts/health.py args: host: { type: string, required: true } timeout: 10这个设计有一个值得称道的地方自定义工具的执行环境是独立于 Agent 主进程的。也就是说就算工具脚本崩溃了也不会把整个 Agent 拖垮只会影响到那一次工具调用。4.2 用 allowlist 控制工具访问范围工具不只是能不能调用的问题还有调用后能碰哪些资源的问题。Kiro 的allowlist字段针对的就是这个。比如文件读取工具如果不加限制Agent 可以读取本机任意路径的文件这显然不现实。通过在allowlist里指定workspace: ~/docs/**就限定了它只能访问~/docs目录下的文件。这个限制不仅保护了你的隐私数据也能防止 Agent 因为一次错误的路径拼接而读到意外内容导致回答偏离轨道。这是一个很重要的习惯每次给 Agent 配置一个新工具都冷静想一下这个工具实际会触及哪些资源然后把范围写到最小。安全问题和效率问题很多时候是同一件事。4.3 沙箱模式什么时候需要开启Kiro 有一个沙箱运行模式开启之后Agent 执行的所有工具操作都发生在临时目录里外部文件系统对它只读。这意味着 Agent 可以放心大胆地生成临时文件、执行中间产物不需要担心污染真实目录。我一般在做数据清洗类 Agent 时使用沙箱模式。输入文件复制进沙箱清洗完的产物先输出在沙箱里我确认没问题后再手动拷贝出来。这个流程看起来多了一步但换来的是极高的安全感——再也不用担心某次路径写错把原始数据覆盖掉了。代价是需要仔细设计工具的输入输出链。沙箱里的路径和真实路径不一样如果你配置的工具脚本里写死了绝对路径进了沙箱就会全部失效。所以开启沙箱时工具脚本尽量用相对路径或者通过环境变量接收基础目录。5. 配置落地全流程从想法到跑通一个可用 Agent5.1 用 kiro plan 先把配置结构搭出来Kiro 有一个很实用的辅助命令kiro plan。你可以在交互模式下描述你想做一个什么样的 Agent,它会结合当前工作目录的文件结构生成一份初步的配置建议。注意这不是什么黑魔法它本质上是调用默认模型帮你写了 draft 配置然后你在此基础上修改。比如我想做一个批量提取 Git 提交记录并按类型分类的 Agent,在kiro plan里描述需求后它会建议配置哪些内置工具、instruction怎么写、persona怎么定。这些建议未必完美但能让你少走很多弯路尤其是刚接触新类型 Agent 的时候有个起步方向很重要。5.2 验证配置这些坑其实都可以早点发现写完配置先用kiro validate做静态检查。它能发现 YAML 语法错误、字段名拼写错误、以及路径不存在的问题。这个命令跑起来很快反馈也很直接。但validate通过不代表配置能正常运行——它检查的是配置是否符合格式不是配置是否符合你期望的行为。所以下一步是kiro run --dry-run。dry-run 模式下Kiro 会完整地走一遍配置加载、工具注册、上下文初始化的流程但是不会真正调用外部的模型接口也不会让工具执行实际效果。它会打印出如果真实运行Agent 第一步会做什么、会调用哪个工具、传入什么参数这类信息。这一步的价值在于你可以在不花钱消耗模型调用的情况下尽早发现配置里的逻辑矛盾。比如你的instruction里要求 Agent 读取一个文件但tools.allowlist里根本没放行那个目录dry-run 会直接把这个矛盾暴露出来。5.3 用 kiro logs 实时观察 Agent 的每一步思考当配置真正跑起来遇到问题时学会看日志是必备技能。Kiro 的日志不仅记录报错信息还记录 Agent 每一步的执行过程系统提示词最终长什么样、模型生成了什么内容、Agent 选择了哪个工具、工具的返回结果是什么、下一步策略为什么这样调整。这些信息在logs/目录里按日期和 Agent 名字组织。我在调试一个 Agent 时的习惯是这样的先跑一遍看日志的整体路径是否合理如果中间某一步跳出了预期就去查那一步前后的上下文确认是instruction的引导问题还是工具返回格式的问题。大部分莫名其妙不听话的问题通过日志都能找到直接原因。如果没有详细的执行日志这种排错几乎无从下手。6. 实战把周报整理助手完整配出来这个案例很适合新手完整走一遍需求是每周五发给团队一份周报周报内容需要从当周的 Git 提交记录、任务管理工具里的待办事项、以及会议笔记中整理汇总。我以前都是手动复制粘贴各处的信息再花半小时组织语言。现在我用 Kiro 自定义一个 Agent 来完成大半工作。6.1 需求拆解这个任务有三个信息源Git 提交记录、任务事项、会议笔记。每个信息源的格式都不一样。理想情况下,我希望 Agent 依次做这些事读取本周所有 Git 提交记录通过git log工具读取任务管理工具导出的 JSON 文件读取会议笔记的 Markdown 文档将三部分信息按技术进展、项目风险、下周计划三个板块组织成周报。这个过程涉及多个工具调用步骤顺序不能乱。如果我把所有要求写在一段话里让 Agent自由发挥大概率会得到一段结构不清晰的周报。所以我需要把instruction写得像一份操作清单。6.2 完整配置示例下面是我实际用下来的一个版本略去了敏感信息只保留框架agent: name: weekly-report description: 从 Git 提交、任务清单和会议笔记中生成周报 persona: 你是一名资深的团队助理擅长从零散信息中提炼结构化要点。 instruction: | 请严格遵守以下步骤执行任务 第一步执行 git log 工具参数为 --since本周一 --until本周日 --prettyformat:%h|%an|%s 获取本周提交记录并记录成列表。 第二步读取任务文件 weekly_tasks.json注意只保留 status 为 done 或 in_progress 的事项。 第三步读取会议笔记 meeting_notes.md提取标题为本周讨论之下的所有列表项。 第四步将以上信息汇总按照技术进展 / 项目风险 / 下周计划三个板块输出。 每个板块用 Markdown 无序列表组织不要额外添加开场白和结束语。 如果第三步没有找到本周讨论章节跳过该板块并在输出末尾加上一行会议记录缺失。 model: provider: default name: default-model temperature: 0.3 runtime: max_rounds: 6 memory: enabled: true window_size: 40 tools: include: - git.log - file.read allowlist: - workspace: ~/work/logs/**从配置里你能看到,我把任务拆成了四个明确步骤每一步做什么、调用什么工具、读取哪个文件都写清楚了。这一步操作对于最终输出质量的影响比任何参数调优都更关键。6.3 运行效果和调整记录第一次运行我就遇到了一个小问题Git 提交记录里包含了团队所有人的提交但周报需要按个人分组而我最初的instruction里没写这个要求。Agent 默认的做法是把所有提交混在一起按时间顺序排列。后来我在 instruction 的第二步补充了说明按提交者姓名分组组内按时间排序输出就完全符合预期了。第二个问题是会议笔记的格式偶尔不标准。有时候本周讨论写成本周讨论内容有时候标题下有嵌套的子标题。Agent 对标准格式处理得很好但一旦遇到变体格式就开始发挥创造力。最后我的解决办法很简单在 instruction 里增加了容错规则——如果找不到完全匹配的标题就查找包含本周讨论字样的任意列表项。加了这条之后容错能力明显提升。7. 排查手册我在这段时间里踩过的几个典型问题7.1 工具调用成功但 Agent 就是没用结果有一次我配置的 Agent 需要读取一份 PDF 文件并提取其中的表格数据。日志显示pdf.parse工具调用成功了返回了完整的数据但 Agent 最终的输出却说未发现表格信息。排查过程很有意思。我先去看工具返回的数据格式原来 PDF 里的表格数据被解析后存放在一个嵌套比较深的 JSON 结构中。Agent 调用了工具也看到了返回内容但在理解时只扫了一眼表层结构没往下深挖。这个问题本质上不是工具的问题而是模型在读完返回结果后没有按预期把嵌套数据展开。解决方案有两个方向一是优化返回格式让工具脚本解析时把表格的关键信息提取成平铺结构二是在instruction里加一句仔细检查工具返回的完整 JSON 数据不要只关注第一层字段。我最后选了后者因为这样不用改工具脚本配置文件的迭代成本更低。7.2 Agent 上下文被大量日志刷爆当 Agent 在循环中多次使用同一个工具时工具每轮返回的结果都会被加入记忆窗口。如果工具返回的是很长很长的内容比如一大段日志或完整文件内容几轮下来上下文窗口就被占满了后面的关键信息反而进不来。Kiro 有一个记忆压缩选项开启后旧的历史消息会被某种摘要机制压缩成精简描述腾出上下文空间给新的工具结果。我建议凡是涉及大文件读取、大日志扫描的 Agent务必开启记忆压缩并把压缩阈值调低一些保证信息吞吐更流畅。7.3 一个配置到处复制最后无法维护自定义 Agent 用多了以后配置文件之间的复制粘贴会带来很大的维护问题。我自己就踩过更新了某个工具的参数格式结果三个 Agent 都声明了同一个工具旧格式却在其中一个 Agent 里保留着一跑就报错。后来我把公共的工具定义抽到了全局config.yaml里Agent 的agent.yaml里只声明要使用哪些工具不再重复定义工具细节。修改工具时只改一处所有关联的 Agent 自动生效。这相当于把公共逻辑从配置里提炼出来了维护成本降了一个量级。如果你管理的 Agent 数量在五个以上强烈建议在最初搭建时就规划好公共配置和 Agent 专属配置的边界不然后面改起来真的会崩溃。Kiro CLI 自定义 Agent 的玩法写到这里已经覆盖了从配置文件结构、参数语义、工具接入到真实案例的完整链路。最后分享一条我自己的体会配置 Agent 最耗费精力的往往不是写参数而是反复理解它为什么会这么做。Kiro 的执行日志是理解 Agent 行为最快的入口遇到任何异常第一件事永远是打开对应时段的日志从系统提示词开始顺序往下读一遍大部分问题都会在这个过程中浮现答案。这个习惯坚持下来配置效率会有非常明显的提升。