Creating custom agents

Custom agents allow you to tailor Kiro CLI behavior for specific tasks by defining which tools are available, what permissions are granted, and what context is automatically included.

Quick start

Create a new custom agent using the interactive command:

kiro-cli --agent create my-agent

This will guide you through the setup process and create a configuration file at ~/.kiro/agents/my-agent.json.

Agent configuration file

Custom agents are defined using JSON configuration files. Here's a basic example:

{
  "name": "my-agent",
  "description": "A custom agent for my workflow",
  "tools": {
    "allowed": ["readFile", "writeFile", "executeBash"],
    "autoApprove": ["readFile"]
  },
  "context": {
    "files": ["README.md", "package.json"],
    "systemPrompt": "You are a helpful coding assistant."
  }
}

Configuration options

Basic information

• name: Unique identifier for your agent
• description: Brief explanation of the agent's purpose

Tool management

• tools.allowed: Array of tool names the agent can access
• tools.autoApprove: Tools that don't require user confirmation
• tools.denied: Explicitly blocked tools (optional)

Context configuration

• context.files: Files to automatically load into context
• context.systemPrompt: Custom instructions for the agent
• context.environment: Environment variables to include

Using your custom agent

Start a chat session with your custom agent:

kiro-cli --agent my-agent

Best practices

1. Start restrictive: Begin with minimal tool access and expand as needed
2. Name clearly: Use descriptive names that indicate the agent's purpose
3. Document usage: Add clear descriptions to help team members understand the agent
4. Version control: Store agent configurations in your project repository
5. Test thoroughly: Verify tool permissions work as expected before sharing

Next steps

• Explore Agent Configuration options in detail