A ilusão dos Múltiplos AGENTS de IA: Como dominar Roles, Skills e economizar tokens na prática.

Você está criando AGENTS de IA do jeito errado. E isso está custando caro para o seu projeto.

É muito comum cairmos na "armadilha da responsabilidade única": um AGENTS para UI, um para Banco, outro para Serviços...

O resultado? Acoplamento, perda de controle e um desperdício gigante de tokens.

Pode até aparecer algo correto quando visamos em responsabilidade única, pequenos AGENTS que devem cuidar de partes exclusivas do projeto, bom até parece um cenário ideal mas o resultado na prática? Um acoplamento gigantesco, a perda do controle da arquitetura e um gasto desnecessário.

A verdadeira virada de chave que percebi ao utilizar ferramentas como o Cursor e o Antigravity é outras, percebi que a solução mais interessante não é ter dezenas de AGENTS conversando, mas sim utilizar o conceito de Function Calling: dar a um único AGENTS Sênior um excelente 'cinto de utilidades'(skills) para ele usar quando precisar dessa forma diminuindo a complexidade de múltiplos AGENTS e busca de contextos variados dentro do projeto.

A anatomia do AGENTS: O Cérebro vs. As Mãos 🛠

Pensando em arquitetura do projeto em um ambiente de IA, onde o contexto e comportamentos bem definidos são a chave para uma atuação assertiva do agente, definir que é? o que lê ele faz? e como será feito? São pontos chaves para usufruir o máximo de agentes de IA, vamos entender cada um desses pontos:

• A Role (O Cérebro): Aqui definimos o perfil do nosso agente, neste arquivo definiremos quem ele é? e como ele deve se comportar?. Persona do agente (Engenheiro de software senior, QA senior especialista em testes de segurança), quais conceitos e paradigmas deve seguir (Clean Architecture, SOLID), como deve se comportar em interagir com cada camada do projeto, assim como “travas de segurança” (quando a IA deve parar e perguntar ao humano).

## 1. Persona
Você é um Engenheiro de Software Sênior especializado em Clean Architecture e segurança de aplicações. Seu objetivo é garantir um código limpo, modular e livre de vulnerabilidades.

## 2. Regras de Código
- Siga rigorosamente os princípios SOLID.
- A camada de Service concentra a regra de negócio e não deve acessar o banco de dados diretamente.
- O banco de dados deve ser acessado exclusivamente através da camada de Repository.

## 3. Travas de Segurança
- Nunca altere o schema do banco, variáveis de ambiente ou instale dependências sem permissão explícita.
- Em caso de conflito de arquitetura, PARE a execução. Explique o problema e sugira duas alternativas antes de acionar qualquer ferramenta de edição.

• As Skills (Ferramentas): aqui definimos como deve ser feito? Seguindo o fluxo já definimos como será nosso AGENT e como deve se comportar, porém agora precisamos dar as ferramentas necessárias para ele utilizar. Essas ferramentas são o que podemos encarar com uma espécie de “manual" como ela deve agir de acordo com cada solicitação e referência nos prompts enviados.

Assim garantindo uma maior padronização dentro das ações solicitadas, sempre que pedimos algo ele irá olhar para skill que faz sentido a solicitação e vai saber exatamente como você gostaria que fosse o resultado da solicitação.

E aqui chegamos a um ponto crucial disso, onde conseguimos através dessas estruturas padronizar comportamentos e resultados obtidos com os agentes de IA. todas essas ferramentas podem ser criadas e mantidas localmente visando um projeto específico ou globalmente se aplicando a geral, seguindo a estrutura abaixo:

E aqui vai um exemplo de inserir_registro_via_repositorio.md

# Skill: Inserir Registro Financeiro via Repositório 🗄️

**Descrição:** Insere um novo registro no banco de dados utilizando exclusivamente a camada de `Repository`. 
**Regras de Execução Obrigatórias:**
1. NUNCA execute comandos SQL diretos.
2. NUNCA crie registros financeiros sem vincular a um usuário existente.
3. Em caso de erro de validação, não tente forçar a inserção. Retorne o código do erro para o usuário humano.

**Parâmetros Necessários:**
- `nome_repositorio` (texto): Nome exato da classe a ser instanciada (ex: `TransacaoRepository`).
- `dados_insercao` (texto): Objeto JSON contendo os dados a serem salvos.
- `id_usuario_auditoria` (texto): O ID do usuário autenticado que está realizando a ação (obrigatório para os logs de segurança).
- `modo_simulacao` (booleano): Se `true`, o sistema apenas valida os dados e a estrutura sem gravar nada no banco (Dry-Run). **Atenção:** Use sempre `true` na primeira tentativa para validar a operação de forma segura.

Dominando o Cursor IDE 💻

Algo importante a se atentar cabe dá uma lida da documentação de como cada IDE aplica esse conceito de Roles e Skills, lembrando que cada uma estruturam e usam de maneira diferente o mesmo arquivo. No cenário de duas IDEs que tenho feito uso Cursor e Antigravity os comportamentos e configuração são os seguintes:

No Cursor: As Roles devem ser criadas dentro de uma pasta Raiz no projeto .cursor/rules

Já as skills podem até ser utilizadas seguindo a estrutura citadas antes porém o Cursor possui de maneira internas skills ue os próprio desenvolvedores criaram para ela saber como deve fazer cada coisa, mas cabe aplicar as suas com as demais especificações

No Antigravity:

No Antigravity, as Skills são ferramentas que o agente usa, enquanto a Role define a "personalidade", cabendo um pequeno ajuste ao documento para que funcione plenamente na plataforma e atenda o que o desenvolvedor está buscando, algo mais especialista ou generalista.

Fluxo da SKILLS / ROLES no escopo do Antigravity

Cabe conferir como cada IDE se comporta com skills:

• Documentação do Antigravity Skills: https://antigravity.google/docs/skills
• Documentação Cursor Roles: https://cursor.com/pt-BR/docs/rules
• Documentação Cursor Skills: https://cursor.com/pt-BR/docs/skills
• 
  

O Bolso Dói: Entendendo o impacto dos Tokens e como Roles e Skills economizam seu dinheiro 💲

Aí você deve estar se perguntando o porquê entender sobre roles e skills e como isso vai te ajudar no dia a dia como desenvolvedor fazendo uso da IA ativamente no seu trabalho. Aposto que você como usuário de a já deve ter ouvido falar em tokens (preço que o agente selecionado cobra para para analisar o input e devolver o output).

Normalmente você tende a passar um contexto em cada solicitação de tarefa dentro da IDE seja especificando como você quer a saída onde ele deve verificar quais as regras ele deve seguir para executar aquele seu pedido da melhor maneira possível.

Porém quando você envia um prompt muito grande você acaba por consumir vários tokens para que aquele a gente consiga analisar, executar a tarefa e devolver uma resposta.

E quando falamos em token necessariamente estamos falando de dinheiro então você pode estar queimando o dinheiro com prompts mal estruturados ou cheios de informações que não precisa necessariamente.

Para você ter ideia, cada gente tem uma precificação diferente do consumo de token, baseado no prompt um exemplo bem simples abaixo de como funciona essa questão do Token em relação às palavras do prompt.

Pensando nisso, surge o porquê você deve configurar roles e skills diminuindo consideravelmente o contexto necessário a ser passado no prompt e deixando o seu AGENT ciente do que realmente você precisa que seja feito. Facilitando muito o seu trabalho no dia a dia e flexibilizando o trabalho dele.

Conclusão✅:

Bom, com isso conseguimos entender os benefícios de configurar boas Skills e roles para as IDEs que utilizam agentes de IA integrado, você como desenvolvedor precisa dominar essas ferramentas e entender cada vez mais como os agentes se comportam dentro do escopo das IDEs, dessa forma você como desenvolvedor vai tirar o máximo proveito das integrações com IA.

É notório que e as IAs estão cada vez mais robustas em relação aos resultados apresentados. Mas elas por si só não substitui um bom profissional mas um bom profissional pode ser substituído por outro que domina IA. Reforço algo que eu tenho visto cada vez mai,s que é IA como aliado e potencializadora de resultados não como substituto, como muitos tem pregado gerando incertezas.

Lembrando que nem tudo gerado por IA é 100% confiável, ainda assim cabe uma revisão e entender o que de fato você está fazendo são pontos importantes a serem abordados sempre que tiver lidando com agentes de IA.

Espero poder contribuir para o seu aprendizado com esse artigo!

Aproveito, me conta aqui se vocês utilizam já no dia a dia e como tá sendo essa parceria? Já faz uso das Skills para potencializar ainda mais o seu agente de IA?