Custom agents - Features - Docs - Kiro Loading image... Product * About Kiro * IDE * CLI * Web * Mobile * Crew * Pricing * Downloads For * Enterprise * Startups * Students Community * Overview * Ambassadors * Discord * Events * Powers * Shop * Showcase Resources * Docs * Blog * Changelog * FAQs * Report a bug * Suggest an idea * Billing support Social * * * * * * * English Site Terms License Responsible AI Policy Legal Privacy Policy Cookie Preferences English Loading image... * Apps * CLI * Web * Enterprise * Pricing * Docs * Community * Resources SIGN IN DOWNLOADS Loading image... Get Started Installation Authentication Your first project Models Overview Available models Reasoning effort Features How Kiro works Specs Steering Hooks MCP Permissions Custom agents Built-in agents Creating custom agents Configuration reference Invoking as sub-agents Examples Troubleshooting Agent Skills Powers Cloud sessions Compaction Kiroignore Checkpoints and rewind Built-in tools Configuration scopes IDE 1.x What's new in 1.0 Setup & First Run Editor Chat Experimental Troubleshooting 0.x reference CLI What's new in 3.0 Setup & First Run Terminal UI Chat Voice mode Headless mode ACP Auto complete Experimental 2.x reference Crew Quick start Installation Running 24/7 Chat Agent Capabilities Features Interfaces Apps System & storage Configuration Security Troubleshooting Web Setup & First Run Identity Center Connect your repositories Working with the agent Autonomous mode Automations Memory Configuration Sync Sandbox Mobile - Preview Overview Commands and Reference CLI commands Slash commands Built-in tools Exit codes Settings Billing Overview Managing your subscription Upgrading your plan Downgrading your plan Cancelling your plan Purchasing add-on credits Managing your payments Managing usage notifications Managing your taxes Contacting billing support Deleting your account Related questions Enterprise Concepts Onboarding quickstart Connecting your identity provider Deployment options Subscribe your team Manage subscriptions Governance Monitor and track Settings Managed updates Billing IAM Supported regions Privacy and Security Overview Data protection Code references Compliance validation Infrastructure security IAM permissions Firewalls, proxies, and data perimeters VPC endpoints (AWS PrivateLink) Guides Overview Language support Learn by playing Migration Migrating from Q Developer Migrating from VSCode Upgrading from Q CLI * Docs * * Features * * Custom agents Copy page View as Markdown Custom agents Copy page View as Markdown 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. Capability IDE CLI Web Mobile Project-level agents ( .kiro/agents/ ) ✓ ✓ ✓ — Global agents ( ~/.kiro/agents/ ) ✓ ✓ — — Agent switching via UI ✓ ✓ — — Modify agent settings ✓ ✓ — — 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 Benefits of using custom agents * Workflow optimization - Create custom agents tailored to specific tasks like AWS infrastructure management, code reviews, or debugging sessions. * Reduced interruptions - Pre-approve trusted tools to eliminate permission prompts during focused work sessions. * Enhanced context - Automatically include relevant project documentation, configuration files, or system information. * Team collaboration - Share custom agent configurations with team members to ensure consistent development environments. * Security control - Limit tool access to only what's needed for specific workflows, reducing potential security risks. Relationship to MCP and built-in tools 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. Configuration file formats 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. JSON Markdown .kiro/agents/my-agent.json : json { "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?" } Storage locations * 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 . Surface behavior 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 . Tip Custom agents control what tools are available and what they can do . If you want to influence how the agent thinks and responds without changing tool access, use Steering files instead. You can combine both - a custom agent that includes steering via the resources field. Previous versions 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 Next steps * 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 Page updated: September 2, 2026 Permissions Built-in agents