Custom agents

Custom agents provide a way to customize Kiro behavior by defining specific configurations for different use cases. Each custom agent is defined by a configuration file that specifies which tools the agent can access, what permissions it has, and what context it should include.

By default, Kiro provides access to all available tools but requires user confirmation for most operations. This approach prioritizes security but can interrupt your workflow with frequent permission prompts.

Custom agents solve this by allowing you to:

• Pre-approve specific tools - Define which tools can run without prompting
• Limit tool access - Restrict which tools are available to reduce complexity
• Include relevant context - Automatically load project files, documentation, or system information
• Configure tool behavior - Set specific parameters for how tools should operate

1. Workflow optimization - Create custom agents tailored to specific tasks like AWS infrastructure management, code reviews, or debugging sessions.
2. Reduced interruptions - Pre-approve trusted tools to eliminate permission prompts during focused work sessions.
3. Enhanced context - Automatically include relevant project documentation, configuration files, or system information.
4. Team collaboration - Share custom agent configurations with team members to ensure consistent development environments.
5. Security control - Limit tool access to only what's needed for specific workflows, reducing potential security risks.

Custom agents work with both built-in tools and external tools from MCP servers. Use the tools field to specify exactly which tools from each source are available, and toolAliases to handle naming conflicts.

Agent configurations support two formats - JSON and Markdown. Both support identical fields. Use Markdown when your system prompt is long or benefits from human readability; JSON works well for programmatically generated configs.

{
  "name": "my-agent",
  "description": "A custom agent for my workflow",
  "tools": ["read", "write", "shell"],
  "excludedTools": ["knowledge"],
  "includeMcpJson": true,
  "includePowers": false,
  "resources": [
    "file://./ARCHITECTURE.md",
    "skill://backend-patterns"
  ],
  "permissions": {
    "rules": [
      { "capability": "shell", "match": ["npm *", "git *"], "effect": "allow" }
    ]
  },
  "prompt": "You are a helpful coding assistant",
  "model": "claude-sonnet-5",
  "welcomeMessage": "Ready to help. What are you working on?"
}

• Workspace agents (project-specific): .kiro/agents/[name].json or .kiro/agents/[name].md — shared via version control, loaded only if the workspace is trusted
• Global agents (user-wide): ~/.kiro/agents/[name].json or ~/.kiro/agents/[name].md — available across all projects

When both locations have agents with the same name, workspace agents take precedence.

Nested directories are supported. The agent name is the path relative to the agents directory without the extension: ~/.kiro/agents/team/planner.md becomes team/planner.

The IDE and CLI can select a custom agent as the primary session agent. Kiro Web loads project-level custom agents committed to .kiro/agents/ and can invoke them for sub-agent delegation, but you cannot select one as the primary Web session agent. Mobile uses Kiro's built-in agents only.

To use personal custom agents in cloud sessions, upload them from Settings > Sync in Kiro Web, then manage them under Settings > Agents.

If you're upgrading from IDE 0.x or CLI 2.x, agent configs are backward-compatible - existing JSON files continue to work without modification. New fields (permissions, excludedTools, includeMcpJson, resources with skill://, Markdown format) are all optional.

• IDE 0.x reference - Custom agent config
• CLI 2.x reference - Custom agent config
• What's new in CLI 3.0 - Agent config changes
• What's new in IDE 1.0 - Agent config changes

• Built-in agents - pre-configured agents that ship with Kiro
• Create a custom agent
• Configuration reference - full reference for all configuration fields
• Invoking as sub-agents - delegate tasks to agents in parallel
• Permissions - configure capability-based access control
• Examples - real-world agent configurations
• Troubleshooting - common issues and solutions