Kiro CLI Agent 配置参考说明 custom agent JSON 文件的主要字段。你可以定义 agent 名称、prompt、MCP servers、可用 tools、免确认 allowedTools、resources、hooks、模型、快捷键和欢迎语，从而把不同工作流固化为专用 agent。

Kiro CLI Agent 配置参考：tools、resources、hooks 和模型设置

Kiro CLI custom agent 通过 JSON 配置文件定义行为。文件名通常就是 agent 名称，也可以在 name 字段中显式指定。

这份配置参考适合在你已经理解 custom agents 价值后使用：先从最小可用配置开始，再逐步增加 tools、resources、hooks 和 MCP。

核心字段总览

Agent 配置可以包含这些字段：

字段	作用
name	agent 名称，可选，未写时从文件名推导
description	agent 用途说明
prompt	agent 的高层上下文，类似 system prompt
mcpServers	agent 可访问的 MCP servers
tools	agent 可用 tools
toolAliases	处理工具命名冲突或缩短工具名
allowedTools	无需确认即可使用的 tools
toolsSettings	针对具体 tool 的配置
resources	agent 可用资源：files、skills、knowledge bases
hooks	agent 生命周期和工具调用时运行的命令
includeMcpJson	是否包含 mcp.json 中的 MCP servers
model	agent 使用的模型 ID
keyboardShortcut	快速切换到该 agent 的快捷键
welcomeMessage	切换到 agent 时显示的欢迎语

name 和 description

name 用于识别和展示：

{
  "name": "aws-expert"
}

description 帮助用户区分不同 agents：

{
  "description": "An agent specialized for AWS infrastructure tasks"
}

描述要写清“什么时候用这个 agent”，否则团队成员很难选择正确 agent。

prompt

prompt 是 agent 的高层上下文，可以写内联文本：

{
  "prompt": "You are an expert AWS infrastructure specialist"
}

也可以引用外部文件：

{
  "prompt": "file://./my-agent-prompt.md"
}

相对路径会相对于 agent 配置文件所在目录解析；绝对路径会直接使用。长 prompt 建议拆到独立文件，便于版本管理。

mcpServers

mcpServers 定义 agent 可访问的 MCP servers：

{
  "mcpServers": {
    "git": {
      "command": "git-mcp",
      "args": [],
      "env": {
        "GIT_CONFIG_GLOBAL": "/dev/null"
      },
      "timeout": 120000
    }
  }
}

常见字段：

• command：必填，启动 MCP server 的命令。
• args：可选，命令参数。
• env：可选，环境变量。
• timeout：可选，MCP 请求超时，默认 120000ms。
• oauth：可选，HTTP MCP server 的 OAuth 配置。

HTTP MCP server 需要 OAuth 时，可以配置 redirectUri 和 oauthScopes。

tools

tools 列出 agent 可以使用的工具：

{
  "tools": [
    "read",
    "write",
    "shell",
    "@git",
    "@rust-analyzer/check_code"
  ]
}

工具引用规则：

• Built-in tools：直接写名称，例如 read、shell。
• MCP server 所有工具：@server_name。
• MCP server 单个工具：@server_name/tool_name。
• 所有工具：*。
• 所有 built-in tools：@builtin。

toolAliases

当不同 MCP servers 有同名工具时，用 toolAliases 改名：

{
  "toolAliases": {
    "@github-mcp/get_issues": "github_issues",
    "@gitlab-mcp/get_issues": "gitlab_issues"
  }
}

也可以把很长的工具名缩短，例如把 CloudFormation 部署工具改成 deploy_cf。

allowedTools

allowedTools 表示无需用户确认即可使用的工具：

{
  "allowedTools": [
    "read",
    "@git/git_status",
    "@server/read_*",
    "@fetch"
  ]
}

支持精确匹配和 glob 风格通配符：

• * 匹配任意字符序列。
• ? 匹配单个字符。
• 精确匹配优先于 pattern。
• @server_name 表示允许该 server 的全部工具。
• 匹配区分大小写。

注意：allowedTools 不支持用 "*" 允许所有工具。要免确认使用工具，必须写具体工具、server 或 pattern。

toolsSettings

toolsSettings 为具体 tool 提供配置：

{
  "toolsSettings": {
    "write": {
      "allowedPaths": ["src/**", "tests/**"]
    },
    "shell": {
      "allowedCommands": ["git status", "npm test"],
      "deniedCommands": ["git push .*"],
      "autoAllowReadonly": true
    }
  }
}

它适合限制 write 路径、shell 命令、AWS services 等高风险能力。

resources

resources 给 agent 提供上下文资源：

{
  "resources": [
    "file://README.md",
    "file://.kiro/steering/**/*.md",
    "skill://.kiro/skills/**/SKILL.md"
  ]
}

资源类型：

• file://：启动时直接加载到上下文。
• skill://：启动时只加载 metadata，完整内容按需加载。
• knowledgeBase：索引大型文档或代码库，按需搜索。

Knowledge base 示例：

{
  "resources": [
    {
      "type": "knowledgeBase",
      "source": "file://./docs",
      "name": "ProjectDocs",
      "description": "Project documentation",
      "indexType": "best",
      "autoUpdate": true
    }
  ]
}

大文档集不要直接塞进 file://docs/**/*.md，更适合 knowledge base。

hooks

hooks 可以在 agent 生命周期或工具调用前后运行命令：

{
  "hooks": {
    "agentSpawn": [
      { "command": "git status" }
    ],
    "preToolUse": [
      {
        "matcher": "execute_bash",
        "command": "{ echo \"$(date) - Bash:\"; cat; } >> /tmp/audit.log"
      }
    ],
    "postToolUse": [
      {
        "matcher": "fs_write",
        "command": "cargo fmt --all"
      }
    ]
  }
}

可用触发点：

• agentSpawn
• userPromptSubmit
• preToolUse
• postToolUse
• stop

preToolUse 和 postToolUse 的 matcher 使用内部工具名，例如 fs_read、fs_write、execute_bash、use_aws。

includeMcpJson

{
  "includeMcpJson": true
}

设为 true 时，agent 会同时加载全局和当前 workspace 的 MCP 配置文件中的 servers。安全敏感场景建议显式控制，而不是盲目继承所有 MCP。

model、快捷键和欢迎语

指定模型：

{
  "model": "claude-sonnet-4"
}

如果模型不可用，Kiro 会回退到默认模型并显示 warning。

配置快捷键：

{
  "keyboardShortcut": "ctrl+a"
}

支持 ctrl、shift 加字母或数字。再次按同一快捷键会切回之前的 agent。冲突快捷键会被禁用。

欢迎语：

{
  "welcomeMessage": "What would you like to build today?"
}

本地和全局 agent

本地 agents：

.kiro/agents/

只在当前 workspace 及其子目录可用，适合项目规则和团队共享。

全局 agents：

~/.kiro/agents/

跨项目可用，适合个人通用工作流。

同名时，本地 agent 优先于全局 agent。

安全建议

• 从最小 tools 开始，需要时再增加。
• allowedTools 用具体 pattern，少用宽泛通配。
• write、shell、aws 一定配 toolsSettings 限制范围。
• 启用 write tools 后，agent 拥有当前用户的文件系统权限。
• Skills 是文本指令，不能自己执行代码；但如果 agent 允许 shell，就可能执行 skill 中引用的命令。
• 安装第三方 skills 和 resources 前先审查内容。

常见问题

Q: Kiro custom agent 配置文件是什么格式？

A: JSON。文件可以放在 .kiro/agents/ 或 ~/.kiro/agents/。

Q: tools 和 allowedTools 有什么区别？

A: tools 表示 agent 能看到哪些工具；allowedTools 表示哪些工具可以免确认使用。

Q: 大量文档应该放 resources 还是 knowledge base？

A: 大型文档集优先 knowledge base，避免每次启动都占用上下文窗口。