---
title: "Como criar um agente de IA no Claude Code (passo a passo)"
description: "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."
url: "https://williandsantos.com/videos/o-jeito-certo-de-criar-agentes-no-claude-code/"
language: "pt-BR"
---

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

[Inscrever-se no canal →](https://www.youtube.com/@williandsantos?sub%5Fconfirmation=1) [Ler o resumo ↓](#resumo)

WDS // Vídeo [YouTube](https://www.youtube.com/watch?v=VHuApU59reU)

[![](https://i.ytimg.com/vi/VHuApU59reU/maxresdefault.jpg)](https://www.youtube.com/watch?v=VHuApU59reU)

## 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](https://www.youtube.com/watch?v=VHuApU59reU&t=0s) O agente pronto, rodando
- [0:47](https://www.youtube.com/watch?v=VHuApU59reU&t=47s) Fluxo ou agente: qual a diferença
- [1:38](https://www.youtube.com/watch?v=VHuApU59reU&t=98s) Agente de IA em uma frase
- [2:03](https://www.youtube.com/watch?v=VHuApU59reU&t=123s) O que um agente não é
- [2:22](https://www.youtube.com/watch?v=VHuApU59reU&t=142s) Os três níveis de criar um agente
- [4:49](https://www.youtube.com/watch?v=VHuApU59reU&t=289s) O plano em 5 passos
- [6:37](https://www.youtube.com/watch?v=VHuApU59reU&t=397s) Criando a pasta .claude/agents
- [7:36](https://www.youtube.com/watch?v=VHuApU59reU&t=456s) O arquivo do agente: frontmatter, tarefa e limites
- [10:24](https://www.youtube.com/watch?v=VHuApU59reU&t=624s) Salvando o agente e as anotações de exemplo
- [11:37](https://www.youtube.com/watch?v=VHuApU59reU&t=697s) Rodando o agente no Claude Code
- [13:24](https://www.youtube.com/watch?v=VHuApU59reU&t=804s) O resultado: pendencias.md
- [14:10](https://www.youtube.com/watch?v=VHuApU59reU&t=850s) Depois: subagentes
- [14:23](https://www.youtube.com/watch?v=VHuApU59reU&t=863s) Os erros de quem começa
- [15:22](https://www.youtube.com/watch?v=VHuApU59reU&t=922s) O meu plano com agentes
- [16:35](https://www.youtube.com/watch?v=VHuApU59reU&t=995s) 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

- [Revisão humana em automação com IA: quando e como fazer](https://williandsantos.com/blog/revisao-humana-e-parte-do-workflow/): Mostra quando colocar uma pessoa para conferir o resultado, como no vídeo, em que você é o elo entre um agente e o próximo.
- [O que não automatizar: 6 sinais de que o processo deve esperar](https://williandsantos.com/blog/o-que-nao-automatizar/): Ajuda a decidir quais tarefas ainda não devem ser entregues a um agente.
- [O que automatizar primeiro: comece pelo gargalo da operação](https://williandsantos.com/blog/comece-a-automacao-pelo-gargalo/): Complementa a escolha da primeira tarefa: por onde começar quando há vários candidatos.

// Curso · WDS Builders

## [Video Builder IA](https://williandsantos.com/cursos/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 →](https://williandsantos.com/cursos/video-builder-ia/#inscricao)

// 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 →](https://www.youtube.com/@williandsantos?sub%5Fconfirmation=1)

Próximo vídeo 

## [Agente de IA: o que é, como funciona e quando usar](https://williandsantos.com/videos/o-que-e-um-agente-de-ia-entenda-o-conceito-de-uma-vez-por-todas/)

![](https://williandsantos.com/assets/author/avatar-128.webp)

## Willian D. Santos

Desenvolvedor, builder e founder construindo sistemas e produtos em público.

[Sobre mim →](https://williandsantos.com/sobre/) [Artigos →](https://williandsantos.com/autor/willian-d-santos/)

Tags 

agente de IA Claude Code subagentes automação com IA como criar agente de IA

Continue assistindo 

## Mais vídeos sobre o tema

[Ver todos os vídeos →](https://williandsantos.com/videos/)

Vídeo 13 min

### [Claude Code no Windows: como instalar e criar seu primeiro projeto](https://williandsantos.com/videos/claude-code-do-zero-no-windows-instalacao-e-primeiro-projeto/)

Aprenda como instalar o Claude Code no Windows pelo app desktop, escolher o plano, criar o primeiro ambiente e configurar permissões e o CLAUDE.md com segurança.

YouTube [Assistir →](https://williandsantos.com/videos/claude-code-do-zero-no-windows-instalacao-e-primeiro-projeto/)

Vídeo 9 min

### [Como programar com IA sem escrever código: plano, build e validação](https://williandsantos.com/videos/programar-com-ia-sem-escrever-codigo-meu-fluxo-num-projeto-real/)

Aprenda a programar com IA usando spec driven development: escreva o plano, delegue em etapas pequenas e valide usando o sistema. Fluxo prático e erros comuns.

YouTube [Assistir →](https://williandsantos.com/videos/programar-com-ia-sem-escrever-codigo-meu-fluxo-num-projeto-real/)

Vídeo 12 min

### [Como usar IA para dar tarefas em vez de só perguntar](https://williandsantos.com/videos/voce-usa-ia-como-buscador-esta-perdendo-dinheiro/)

Pare de usar IA como buscador. Veja como transformar perguntas em tarefas com resultado, contexto, limites e forma de conferir, e como mesclar as duas coisas.

YouTube [Assistir →](https://williandsantos.com/videos/voce-usa-ia-como-buscador-esta-perdendo-dinheiro/)

Leia também 

## Artigos sobre o mesmo tema

[Ver o blog →](https://williandsantos.com/blog/)

[Inteligência Artificial](https://williandsantos.com/blog/categoria/inteligencia-artificial/) 20 de nov. de 2026

### [Edição de vídeo com IA: como funciona do bruto ao publicado](https://williandsantos.com/blog/edicao-de-video-com-ia/)

Entenda a edição de vídeo com IA, do vídeo bruto ao publicado: o que a IA faz em cada etapa, o que continua sendo sua decisão e como começar.

16 min de leitura [Ler →](https://williandsantos.com/blog/edicao-de-video-com-ia/)

[Inteligência Artificial](https://williandsantos.com/blog/categoria/inteligencia-artificial/) 09 de set. de 2026

### [IA aplicada: como montar um sistema de IA confiável](https://williandsantos.com/blog/ia-aplicada-sistema-confiavel/)

Como levar a IA do teste no chat para o processo real: tarefa delimitada, contexto, avaliação, travas e monitoramento, com passo a passo e erros comuns.

9 min de leitura [Ler →](https://williandsantos.com/blog/ia-aplicada-sistema-confiavel/)

[Inteligência Artificial](https://williandsantos.com/blog/categoria/inteligencia-artificial/) 02 de set. de 2026

### [Revisão humana em automação com IA: quando e como fazer](https://williandsantos.com/blog/revisao-humana-e-parte-do-workflow/)

Como desenhar a revisão humana em automações com IA: onde colocar a etapa, quem revisa, quais critérios usar e como evitar que vire gargalo ou carimbo.

8 min de leitura [Ler →](https://williandsantos.com/blog/revisao-humana-e-parte-do-workflow/)
