Configuration reference

Custom agent configuration files are JSON documents that define how an custom agent behaves. This section provides an overview of configuration concepts and common patterns.

Configuration reference

For complete details about custom agent configuration file format, available fields, and syntax, see the supplementary Amazon Q Developer CLI documentation:

• Agent configuration format - Complete reference for all configuration options

• Built-in tools reference - Documentation for all built-in tools and their configuration options

You can also view the JSON schema for custom agent configuration files by running:

/agent schema

Configuration concepts

Custom agent configuration files contain several key sections that control different aspects of custom agent behavior:

Basic metadata

Every custom agent can include basic metadata for identification and documentation:

• Name - The custom agent's identifier (derived from filename if not specified)

• Description - Human-readable explanation of the custom agent's purpose

Tools configuration

The tools configuration controls which tools are available to the custom agent and how they behave:

tools

Lists all tools the custom agent can potentially use, including built-in tools and MCP server tools

allowedTools

Specifies which tools can run without user confirmation, improving workflow efficiency

toolAliases

Provides alternative names for tools, useful for resolving naming conflicts or creating shortcuts

toolsSettings

Configures specific behavior for individual tools, such as allowed file paths or service permissions

MCP servers configuration

The mcpServers section defines which Model Context Protocol servers the custom agent can access. Each server configuration includes:

• Command - The executable command to start the MCP server

• Arguments - Command-line arguments for the server

• Environment variables - Environment settings for the server process

• Timeout settings - Request timeout configuration

For more information about MCP integration, see Using MCP with Amazon Q Developer.

Resources and context

Custom agents can automatically include relevant context through two mechanisms:

resources

Files and directories to include in the custom agent's context, supporting glob patterns for flexible file selection

hooks

Commands to run at specific trigger points (like custom agent startup or user input), with output included in context

Common configuration patterns

Minimal custom agent configuration

A simple custom agent that provides basic file operations with pre-approved read access:

{
"name": "basic-ops",
  "description": "Basic file operations custom agent",
  "tools": [
    "fs_read",
    "fs_write",
    "execute_bash"
  ],
  "allowedTools": [
    "fs_read"
  ]
}

Specialized workflow custom agent

An custom agent configured for AWS infrastructure management with specific tool permissions:

{
"name": "infra-manage",
  "description": "AWS infrastructure management custom agent",
  "tools": [
    "fs_read",
    "fs_write",
    "execute_bash",
    "use_aws"
  ],
  "allowedTools": [
    "fs_read",
    "use_aws"
  ],
  "toolsSettings": {
    "use_aws": {
      "allowedServices": ["s3", "lambda", "cloudformation"]
    }
  },
  "resources": [
    "file://README.md",
    "file://infrastructure/**/*.yaml",
    "file://docs/deployment.md"
  ]
}

Project-specific custom agent with hooks

An custom agent that includes project context through both static files and dynamic commands:

{
  "name": "project-dev",
  "description": "Project development custom agent with git context",
  "tools": [
    "fs_read",
    "fs_write",
    "execute_bash",
    "@git"
  ],
  "allowedTools": [
    "fs_read",
    "@git/git_status"
  ],
  "resources": [
    "file://README.md",
    "file://CONTRIBUTING.md",
    "file://src/**/*.md"
  ],
  "hooks": {
    "agentSpawn": [
      {
        "command": "git status --porcelain",
        "timeout_ms": 10000
      }
    ]
  }
}

Custom agent with MCP server integration

An custom agent that integrates external tools through MCP servers:

{
"name": "custom-dev",
  "description": "Development custom agent with external tool integration",
  "mcpServers": {
    "git": {
      "command": "git-mcp-server",
      "args": [],
      "timeout": 30000
    },
    "fetch": {
      "command": "fetch-mcp-server",
      "args": ["--timeout", "10"]
    }
  },
  "tools": [
    "fs_read",
    "fs_write",
    "@git",
    "@fetch/fetch_url"
  ],
  "allowedTools": [
    "fs_read",
    "@git/git_status",
    "@fetch/fetch_url"
  ],
  "toolAliases": {
    "@git/git_status": "status",
    "@fetch/fetch_url": "get"
  }
}