Pular para o conteúdo

Vídeo · Inteligência Artificial

Como criar um agente de IA no Claude Code (passo a passo)

Aprenda a criar um agente de IA no Claude Code com a pasta .claude/agents: quando usar, quais ferramentas liberar, como testar e os erros mais comuns.

Duração
17:24
Capítulos
15
Publicado
30 OUT
Sumário · 11 seções0% lido

Resumo

Para criar um agente no Claude Code, você escreve um arquivo Markdown em .claude/agents com nome, descrição, ferramentas liberadas e instruções claras do que é a tarefa e do que é considerado pronto. Comece com uma tarefa pequena, libere só as ferramentas necessárias, rode, confira o resultado e ajuste as instruções, não o modelo.

O que o vídeo mostra

O vídeo explica a diferença entre fluxo e agente e mostra os três níveis de criar um agente. Depois cria, na prática, um agente que lê uma pasta de anotações e gera um arquivo pendencias.md só com o que ainda está em aberto, rodando no Claude Code desktop. No fim, aponta os erros mais comuns de quem começa.

  • 0:00 O agente pronto, rodando
  • 0:47 Fluxo ou agente: qual a diferença
  • 1:38 Agente de IA em uma frase
  • 2:03 O que um agente não é
  • 2:22 Os três níveis de criar um agente
  • 4:49 O plano em 5 passos
  • 6:37 Criando a pasta .claude/agents
  • 7:36 O arquivo do agente: frontmatter, tarefa e limites
  • 10:24 Salvando o agente e as anotações de exemplo
  • 11:37 Rodando o agente no Claude Code
  • 13:24 O resultado: pendencias.md
  • 14:10 Depois: subagentes
  • 14:23 Os erros de quem começa
  • 15:22 O meu plano com agentes
  • 16:35 Resumindo

Qual a diferença entre fluxo e agente de IA?

Num fluxo, o caminho é fixo: passo A, B, C, D. A IA pode até ser chamada no meio, para resumir ou classificar algo, mas quem decide a direção é o desenho do fluxo. Se o resultado depende de a ordem das etapas ser sempre a mesma, você quer um fluxo.

Num agente, o modelo recebe a tarefa, escolhe a ferramenta, executa, olha o resultado e decide o próximo passo, em ciclos, até concluir. No exemplo do vídeo, o agente listou a pasta, leu as notas e escreveu o arquivo sem que ninguém tivesse escrito essa ordem.

Um agente não é autônomo no sentido de fazer o que quiser. Ele trabalha com as ferramentas que você liberou e dentro das regras que você escreveu. A qualidade do resultado depende mais da sua instrução do que de qualquer característica misteriosa do modelo.

  • Use fluxo quando o caminho é conhecido e se repete igual.
  • Use agente quando o próximo passo depende do que foi encontrado no passo anterior.
  • Misturar os dois é comum: um fluxo que dispara um agente, ou um agente que roda dentro de uma etapa do fluxo.

Quais são os três níveis de criar um agente?

O primeiro nível é usar um agente que já existe. O Claude Code já é um agente: você pede uma tarefa e ele lê arquivos, escreve código e decide o que fazer. Você não criou nada, só usou.

O segundo nível é especializar. Você dá a um agente uma descrição de cargo: o que ele faz, quais ferramentas pode usar, o que conta como pronto e quais são os limites. É o nível que a maioria das pessoas usa no dia a dia e é o foco do vídeo.

O terceiro nível é construir do zero: escrever o ciclo, definir as ferramentas, integrar com a API de um modelo. Faz sentido quando a solução precisa ser muito específica, por exemplo para uma empresa com um requisito que nenhuma ferramenta pronta atende. Para começar, o nível dois costuma resolver.

Como criar um agente no Claude Code, passo a passo?

Dentro da pasta do projeto, crie a pasta .claude e, dentro dela, a pasta agents. Cada agente é um arquivo Markdown (.md) nessa pasta. Markdown é só texto com marcações simples: hashtag vira título, duas hashtags viram subtítulo. Qualquer editor serve, do bloco de notas à sua IDE.

O arquivo começa com um cabeçalho (frontmatter) entre linhas de três traços. No exemplo do vídeo, ele tem três campos: name (o nome do agente, aqui pendencias), description (o que ele faz, em uma frase, incluindo o nome da pasta que ele vai ler) e tools (Read, Glob e Write). Read lê arquivos, Glob encontra arquivos por padrão de nome e Write escreve.

Abaixo do cabeçalho vem o corpo, em texto normal. No exemplo, ele tem três blocos: a tarefa (ler todas as notas da pasta e escrever o arquivo pendencias.md), a definição de pronto (uma linha por pendência, em formato de lista com checkbox e a nota de origem) e os limites (se a nota diz que algo já foi resolvido, não entra).

Para rodar, abra a pasta no Claude Code desktop, digite @ e o nome do agente, complete com tab e peça que ele faça a tarefa. No vídeo, ele leu as notas, devolveu 10 pendências, listou as que ficaram de fora por já estarem resolvidas e gerou o arquivo na pasta do projeto.

  • Pasta: .claude/agents na raiz do projeto.
  • Arquivo: nome-do-agente.md, com frontmatter e corpo em Markdown.
  • Frontmatter: name, description e tools.
  • Corpo: tarefa, definição de pronto e limites.

Quais ferramentas liberar para o agente?

Libere só o que a tarefa exige. Um agente que lê uma pasta e escreve um arquivo não precisa de internet, de consulta a API nem de execução de comandos. Cada permissão a mais é uma chance a mais de ele fazer algo que você não queria.

Uma forma prática de decidir: escreva a tarefa em uma frase e liste os verbos. Ler, achar arquivos, escrever. Cada verbo vira uma ferramenta. Se aparecer um verbo que você não sabe se é necessário, comece sem ele e adicione depois, se o teste mostrar que faltou.

Isso também ajuda na confiança. Se o agente só consegue ler uma pasta e escrever um arquivo, o pior erro possível é um arquivo mal escrito, algo fácil de perceber e desfazer.

Como saber se o agente está funcionando e como ajustar?

Rode, abra o resultado e compare com a sua definição de pronto. Se o formato saiu diferente do pedido, ou se entrou uma pendência que já estava resolvida, o problema quase sempre está na instrução. Troque de modelo só depois de esgotar a instrução.

A regra do vídeo é ser óbvio com a IA. Ela não tem o seu senso comum. Se você quer ordem de prioridade, uma mensagem no final ou outro layout, escreva isso no arquivo do agente. Na próxima execução ele segue a nova versão.

Um bom ciclo é: rodar, conferir, ajustar uma coisa, rodar de novo. Mudar várias coisas de uma vez dificulta saber o que resolveu e o que piorou.

  • Resultado fora do formato: detalhe o formato, com um exemplo de linha.
  • Itens que não deveriam aparecer: escreva a regra de exclusão como uma frase direta.
  • Resultado incompleto: confira se a descrição da tarefa cobre todos os arquivos que ele deve ler.

Quais são os erros mais comuns de quem começa?

O primeiro é escolher uma tarefa grande demais. Quanto maior a descrição, mais chances de o agente errar, inventar algo ou fazer o que não devia. Prefira uma tarefa pequena, repetitiva e fácil de conferir, e só depois pense em combinar várias.

O segundo é dar permissão demais, na lógica de liberar tudo para não ter que pensar nisso. O agente pode acabar mexendo no que não devia, inclusive no seu computador. Comece com o mínimo.

Quando for encadear agentes, o vídeo recomenda começar com você mesmo sendo o elo: um agente termina, você confere e chama o próximo. Só depois de rodar bastante vale automatizar também o gatilho e a passagem entre eles.

Para aplicar

  • Escolha uma tarefa pequena e repetitiva do seu dia que dê para conferir em um minuto.
  • Escreva em uma frase o que conta como pronto, incluindo o formato do arquivo de saída.
  • Crie a pasta .claude/agents e um arquivo .md com name, description e tools.
  • Libere só as ferramentas dos verbos da tarefa, como Read, Glob e Write.
  • Rode o agente no Claude Code com @ e o nome dele, e compare o resultado com a sua definição de pronto.
  • Ajuste uma instrução por vez e rode de novo até o resultado sair como você espera.
  • Só depois de vários usos estáveis, pense em encadear com outro agente ou em automatizar o gatilho.

Perguntas frequentes

Preciso saber programar para criar um agente no Claude Code?

Para o nível de especialização mostrado no vídeo, não. O agente é um arquivo de texto em Markdown com um cabeçalho e instruções em português. Saber programar ajuda quando você quiser construir um agente do zero, com ciclo próprio e integrações por API.

Posso usar o Claude Code pelo terminal em vez do desktop?

Sim. O agente é o mesmo arquivo em .claude/agents. No vídeo, o desktop foi escolhido porque é mais visual e menos técnico, mas a mesma pasta funciona pela linha de comando.

Quanto tempo leva para criar o primeiro agente?

O exemplo do vídeo, com um arquivo de poucas linhas e uma pasta de anotações, cabe em uma sessão curta. O tempo maior costuma ir para ajustar a definição de pronto e os limites depois do primeiro teste.

O que fazer quando o agente erra?

Releia a sua instrução antes de culpar o modelo. Verifique se a tarefa, o formato esperado e as regras de exclusão estão escritos de forma explícita, ajuste uma coisa e rode de novo.

Quando faz sentido ter mais de um agente?

Quando a tarefa ficou grande e dá para separar em etapas bem definidas, cada uma com seu agente. Comece sendo o elo entre eles, conferindo cada saída, e só automatize a passagem depois de ter confiança no resultado de cada etapa.

Para continuar

// Curso · WDS Builders

Video Builder IA

Você grava o seu vídeo e dirige um agente de IA que transcreve, corta, legenda, anima e renderiza. Nada avança sem a sua aprovação. Do bruto ao vídeo publicado.

Entrar na lista de espera →

// Canal no YouTube

Inscreva-se no canal

IA aplicada, automação e os bastidores do que estou construindo, mostrados na prática.

Inscrever-se no canal →

Mais vídeos sobre o tema

Ver todos os vídeos →

Artigos sobre o mesmo tema

Ver o blog →