Every agent configuration file can include the following sections:
name — The name of the agent (optional, derived from filename if not specified).description — A description of the agent.prompt — High-level context for the agent.mcpServers — The MCP servers the agent has access to.tools — The tools available to the agent.toolAliases — Tool name remapping for handling naming collisions.allowedTools — Tools that can be used without prompting.toolsSettings — Configuration for specific tools.resources — Resources available to the agent.hooks — Commands run at specific trigger points.useLegacyMcpJson — Whether to include legacy MCP configuration.model — The model ID to use for this agent.The name field specifies the name of the agent. This is used for identification and display purposes.
{ "name": "aws-expert" }
The description field provides a description of what the agent does. This is primarily for human readability and helps users distinguish between different agents.
{ "description": "An agent specialized for AWS infrastructure tasks" }
The prompt field is intended to provide high-level context to the agent, similar to a system prompt. It supports both inline text and file:// URIs to reference external files.
{ "prompt": "You are an expert AWS infrastructure specialist" }
You can reference external files using file:// URIs. This allows you to maintain long, complex prompts in separate files for better organization and version control, while keeping your agent configuration clean and readable.
{ "prompt": "file://./my-agent-prompt.md" }
"file://./prompt.md" → prompt.md in the same directory as the agent config"file://../shared/prompt.md" → prompt.md in a parent directory"file:///home/user/prompts/agent.md" → Absolute path to the file{ "prompt": "file://./prompts/aws-expert.md" }
{ "prompt": "file:///Users/developer/shared-prompts/rust-specialist.md" }
The mcpServers field specifies which Model Context Protocol (MCP) servers the agent has access to. Each server is defined with a command and optional arguments.
{ "mcpServers": { "fetch": { "command": "fetch3.1", "args": [] }, "git": { "command": "git-mcp", "args": [], "env": { "GIT_CONFIG_GLOBAL": "/dev/null" }, "timeout": 120000 } } }
Each MCP server configuration can include:
command (required): The command to execute to start the MCP serverargs (optional): Arguments to pass to the commandenv (optional): Environment variables to set for the servertimeout (optional): Timeout for each MCP request in milliseconds (default: 120000)The tools field lists all tools that the agent can potentially use. Tools include built-in tools and tools from MCP servers.
fs_read, execute_bash)@ followed by the server name (e.g., @git)@server_name/tool_name* as a special wildcard to include all available tools (both built-in and from MCP servers)@builtin to include all built-in tools@server_name to include all tools from a specific MCP server{ "tools": [ "fs_read", "fs_write", "execute_bash", "@git", "@rust-analyzer/check_code" ] }
To include all available tools, you can simply use:
{ "tools": ["*"] }
The toolAliases field is an advanced feature that allows you to remap tool names. This is primarily used to resolve naming collisions between tools from different MCP servers, or to create more intuitive names for specific tools.
For example, if both @github-mcp and @gitlab-mcp servers provide a tool called get_issues, you would have a naming collision. You can use toolAliases to disambiguate them:
{ "toolAliases": { "@github-mcp/get_issues": "github_issues", "@gitlab-mcp/get_issues": "gitlab_issues" } }
With this configuration, the tools will be available to the agent as github_issues and gitlab_issues instead of having a collision on get_issues.
You can also use aliases to create shorter or more intuitive names for frequently used tools:
{ "toolAliases": { "@aws-cloud-formation/deploy_stack_with_parameters": "deploy_cf", "@kubernetes-tools/get_pod_logs_with_namespace": "pod_logs" } }
The key is the original tool name (including server prefix for MCP tools), and the value is the new name to use.
The allowedTools field specifies which tools can be used without prompting the user for permission. This is a security feature that helps prevent unauthorized tool usage.
{ "allowedTools": [ "fs_read", "fs_*", "@git/git_status", "@server/read_*", "@fetch" ] }
You can allow tools using several patterns:
"fs_read", "execute_bash", "knowledge""@server_name/tool_name" (e.g., "@git/git_status")"@server_name" (e.g., "@fetch")The allowedTools field supports glob-style wildcard patterns using * and ?:
"fs_*" → matches fs_read, fs_write, fs_anything"*_bash" → matches execute_bash, run_bash"fs_*_tool" → matches fs_read_tool, fs_write_tool"fs_?ead" → matches fs_read, fs_head (but not fs_write)"@server/read_*" → matches @server/read_file, @server/read_config"@server/*_get" → matches @server/issue_get, @server/data_get"@*-mcp/read_*" → matches @git-mcp/read_file, @db-mcp/read_data"@git-*/*" → matches any tool from servers matching git-*Optionally, you can also prefix native tools with the namespace @builtin.
{ "allowedTools": [ // Exact matches "fs_read", "knowledge", "@server/specific_tool", // Native tool wildcards "fs_*", // All filesystem tools "execute_*", // All execute tools "*_test", // Any tool ending in _test @builtin, // All native tools // MCP tool wildcards "@server/api_*", // All API tools from server "@server/read_*", // All read tools from server "@git-server/get_*_info", // Tools like get_user_info, get_repo_info "@*/status", // Status tool from any server // Server-level permissions "@fetch", // All tools from fetch server "@git-*" // All tools from any git-* server ] }
* matches any sequence of characters (including none)? matches exactly one character@server_name) allow all tools from that serverUnlike the tools field, the allowedTools field does not support the "*" wildcard for allowing all tools. To allow tools, you must use specific patterns or server-level permissions.
The toolsSettings field provides configuration for specific tools. Each tool can have its own unique configuration options.
Note that specifications that configure allowable patterns will be overridden if the tool is also included in allowedTools.
{ "toolsSettings": { "fs_write": { "allowedPaths": ["~/**"] }, "@git/git_status": { "git_user": "$GIT_USER" } } }
The resources field gives an agent access to local resources. Currently, only file resources are supported, and all resource paths must start with file://.
{ "resources": [ "file://AmazonQ.md", "file://README.md", "file://.amazonq/rules/**/*.md" ] }
Resources can include:
The hooks field defines commands to run at specific trigger points during agent lifecycle and tool execution.
For detailed information about hook behavior, input/output formats, and examples, see the Hooks documentation.
{ "hooks": { "agentSpawn": [ { "command": "git status" } ], "userPromptSubmit": [ { "command": "ls -la" } ], "preToolUse": [ { "matcher": "execute_bash", "command": "{ echo \"$(date) - Bash command:\"; cat; echo; } >> /tmp/bash_audit_log" }, { "matcher": "use_aws", "command": "{ echo \"$(date) - AWS CLI call:\"; cat; echo; } >> /tmp/aws_audit_log" } ], "postToolUse": [ { "matcher": "fs_write", "command": "cargo fmt --all" } ] } }
Each hook is defined with:
command (required): The command to executematcher (optional): Pattern to match tool names for preToolUse and postToolUse hooks. See built-in tools documentation for available tool names.Available hook triggers:
agentSpawn: Triggered when the agent is initialized.userPromptSubmit: Triggered when the user submits a message.preToolUse: Triggered before a tool is executed. Can block the tool use.postToolUse: Triggered after a tool is executed.stop: Triggered when the assistant finishes responding.The useLegacyMcpJson field determines whether to include MCP servers defined in the legacy MCP configuration files (~/.aws/amazonq/mcp.json for global and cwd/.amazonq/mcp.json for workspace).
{ "useLegacyMcpJson": true }
When set to true, the agent will have access to all MCP servers defined in the global and local configurations in addition to those defined in the agent's mcpServers field.
The model field specifies the model ID to use for this agent. If not specified, the agent will use the default model.
{ "model": "claude-sonnet-4" }
The model ID must match one of the available models returned by the Kiro CLI's model service. You can see available models by using the /model command in an active chat session.
If the specified model is not available, the agent will fall back to the default model and display a warning.
Here's a complete example of an agent configuration file:
{ "name": "aws-rust-agent", "description": "A specialized agent for AWS and Rust development tasks", "mcpServers": { "fetch": { "command": "fetch3.1", "args": [] }, "git": { "command": "git-mcp", "args": [] } }, "tools": [ "fs_read", "fs_write", "execute_bash", "use_aws", "@git", "@fetch/fetch_url" ], "toolAliases": { "@git/git_status": "status", "@fetch/fetch_url": "get" }, "allowedTools": [ "fs_read", "@git/git_status" ], "toolsSettings": { "fs_write": { "allowedPaths": ["src/**", "tests/**", "Cargo.toml"] }, "use_aws": { "allowedServices": ["s3", "lambda"] } }, "resources": [ "file://README.md", "file://docs/**/*.md" ], "hooks": { "agentSpawn": [ { "command": "git status" } ], "userPromptSubmit": [ { "command": "ls -la" } ] }, "useLegacyMcpJson": true, "model": "claude-sonnet-4" }
Agent configuration files are JSON files that define how your custom agents behave. The filename (without .json) becomes the agent's name.
We recommend using the /agent generate command within your active Kiro session to intelligently generate agent configurations with AI assistance.
Agent files can be stored in two locations:
.kiro/cli-agents/
Local agents are specific to the current workspace and only available when running Kiro CLI from that directory or its subdirectories.
Example:
my-project/ ├── .kiro/ │ └── cli-agents/ │ ├── dev-agent.json │ └── aws-specialist.json └── src/ └── main.py
~/.kiro/cli-agents/
Global agents are available from any directory.
Example:
~/.kiro/cli-agents/ ├── general-assistant.json ├── code-reviewer.json └── documentation-writer.json
When Kiro CLI looks for an agent:
.kiro/cli-agents/ in current directory~/.kiro/cli-agents/ in home directoryIf both locations have agents with the same name, the local agent takes precedence with a warning message.
The agent's name for identification and display.
{ "name": "aws-expert" }
Human-readable description of the agent's purpose.
{ "description": "An agent specialized for AWS infrastructure tasks" }
High-level context for the agent, similar to a system prompt. Supports inline text or file:// URIs.
Inline:
{ "prompt": "You are an expert AWS infrastructure specialist" }
File URI:
{ "prompt": "file://./my-agent-prompt.md" }
Path Resolution:
"file://./prompt.md" → Same directory as agent config"file://../shared/prompt.md" → Parent directory"file:///home/user/prompts/agent.md"MCP servers the agent can access.
{ "mcpServers": { "fetch": { "command": "fetch-server", "args": [] }, "git": { "command": "git-mcp", "args": [], "env": { "GIT_CONFIG_GLOBAL": "/dev/null" }, "timeout": 120000 } } }
Fields:
command (required): Command to start the MCP serverargs (optional): Arguments for the commandenv (optional): Environment variablestimeout (optional): Request timeout in milliseconds (default: 120000)Tools available to the agent.
{ "tools": [ "fs_read", "fs_write", "execute_bash", "@git", "@rust-analyzer/check_code" ] }
Tool References:
"fs_read", "execute_bash""@server_name""@server_name/tool_name""*""@builtin"Remap tool names to resolve naming collisions or create intuitive names.
{ "toolAliases": { "@github-mcp/get_issues": "github_issues", "@gitlab-mcp/get_issues": "gitlab_issues", "@aws-cloud-formation/deploy_stack_with_parameters": "deploy_cf" } }
Tools that can be used without prompting for permission.
{ "allowedTools": [ "fs_read", "fs_*", "@git/git_status", "@server/read_*", "@fetch" ] }
Pattern Support:
Exact Matches:
"fs_read", "execute_bash""@server_name/tool_name""@server_name"Wildcards:
"fs_*" → fs_read, fs_write"*_bash" → execute_bash, run_bash"fs_*_tool" → fs_read_tool, fs_write_tool"fs_?ead" → fs_read, fs_head"@server/read_*", "@git-*/status"Configuration for specific tools.
{ "toolsSettings": { "fs_write": { "allowedPaths": ["~/**"] }, "execute_bash": { "allowedCommands": ["git status", "git fetch"], "deniedCommands": ["git commit .*", "git push .*"], "autoAllowReadonly": true }, "@git/git_status": { "git_user": "$GIT_USER" } } }
See Built-in Tools for tool-specific options.
Local resources available to the agent. All paths must start with file://.
{ "resources": [ "file://README.md", "file://.kiro/rules/**/*.md", "file://docs/**/*.md" ] }
Supports:
Commands to run at specific trigger points.
{ "hooks": { "agentSpawn": [ { "command": "git status" } ], "userPromptSubmit": [ { "command": "ls -la" } ], "preToolUse": [ { "matcher": "execute_bash", "command": "{ echo \"$(date) - Bash:\"; cat; } >> /tmp/audit.log" } ], "postToolUse": [ { "matcher": "fs_write", "command": "cargo fmt --all" } ], "stop": [ { "command": "npm test" } ] } }
Hook Types:
agentSpawn: When agent is activateduserPromptSubmit: When user submits a promptpreToolUse: Before tool execution (can block)postToolUse: After tool executionstop: When assistant finishes respondingSee Hooks for detailed documentation.
Model ID to use for this agent.
{ "model": "claude-sonnet-4" }
If not specified or unavailable, falls back to default model.
{ "name": "aws-rust-agent", "description": "Specialized agent for AWS and Rust development", "prompt": "file://./prompts/aws-rust-expert.md", "mcpServers": { "fetch": { "command": "fetch-server", "args": [] }, "git": { "command": "git-mcp", "args": [] } }, "tools": [ "fs_read", "fs_write", "execute_bash", "use_aws", "@git", "@fetch/fetch_url" ], "toolAliases": { "@git/git_status": "status", "@fetch/fetch_url": "get" }, "allowedTools": [ "fs_read", "@git/git_status" ], "toolsSettings": { "fs_write": { "allowedPaths": ["src/**", "tests/**", "Cargo.toml"] }, "use_aws": { "allowedServices": ["s3", "lambda"], "autoAllowReadonly": true } }, "resources": [ "file://README.md", "file://docs/**/*.md" ], "hooks": { "agentSpawn": [ { "command": "git status" } ], "postToolUse": [ { "matcher": "fs_write", "command": "cargo fmt --all" } ] }, "model": "claude-sonnet-4" }
Use Local Agents For:
Use Global Agents For:
allowedTools carefullytoolsSettings for sensitive operations
Agent configuration reference