Gerenciar agentes personalizados - Amazon Q Developer
Locais dos arquivos de agentes personalizadosPráticas recomendadas para organizar agentes personalizadosCompartilhamento de agentes personalizados com equipes

Gerenciar agentes personalizados

Esta seção aborda como organizar, gerenciar e trabalhar com agentes personalizados de forma eficaz em seu fluxo de trabalho de desenvolvimento.

Locais dos arquivos de agentes personalizados

Os arquivos de configuração de agentes personalizados são armazenados como arquivos JSON em diretórios específicos:

Agentes personalizados globais

~/.aws/amazonq/cli-agents/{agent-name}.json

Disponíveis em todos os projetos e diretórios do seu sistema.

Agentes personalizados em nível de projeto

.amazonq/cli-agents/{agent-name}.json

Disponíveis somente no diretório específico do projeto e seus subdiretórios.

Importante: {agent-name} no nome do arquivo é somente para sua referência. O nome real do agente é determinado pelo campo name no próprio arquivo de configuração JSON, que é obrigatório.

Precedência de agentes personalizados e resolução de conflitos

Quando a CLI do Amazon Q Developer procura um agente personalizado, ela segue uma ordem de precedência específica:

  1. Agentes personalizados locais: verifica a existência de agentes personalizados no diretório de trabalho atual

  2. Agentes personalizados globais: retorna aos agentes personalizados em seu diretório inicial

  3. Padrão incorporado: usa o agente padrão se nenhum agente personalizado for encontrado

Se os diretórios local e global contiverem agentes personalizados com o mesmo nome, o agente personalizado local terá prioridade. A CLI do Amazon Q Developer exibirá uma mensagem de aviso quando isso ocorrer:

WARNING: Agent conflict for my-agent. Using workspace version.

Esse sistema de precedência permite que você:

  • Substitua agentes personalizados globais por versões específicas de projeto

  • Teste as modificações personalizadas do agente localmente antes de torná-las globais

  • Mantenha diferentes configurações de agentes personalizados para diferentes projetos

Práticas recomendadas para organizar agentes personalizados

Quando usar agentes personalizados globais

Use agentes personalizados globais em:

  • Fluxos de trabalho de uso geral: agentes personalizados usados em vários projetos

  • Produtividade pessoal: agentes personalizados adaptados ao seu estilo de trabalho individual

  • Tarefas comuns de desenvolvimento: revisão de código, depuração, geração de documentação

  • Fluxos de trabalho específicos de ferramentas: gerenciamento da AWS, operações do Git, fluxos de trabalho do Docker

Quando usar agentes personalizados locais

Use agentes personalizados locais em:

  • Configurações específicas do projeto: agentes personalizados que precisam acessar arquivos específicos do projeto

  • Colaboração em equipe: agentes personalizados compartilhados por meio do controle de versão

  • Ambientes de desenvolvimento: agentes personalizados com requisitos exclusivos para projetos específicos

  • Testes e experimentação: modificações temporárias do agente personalizado sem afetar as configurações globais

Convenções de nomenclatura de agentes personalizados

Considere estas convenções de nomenclatura para uma melhor organização dos agentes personalizados:

  • Nomes baseados em propósitos: aws-specialist.json, code-reviewer.json, documentation-writer.json

  • Nomes específicos para tecnologia: python-dev.json, react-frontend.json, terraform-ops.json

  • Nomes específicos para projetos: project-alpha.json, mobile-app.json, api-backend.json

  • Nomes específicos para ambiente: development.json, staging.json, production.json

Compartilhamento de agentes personalizados com equipes

Agentes personalizados locais podem ser compartilhados com os membros da equipe por meio de sistemas de controle de versão. Essa abordagem permite que as equipes:

  • Padronizem os ambientes de desenvolvimento: garanta que todos os membros da equipe tenham acesso às mesmas ferramentas e configurações

  • Compartilhem contexto específico do projeto: inclua documentação do projeto, padrões de codificação e scripts personalizados

  • Mantenham a consistência: use as mesmas permissões e configurações de ferramenta em toda a equipe

  • Colaborem em melhorias: use solicitações pull para revisar e melhorar as configurações do agente personalizado

Práticas recomendadas para controle de versão

Ao compartilhar agentes personalizados por meio do controle de versão:

  • Inclua diretórios de agentes personalizados: adicione .aws/amazonq/agents/ ao seu repositório

  • Documente as finalidades dos agentes personalizados: escreva descrições claras nos arquivos de configuração do agente personalizado

  • Analise as alterações do agente personalizado: trate as alterações personalizadas na configuração do agente como alterações no código

  • Teste as configurações personalizadas do agente: verifique se os agentes personalizados compartilhados funcionam corretamente para todos os membros da equipe

  • Evite informações confidenciais: não inclua chaves de API, senhas ou informações pessoais em agentes personalizados compartilhados