As developers, we constantly juggle multiple roles. One moment you're buried in Python backend work, wrestling with database schemas; the next you're thrown into a React frontend project, navigating component libraries and design systems. Every context switch demands a mental "hard reboot" with new tools, languages, and mental models.

Imagine having an AI assistant like Amazon Q Developer in your terminal, always ready to help. You ask: "How many tables are there?" The AI freezes. Are you referring to HTML <table> elements in the UI, or SQL tables in PostgreSQL? Without knowing which hat you're wearing, it can only guess.

This is the "development chaos" that slows us down. But what if you could give your AI asistant different hats too? What if you could create specialized "personas" or "partners"—a frontend expert, a backend guru, a DevOps ninja—so it knows exactly what you're working on?

This is exactly what Custom Agents in the Amazon Q Developer CLI enable. Let's build a few of these AI partners to streamline your workflow.

Our goal is to create two specialized agents directly in the terminal:

1. Backend Expert: An agent optimized for Python and PostgreSQL, with direct read-only access to our database structure.
2. Frontend Master: An agent tailored for React and Figma, ready to assist with UI components and design specifications.

First, ensure you have the Amazon Q Developer CLI installed and authenticated. Register at the AWS website if needed.

Creating the Backend Expert Agent

Our first agent is the backend expert. We define its personality and capabilities using a simple JSON configuration file stored in a specific directory under your home folder.

mkdir -p ~/.aws/amazonq/agents/
nano ~/.aws/amazonq/agents/backend-expert.json

Paste the following JSON configuration. We'll break down each section afterward.

{
  "description": "Optimized for Python and PostgreSQL backend development",
  "mcpServers": {
    "PostgreSQL": {
      "command": "uvx",
      "args": [
        "mcp-server-postgres",
        "--readonly",
        "true"
      ]
    }
  },
  "tools": ["*"],
  "allowedTools": [
    "fs_read",
    "@PostgreSQL/get_table_schema",
    "@PostgreSQL/list_tables"
  ],
  "resources": {
    "alwaysInclude": [
      "file:///workspace/project/README.md",
      "file:///home/user/docs/python-guidelines.md",
      "file:///home/user/docs/sql-standards.md"
    ]
  },
  "hooks": {
    "agentSpawn": [
      {
        "command": "git status"
      }
    ]
  }
}

Here's what each section does:

• "description": A simple note for yourself explaining what this agent does.
• "mcpServers": This connects your agent to the outside world. We're giving it a direct line to the PostgreSQL database. This lets Q answer questions like "What columns does the users table have?" with actual data. Notice the "--readonly", "true" flag—this is a critical security measure ensuring your AI assistant doesn't accidentally modify anything.
• "tools" and "allowedTools": Think of "tools" as giving your agent a full toolbox, while "allowedTools" pre-approves specific tools for use. We're granting access to all tools ("*"), but being very careful with permissions. It can read files (fs_read) and fetch database schemas (@PostgreSQL/get_table_schema) without asking, but if it wants to write files (fs_write), it must get your approval first. This gives you granular control.
• "resources": This is like giving your agent required reading material. We tell it to always reference the project's README.md and some personal preference files about Python and SQL. This helps it provide answers consistent with your project conventions and coding style.
• "hooks": This gives our agent a startup routine. The agentSpawn hook runs a command each time you start a conversation with this agent. Here, we run git status so the agent immediately knows your repository state.

Creating the Frontend Master Agent

With the backend expert ready, let's create its frontend counterpart.

Create a new file for the frontend agant:

nano ~/.aws/amazonq/agents/frontend-dev.json

Paste this configuration. Note the differences from our backend agent.

{
  "description": "Optimized for React and Figma frontend web development",
  "mcpServers": {
    "Figma": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://127.0.0.1:3845/sse"
      ]
    }
  },
  "tools": ["*"],
  "allowedTools": [
    "fs_read",
    "fs_write",
    "report_issues",
    "@Figma"
  ],
  "resources": {
    "alwaysInclude": [
      "file:///home/user/configs/react-preferences.md"
    ]
  },
  "hooks": {
    "agentSpawn": [
      {
        "command": "git status"
      }
    ]
  }
}

Key differences:

• New tool: The mcpServers section now points to a local Figma server, giving our agent direct access to our design files.
• Different permissions: The allowedTools list is more permissive here. We trust this agent to read and write files (fs_write), and it can use any Figma server tools (@Figma) without asking for permission.
• Different reading material: The resources section now points to a react-preferences.md file, keeping its knwoledge aligned with our frontend framework.

Putting Your Agents to Work

The magic moment arrives. Switching between your specialized AI partners is as simple as starting a new chat with a parameter.

To chat with your backend expert:

q chat --agent backend-expert

In this conversation, Amazon Q knows it's in "backend mode." You can ask:

"What columns does the products table contain?"

It will use the PostgreSQL connection to return accurate table structure information.

Ready to switch to frontend work? Just start a new chat with your frontend master:

q chat --agent frontend-dev

In this session, you can ask:

"Generate a React component based on the 'Login Button' in the Figma design."

It will use the Figma connection to pull design specifications and generate code. No more ambiguity—only context-aware help that understands your workflow.

Other Agents You Could Build

Custom agents can be created for any part of your workflow:

• An aws-specialist agent: Pre-loaded with your documentation and permitted to run CLI commands.
• A code-reviewer agent: Configured with your team's code review rules and style guidelines.
• A documentation-writer agent: Granted read access to all source files, but restricted to writing only .md files.

By creating these simple JSON files, you're not just configuring a tool—you're building a team of AI assistants that adapt to your way of working. You're taming the chaos of context switching, one agent at a time.