🤖 Como ler este módulo
A grande virada é parar de pensar em "passos que eu disparo" e começar a pensar em "um resultado que delego a alguém que raciocina". Os três tipos de agente diferem só no gatilho — você (local), o relógio (agendado/cron) ou um evento externo (webhook). Cada termo novo (cron, webhook, payload, agentic gap) é definido num quadrinho "O que é?" na primeira vez que aparece.
Antes dos oito tópicos, veja o mapa. Três gatilhos diferentes acordam o mesmo tipo de cérebro: um agente que raciocina sobre o resultado. O que muda é só quem aperta o botão — você, o relógio ou uma campainha digital.
Diagrama ilustrativo — o tipo de agente é definido pelo gatilho, não pelo cérebro. Local, agendado e por evento usam o mesmo raciocínio; mudam só em quem (ou o quê) os acorda.
🤖 O que é um agente
O que é
Na automação tradicional, você liga cada passo: nó 1 → nó 2 → nó 3, num caminho fixo e previsível. Um agente recebe o resultado desejado — não a sequência — e raciocina sobre como chegar lá. Ele escolhe ferramentas, adapta quando a situação muda, faz perguntas de esclarecimento quando falta contexto e se auto-cura quando algo quebra no meio do caminho.
O que é?Determinístico = a mesma entrada produz sempre a mesma saída, pelo mesmo caminho (a automação tradicional). Não-determinístico = o agente decide o caminho na hora, então pode resolver de jeitos diferentes — mas cumpre o objetivo. Agente = não-determinístico por natureza.
A melhor analogia é o jantar fora. Cozinhar pela receita é automação: você segue os passos exatos e, se faltar um ingrediente, o processo trava. Pedir um bife no restaurante é o agente: você diz o resultado ("bife ao ponto, com fritas"), e a cozinha resolve o "como" — substitui o que falta, ajusta o fogo, refaz se cair no chão. É como contratar um dev experiente em vez de ditar cada linha: você delega o objetivo, não o procedimento.
Por que aprender
Quando você entende que um agente raciocina, para de microgerenciar e passa a projetar bem o resultado e o contexto. É isso que destrava velocidade: você descreve o destino e deixa o agente traçar (e re-traçar) a rota.
- •Adapta-se: situações novas não exigem um novo fluxo — o agente improvisa.
- •Pergunta: quando o pedido é ambíguo, ele esclarece em vez de adivinhar.
- •Auto-cura: bate um erro, diagnostica e tenta outro caminho sozinho.
Conceitos-chave
Você delega o "o quê".
Escolhe o caminho na hora.
Pode variar; cumpre o fim.
Quebra, diagnostica, refaz.
🖥️ Agente sob demanda (local)
O que é
O agente local é o assistente funcionando como seu agente pessoal, ali na sua máquina: você pede, ele pesquisa, monta arquivos, itera com você e fica mais esperto a cada uso. Você é o gatilho — nada roda sem você pedir. É a forma mais simples de agente: sem deploy, sem servidor, sem agenda. Só conversa.
O que é?Sob demanda (on-demand) — roda só quando você chama. Deploy — colocar algo para rodar num servidor, fora da sua máquina, de forma contínua. O agente local não precisa de deploy: ele vive no mesmo lugar onde você conversa com ele.
Por que aprender
Comece sempre pelo local. É onde você constrói intuição: vê o agente raciocinar, percebe quando ele acerta e quando se perde, e aprende a dar resultado e contexto. Tudo o que você domina aqui se transfere depois para o agendado e o por evento — só que sem você por perto para corrigir.
🎯 Dica prática
Use o agente local como bancada de testes do que depois vai virar agendado. Rode o mesmo pedido três ou quatro vezes ali, veja onde ele tropeça, e só promova para a nuvem quando ele rodar liso. O que você não consertou no local, vai te assombrar em produção.
Conceitos-chave
Gatilho = seu pedido.
Roda na sua máquina.
Fica mais esperto a cada uso.
A base para os outros tipos.
♻️ O loop de auto-melhoria na prática
O que é
O loop de auto-melhoria é o superpoder do agente local: você roda o workflow, ele bate um erro, diagnostica o que falhou, conserta a tool que quebrou e atualiza o workflow para que aquele erro não volte. Cada rodada deixa o processo mais suave e mais rápido. Não é você consertando — é o agente costurando o conserto de volta no próprio fluxo.
Roda o workflow — o agente executa o processo do começo ao fim, na sua frente.
Bate um erro — uma tool retorna falha, uma fonte some, um formato muda.
Diagnostica — lê o erro, identifica a causa (não o sintoma) e propõe o conserto.
Conserta a tool — corrige o script/chamada que quebrou.
Atualiza o workflow — costura o conserto de volta, para o mesmo erro não voltar. As próximas rodadas ficam suaves e rápidas.
Por que aprender
É esse loop que faz o agente local parecer mágico: ele não só erra menos, ele aprende com cada execução. Mas há um aviso importante — esse superpoder some quando o agente vai para produção. Quando ele roda sozinho na nuvem, ninguém está assistindo para fechar o loop. Guarde isso: é o gancho para o tópico 6, o "agentic gap".
🎯 Dica prática
Sempre que o loop fechar um erro, peça ao agente para escrever no workflow uma defesa explícita contra aquele caso (um try/catch, uma validação, um fallback). Assim o conserto vira parte permanente do fluxo — e continua valendo quando você não estiver mais por perto.
Conceitos-chave
Acha a causa do erro.
Corrige o que quebrou.
O erro não volta.
Ninguém fecha o loop lá.
⏰ Agente agendado (cron) — anatomia
O que é
O agente agendado roda sozinho na hora marcada — o gatilho é o relógio. A hora é definida por uma expressão cron, um padrão de cinco campos: minuto, hora, dia-do-mês, mês e dia-da-semana. Por exemplo, 0 7 * * * significa "às 7h, todos os dias". O agente acorda, faz o trabalho e volta a dormir, sem ninguém olhando (unattended).
O que é?Cron — uma forma compacta de dizer "quando rodar", herdada do Unix. São cinco campos separados por espaço; o asterisco * quer dizer "qualquer/todo". Unattended — roda sem supervisão humana, na hora marcada, mesmo que você esteja dormindo.
Diagrama ilustrativo — leia da esquerda para a direita. Outros exemplos: */15 * * * * = a cada 15 min; 0 9 * * 1 = toda segunda às 9h; 0 0 1 * * = todo dia 1º à meia-noite.
Por que aprender
O agendado é o que transforma uma tarefa que você faria à mão num hábito automático. Exemplo clássico: cron dispara → o agente pesquisa um tópico → sintetiza o que achou → grava uma linha numa planilha — tudo unattended, todo dia, antes de você acordar. Você desenha uma vez e colhe para sempre.
Crie um agente AGENDADO com cron <0 7 * * *> (todo dia às 7h).
A cada execução ele deve, sem supervisão:
1. Pesquisar na web o tópico <novidades em automação com IA>;
2. Sintetizar os achados em 3 bullets curtos (1 frase cada);
3. Gravar UMA linha nova na planilha <Radar IA / aba "diário">
com as colunas: data | resumo | 3 links.
Exigências: inputs fixos (tópico e planilha são constantes),
saída estruturada (sempre as mesmas colunas, nessa ordem),
trate erro de cada chamada externa, e logue cada passo.Conceitos-chave
min h dia mês dia-sem.
* = qualquer/todo.
Gatilho = a hora marcada.
Roda sem ninguém olhando.
🔔 Agente por evento (webhook) — anatomia
O que é
O agente por evento acorda quando algo acontece lá fora — o gatilho é um webhook: uma URL que fica escutando. Quando um sistema externo chama essa URL, ele entrega junto um payload (os dados do evento). É a campainha digital: alguém toca (chama a URL), o agente atende e age sobre o que veio. Exemplo: um formulário é enviado → dispara o webhook → o agente gera um relatório.
O que é?Webhook — uma URL que seu agente expõe e que outros sistemas chamam para avisar "aconteceu algo, aja agora". Payload — o pacote de dados que vem junto na chamada (ex.: os campos do formulário, em JSON). É a diferença entre uma campainha e uma campainha que já te entrega o pacote.
O que é?Authorization: Bearer — um cabeçalho (header) que a chamada precisa enviar com uma chave secreta, provando que quem tocou a campainha tem permissão. Sem a chave certa, o webhook recusa. É o que impede qualquer um de disparar seu agente.
Por que aprender
O por evento é o que conecta o seu agente ao mundo real, em tempo real: um lead preenche o form e em segundos recebe o relatório; um pagamento entra e a nota é emitida na hora. Em vez de esperar a próxima rodada do cron, ele reage no instante do evento. E a autenticação por header é o que mantém essa porta segura.
# Chamada que ACORDA o agente — um sistema externo faz isto:
POST <https://seu-agente.exemplo.com/webhook/lead>
Authorization: Bearer <SUA_CHAVE_SECRETA>
Content-Type: application/json
# payload (os dados do evento, em JSON):
{
"evento": "novo_lead",
"nome": "Maria Souza",
"email": "maria@exemplo.com",
"empresa": "Acme Ltda",
"mensagem": "Quero um orçamento de automação."
}
# Prompt do agente por evento:
Crie um agente POR EVENTO exposto no webhook acima.
Ao receber o payload, ele deve: validar a chave Bearer;
gerar um relatório do lead (resumo + próxima ação sugerida);
e responder 200 com o relatório. Trate erro e logue cada passo.Authorization (ou com chave errada) — deve voltar 401/403 e não processar nada. Envie um payload com um campo faltando (ex.: sem email) e confira no log se o agente tratou o erro em vez de quebrar.
Conceitos-chave
URL que escuta eventos.
Os dados do evento (JSON).
Tocou → o agente atende.
Header que autentica.
🕳️ O agentic gap
O que é
O agentic gap é a lacuna que aparece quando o agente sai do local e vai para a nuvem rodando por agenda ou evento: o assistente não está mais olhando para fechar o loop de auto-melhoria. Lembra do tópico 3? Lá, quando algo quebrava, o agente diagnosticava e consertava na sua frente. Em produção, ele roda, mas não adapta da mesma forma — e uma falha pode passar completamente despercebida.
O que é?Agentic gap — a diferença entre o agente "esperto" que você vê no local (que se auto-cura porque você está junto, fechando o loop) e o agente "no piloto automático" em produção, que executa sem alguém ali para perceber e corrigir o que deu errado.
✓ Local (auto-cura)
- ✓Você assiste: vê o erro no instante em que acontece.
- ✓O loop fecha: diagnostica, conserta a tool, atualiza o fluxo.
- ✓Adapta a casos novos ali mesmo, com seu feedback.
- ✓A falha vira aprendizado permanente do workflow.
✗ Produção (sem auto-cura)
- ✗Ninguém assiste: o erro acontece e segue invisível.
- ✗O loop não fecha: roda, mas não se conserta sozinho.
- ✗Caso novo = comportamento imprevisto, sem feedback.
- ✗A falha pode passar despercebida por dias.
Por que aprender
O agentic gap não é motivo para evitar produção — é o que define como você projeta. Como ninguém vai fechar o loop por você, o conserto precisa estar embutido desde o primeiro prompt: tratamento de erro, log em cada passo e saída previsível. Você compensa a ausência da auto-cura ao vivo construindo a resiliência para dentro do agente (é exatamente o tema do tópico 7).
🎯 Dica prática
Antes de promover um agente para a nuvem, pergunte-se: "se isto falhar às 3h da manhã, como eu fico sabendo?". Se a resposta for "não fico", você ainda está no agentic gap. Adicione um aviso (e-mail/DM em caso de erro) antes de subir.
Conceitos-chave
Loop não fecha sozinho.
Executa, mas não se cura.
Pode passar despercebida.
Resiliência embutida.
🧱 Inputs fixos, saída estruturada, erro & log desde o 1º prompt
O que é
São as quatro exigências de qualquer build unattended — o antídoto contra o agentic gap. Como ninguém estará olhando, o agente precisa nascer resiliente: inputs fixos (nada de "qual fonte uso hoje?"), saída estruturada/previsível (sempre o mesmo formato), tratamento de erro embutido (try/catch em toda chamada externa) e log em cada passo. E tudo isso entra desde o primeiro prompt, não como remendo depois.
O que é?try/catch — "tente fazer isto; se der erro, faça aquilo" em vez de quebrar. Log — um registro do que o agente fez em cada passo, que você lê depois para entender o que aconteceu quando ninguém estava olhando.
Fonte, planilha, tópico — tudo constante. O agente não pergunta nada no meio da noite.
Sempre as mesmas colunas/campos, na mesma ordem. Previsível para quem consome depois.
try/catch em toda chamada externa (API, raspagem, planilha). Falhar não pode ser "travar".
Um registro por etapa. É seu único olho quando você não está olhando.
Por que aprender
Quem trata erro e loga desde o início transforma uma falha silenciosa numa mensagem clara. A diferença entre acordar e descobrir que "o radar parou há três dias e ninguém viu" e ler "Firecrawl deu 429 na fonte 3 ontem às 7h" é toda a diferença entre um brinquedo e algo confiável.
🎯 Dica prática
Logue específico, não genérico. "Firecrawl 429 (rate limit) na fonte 3 às 07:02" diz o que fazer; "task failed" não diz nada e te custa uma hora de investigação. Bom log nomeia o quê, onde e quando.
Construa o agente <radar diário> para rodar UNATTENDED, com:
[Inputs FIXOS] fonte = <lista de 4 sites>; destino = <planilha X>.
Nada de perguntar nada em tempo de execução.
[Saída ESTRUTURADA] sempre as colunas: data | titulo | resumo | url,
nessa ordem, mesmo que algum campo venha vazio.
[Tratamento de ERRO] envolva CADA chamada externa em try/catch;
se uma fonte falhar, pule-a e continue as demais.
[LOG por passo] registre início/fim de cada etapa e todo erro,
nomeando fonte + código (ex.: "fonte 3: HTTP 429").
Em caso de falha, me avise por <e-mail/DM>.Conceitos-chave
Nada de perguntar no meio.
Sempre o mesmo formato.
try/catch externo.
Nomeie o quê/onde/quando.
📜 Quando um "agente" é só um script (e tudo bem)
O que é
Nem tudo precisa raciocinar. Se a tarefa é fixa e previsível — sempre os mesmos passos, sobre os mesmos dados, com o mesmo resultado — um script determinístico é mais barato (não gasta tokens raciocinando), mais rápido e mais confiável do que um agente. Escolher o script aqui não é "menos avançado": é a engenharia certa. Boring is beautiful — chato é lindo.
O que é?Script — um pequeno programa que faz exatamente os mesmos passos toda vez (determinístico). Não raciocina, não adapta, não custa por token: faz o que está escrito, ponto. Para tarefas que nunca mudam, isso é uma vantagem.
✓ Use um AGENTE quando…
- ✓A entrada varia muito e exige interpretação (linguagem natural).
- ✓O caminho não é fixo: precisa escolher ferramentas na hora.
- ✓Casos novos aparecem e é preciso adaptar/improvisar.
- ✓Há ambiguidade real que justifica perguntar/raciocinar.
✗ Use um SCRIPT quando…
- ▸A tarefa é fixa: sempre os mesmos passos, mesma ordem.
- ▸A entrada é previsível e bem-estruturada (não precisa interpretar).
- ▸Confiabilidade e custo importam mais que flexibilidade.
- ▸"Chato e repetível" é exatamente o que você quer.
Por que aprender
Maturidade de quem constrói não é usar agente para tudo — é saber quando não usar. Jogar um agente caro e não-determinístico numa tarefa que um script de dez linhas resolveria é desperdício e abre porta para erro onde não havia. Escolher a ferramenta certa para o problema é o que separa quem brinca de quem entrega.
Conceitos-chave
Previsível não precisa raciocinar.
Não gasta token à toa.
Faz o mesmo toda vez.
Escolha válida e madura.
Um agente roda na nuvem por cron, todo dia às 7h, e ontem uma fonte caiu — mas só hoje você percebeu que faltam dados. Que conceito explica isso?
📌 Resumo do Módulo
0 7 * * * = 7h todo dia; roda unattended.Próximo Módulo:
Trilha 5 — Projetos Práticos (End-to-End)