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 trusted operations - Define which operations 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 operations 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. In CLI V3, keep full MCP selectors instead of relying on the CLI 2.x toolAliases field.

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-4.6",
  "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. Sessions you start from Mobile behave the same way as Kiro Web sessions.

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

If you're upgrading from IDE 0.x, existing JSON profiles continue to work. For CLI 2.x, profiles that still use allowedTools or toolsSettings without a permissions block must be converted with /upgrade-agent before CLI V3 can load them; other supported fields carry over. Current optional fields include permissions, excludedTools, includeMcpJson, resources with skill://, and Markdown format.

• IDE 0.x reference - Custom agent config
• CLI 2.x reference - Custom agent config
• Agent configuration reference - Markdown format
• 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