Definir um agente personalizado - Amazon Q Developer
Criar seu primeiro agente personalizadoComandos de agentes personalizadosMigrar de perfis herdadosUsar agentes padrão em comparação com agentes personalizados

Definir um agente personalizado

Esta seção aborda como criar e usar agentes personalizados no fluxo de trabalho da CLI do Amazon Q Developer.

Criar seu primeiro agente personalizado

Confira um passo a passo para criar seu primeiro agente personalizado:

  1. Inicie uma sessão de chat na CLI do Amazon Q Developer:

    $ q chat

  2. Liste os agentes existentes para ver a disponibilidade:

    /agent list

  3. Crie um agente (substitua my-agent pelo nome de sua preferência):

    /agent create --name my-agent

    Isso cria e abre um arquivo de configuração de agente em seu editor padrão (definido pela variável de ambiente EDITOR).

  4. Personalize a configuração do agente personalizado conforme necessário. Para começar de forma simples, você pode:

    • Adicionar uma descrição que explica a finalidade do agente personalizado

    • Especificar quais ferramentas devem estar disponíveis

    • Pré-aprovar ferramentas que você usa com frequência

  5. Salve o arquivo de configuração e saia do editor para retornar à sessão de chat.

  6. Inicie uma nova sessão de chat com seu agente personalizado:

    $ q chat --agent my-agent

    Observação: não é possível alternar agentes personalizados em uma sessão de chat existente. É preciso iniciar uma nova sessão para alterar os agentes personalizados.

  7. Teste o agente personalizado solicitando que ele execute tarefas usando as ferramentas que você configurou.

Para obter informações detalhadas sobre as opções de configuração do agente personalizado, consulte Configuration reference.

Comandos de agentes personalizados

A CLI do Amazon Q Developer fornece vários comandos para gerenciar agentes personalizados. Esses comandos estão disponíveis durante uma sessão de chat e começam com /agent.

Comandos de agentes personalizados
Command Descrição Disponibilidade
/agent list Mostra todos os agentes personalizados disponíveis em seu ambiente Sessão de chat
/agent schema Exibe o esquema JSON para criar arquivos de configuração de agentes personalizados Sessão de chat
/agent create --name [name] Cria e abre um arquivo de configuração de agente personalizado em seu editor padrão Sessão de chat

Observação: algumas operações de gerenciamento de agentes personalizados exigem edição manual de arquivos em vez de comandos interativos. As alterações no agente personalizado entram em vigor ao iniciar uma nova sessão de chat.

Migrar de perfis herdados

Quando você atualiza para uma versão da CLI do Amazon Q Developer que oferece suporte a agentes e faz login, pode ser solicitado que você migre seus perfis antigos para agentes se você:

  • Tem configurações de perfil herdadas existentes

  • Está executando no modo interativo (a migração é ignorada com --no-interactive)

  • Ainda não concluiu o processo de migração

O processo de migração:

  • Converte as configurações de perfil existentes para o novo formato de agente

  • Preserva as permissões de ferramentas e as configurações de contexto existentes

  • Cria arquivos de configuração de agente no diretório inicial

  • Mantém a compatibilidade com versões anteriores dos fluxos de trabalho existentes

A migração é opcional e pode ser recusada. Se você optar por não migrar, poderá continuar usando o agente padrão ou criar agentes manualmente. Para controlar o comportamento da migração, use o sinalizador --no-interactive para ignorar totalmente os prompts de migração.

Usar agentes padrão em comparação com agentes personalizados

A CLI do Amazon Q Developer inclui um agente padrão integrado que fornece acesso a todas as ferramentas com o mínimo de permissões pré-aprovadas. Esse agente padrão:

  • Inclui todas as ferramentas disponíveis (incorporadas e do MCP)

  • Pré-aprova somente a ferramenta fs_read para segurança

  • Inclui automaticamente arquivos de projeto comuns, como README.md e AmazonQ.md

  • Usa a configuração MCP legada, se disponível

Agentes personalizados permitem que você:

  • Limite o acesso de ferramenta somente ao que você precisa

  • Pré-aprove ferramentas adicionais para reduzir interrupções

  • Inclua documentação específica do projeto e arquivos de contexto

  • Configure o comportamento da ferramenta para o seu caso de uso específico