Kiro CLI Agent 示例展示了 custom agents 的常见写法：AWS infrastructure agent、development workflow agent、code review agent、项目专用 agent，以及接入 remote MCP server 的 agent。你可以从这些模板出发再收紧权限。

Kiro CLI Agent 示例：AWS、开发流、代码审查和项目专用 Agent

Custom agents 最好从具体场景出发设计，而不是一开始就做“全能 agent”。下面这些 Kiro CLI agent 示例可以作为模板：先复制思路，再按你的项目收紧 tools、allowedTools、resources 和 hooks。

AWS Specialist Agent

AWS specialist agent 面向基础设施管理和云开发任务。它会开放 AWS 相关能力，并把 infrastructure 文档和部署脚本放入 resources。

适合场景：

• 部署 CloudFormation stacks。
• 管理 S3 buckets 和 Lambda functions。
• 排查 AWS services 问题。
• 审查和更新 Infrastructure as Code。

设计要点：

• tools 包含 read、write、shell、aws。
• allowedTools 只预批准 read 和 aws 中的安全操作。
• toolsSettings.aws.allowedServices 限制 AWS services，例如 s3、lambda、cloudformation。
• toolsSettings.write.allowedPaths 只允许写 infrastructure/**、scripts/**、YAML/JSON 等相关路径。
• agentSpawn hook 可运行 aws sts get-caller-identity，确认当前身份。

AWS agent 不建议给过宽权限。尤其是 iam、ec2、cloudformation 这类服务，最好保留关键操作审批。

Development Workflow Agent

Development workflow agent 面向日常开发、Git、测试和文档更新。

适合场景：

• Code review 和分析。
• 编写和更新测试。
• Git workflow 管理。
• 文档更新。
• 依赖维护。

设计要点：

• 通过 MCP 接入 Git tools。
• allowedTools 预批准 git_status、git_log、git_diff 等只读 Git 操作。
• toolAliases 把 Git MCP 工具简化成 status、log、diff。
• write.allowedPaths 限制到 src/**、tests/**、docs/**、package.json 等项目文件。
• agentSpawn hook 可读取 git status --porcelain 和当前分支。

这个 agent 的重点是“开发可用，但不要默认允许 push、commit 或破坏性命令”。

Code Review Agent

Code review agent 专注代码质量、安全和最佳实践分析。

适合场景：

• 审查 pull request。
• 发现安全漏洞。
• 检查编码规范。
• 分析复杂度和可维护性。
• 给出重构建议。

设计要点：

• 通常只需要 read 和有限 shell。
• allowedTools 可允许 read 和只读 shell 命令。
• shell.allowedCommands 可包含 git diff、git log、eslint、pylint、rubocop 等。
• resources 加入 CONTRIBUTING.md、coding standards、安全指南和 lint 配置。
• hook 可在 agent 启动时收集最近变更文件。

Code review agent 不应默认拥有 write 权限。审查和修改最好分离。

Project-Specific Agent

Project-specific agent 适合绑定特定项目，例如移动 App 后端、Docker 服务、数据库迁移项目等。

适合场景：

• 管理 Docker containers 和 services。
• 运行数据库查询和 migrations。
• 构建和测试应用。
• 排查生产问题。
• 更新 API 文档。

设计要点：

• mcpServers 接入 Docker、database 等项目工具。
• allowedTools 优先允许只读操作，例如容器列表、日志、只读查询。
• toolsSettings.write.allowedPaths 限制到 src/**、tests/**、migrations/**、Dockerfile 等。
• shell.allowedCommands 限定测试、构建和 docker compose 命令。
• resources 加入 API 文档、数据库 schema、配置文件和 compose 文件。

如果包含数据库 MCP，强烈建议区分 read-only query 和 write/migration 操作。

Remote MCP Server Agent

Custom agent 也可以接入 remote MCP server：

{
  "name": "domain-finder",
  "description": "Agent with access to domain search capabilities",
  "prompt": "You help users find and research domain names using the find-a-domain service.",
  "mcpServers": {
    "find-a-domain": {
      "type": "http",
      "url": "https://api.findadomain.dev/mcp"
    }
  },
  "tools": ["@find-a-domain"],
  "allowedTools": ["@find-a-domain"]
}

如果 remote MCP server 需要 OAuth，可以配置 scopes：

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.github.com/mcp",
      "oauth": {
        "oauthScopes": ["repo", "user", "read:org"]
      }
    }
  }
}

遇到 OAuth scope 错误时，官方示例提到可以用空数组绕过 scope requirements，但这要结合 server 的安全模型谨慎判断。

创建有效 custom agents 的建议

• Start simple：先从基本 tools 和 resources 开始。
• Use descriptive names：名称要能看出用途。
• Include relevant context：只加入真正相关的文档和配置。
• Pre-approve safe tools：只预批准低风险、高频工具。
• Use hooks for dynamic context：用 hooks 注入当前状态，例如 git status。
• Limit tool scope：用 toolsSettings 限制路径、命令和服务。
• Test thoroughly：分享给团队前先完整测试。
• Document your agents：描述清楚用途和边界。

常见问题

Q: Kiro custom agent 示例能直接复制使用吗？

A: 可以作为起点，但要按项目收紧权限，尤其是 write、shell、aws 和数据库工具。

Q: Code review agent 应该有写权限吗？

A: 通常不建议。审查和修改分离更安全，避免 review agent 在未确认时改代码。

Q: Remote MCP server agent 要注意什么？

A: 注意 OAuth scopes、工具权限和数据外发边界，不要把敏感项目上下文交给不可信 server。