Como criar um agente no Claude Code?

A resposta curta

Agente é funcionário de papel. Você escreve um arquivo Markdown descrevendo quem ele é, o que faz, o que não faz e como entrega — e salva em .claude/agents/ dentro da pasta do projeto. A regra prática: um agente, uma função, um formato de saída. Se você precisa de dois formatos de saída diferentes, são dois agentes.

O arquivo tem duas partes. No topo, entre duas linhas de três traços, vai o cabeçalho com três informações: name (o nome curto), description (quando ele deve ser chamado) e tools (o que ele tem permissão de usar). Abaixo do cabeçalho vem o texto livre: o manual dele.

Depende de quê

Da repetição. Se a tarefa acontece toda semana com entrada parecida, vira agente. Se acontece uma vez, é só uma conversa.

Da clareza do critério de sucesso. Você precisa conseguir escrever "a saída está certa quando…". Sem isso, não há como corrigir o agente.

Do escopo. Um agente de qualificação classifica lead. Não escreve proposta, não dá desconto, não fala com cliente. Escopo estreito é o que faz ele ser confiável.

De onde salvar. Em .claude/agents/ dentro do projeto, o agente vale para aquele projeto e pode ser versionado junto com o resto — a equipe inteira herda. Em ~/.claude/agents/, na sua pasta pessoal, ele vale para todos os seus projetos.

Como decidir no seu caso

1. Escolha uma tarefa repetida e nomeie o resultado esperado.
2. Escreva a descrição pensando em quando ela deve disparar, com as palavras que a equipe usa de verdade.
3. Limite as ferramentas ao mínimo necessário.
4. Escreva o manual com o contexto da empresa, o passo a passo e a lista do que ele não faz.
5. Rode com cinco casos reais e compare com o que você teria feito à mão.
6. Corrija o arquivo, não a conversa.

Esqueleto de um agente de qualificação, salvo como .claude/agents/qualificador-de-leads.md:

---
name: qualificador-de-leads
description: Use quando chegar um lead novo pelo formulário ou pelo WhatsApp e for preciso classificar em A, B ou C segundo o cliente ideal da empresa e sugerir a primeira mensagem. Não escreve proposta, não define preço, não fala com o cliente.
tools: Read, Write, Grep
---

Você é o pré-vendas de uma empresa de manutenção predial que vende
contratos mensais para condomínios e administradoras.

Cliente ideal: empresas de 10 a 200 funcionários, no Sudeste, com
orçamento acima de R$ 5.000 e decisão em até 45 dias.

Ao receber os dados de um lead:
1. Leia o histórico em `dados/clientes.csv` antes de classificar.
2. Classifique em A (encaixa e tem urgência), B (encaixa, sem prazo)
   ou C (fora do perfil). Escreva a razão em uma frase.
3. Para A e B, escreva a primeira mensagem de WhatsApp, com no
   máximo 4 linhas, terminando em uma pergunta.
4. Devolva sempre neste formato: CLASSE / RAZÃO / MENSAGEM.

Nunca invente informação que não está nos dados do lead. Quando
faltar dado essencial, classifique como B e diga o que falta.

Um exemplo com número

Uma empresa recebe 200 leads por mês. A triagem manual leva 6 minutos por lead: 20 horas por mês. Com o agente classificando e sugerindo a primeira mensagem, a pessoa passa a gastar 1,5 minuto por lead conferindo: 5 horas. São 15 horas devolvidas por mês ao time comercial. A revisão humana continua existindo — ela só ficou quatro vezes mais rápida.

Faixa de referência de mercado observada em operações de PME brasileiras (setembro de 2026), não pesquisa publicada. Meça o seu tempo real antes e depois.

O erro mais comum de quem pergunta isso

Três erros derrubam a maioria dos agentes. Descrição vaga, que faz o agente ser chamado na hora errada. Escopo sem limite, um agente que faz tudo e por isso não é confiável em nada. E nenhuma verificação da saída: ninguém definiu quem confere antes de o resultado ir para o cliente. Escreva no próprio arquivo o que o agente não faz e quem revisa.

Para onde ir depois

Crie um agente só, com a tarefa mais chata e mais repetida do seu comercial. Rode uma semana medindo tempo e qualidade. Quando estabilizar, escreva o segundo — e mantenha a regra de uma função por agente.

Leia a seguir

• O problema por trás: Quero usar IA e não sei por onde começar
• O problema por trás: O follow-up não acontece
• Para executar: Implantar IA no comercial em 30 dias