O que é um Agent?
Ao final desta seção, você vai estar confortável com o conceito de agent e com suas aplicações.
Sobre a terminologia deste curso: os termos técnicos são mantidos em inglês — Agent, Tool, Thought, Action, Observation, prompt, token. Não é preguiça de tradução: é que toda a documentação, todo erro que você vai pesquisar no Google e todo nome de função nas bibliotecas usam esses termos. Traduzi-los criaria um vocabulário que só existe nesta apostila. A explicação vem em português; o termo fica em inglês.
Para explicar o que é um Agent, vamos começar com uma analogia.
A visão geral: Alfred, o Agent
Este é o Alfred. Alfred é um Agent.
Imagine que Alfred recebe um comando: "Alfred, eu gostaria de um café, por favor."
Como Alfred entende linguagem natural, ele capta rapidamente o pedido.
Antes de atender, Alfred faz raciocínio e planejamento, descobrindo os passos e as Tools de que precisa:
- Ir até a cozinha
- Usar a cafeteira
- Preparar o café
- Trazer o café de volta
Repare no que aconteceu: ninguém disse a Alfred como fazer café. O pedido foi "quero um café". Os quatro passos foram decididos por ele, a partir do objetivo e do conjunto de capacidades que ele sabe ter.
Com o plano em mãos, ele precisa agir. Para executar, ele usa as Tools da lista de Tools que conhece. Neste caso, a cafeteira.
Por fim, Alfred traz o café recém-preparado.
E é isso que um Agent é: um modelo de IA capaz de raciocinar, planejar e interagir com seu ambiente.
Chamamos de Agent porque ele tem agency — agência, a capacidade de agir sobre o ambiente.
O mesmo Alfred, no fórum
A analogia do café é ótima para entender o mecanismo. Mas o Agent que você vai construir neste curso trabalha em outro ambiente. Vamos refazer o mesmo raciocínio com o pedido que interessa:
"Alfred, traga os processos mais recentes sobre violência doméstica."
Note que o pedido tem exatamente a mesma forma do pedido de café: um objetivo em linguagem natural, sem instruções de como cumpri-lo. Quem decide o "como" é o Agent.
O que Alfred precisa raciocinar
Antes de agir, ele precisa decompor o pedido:
- "Violência doméstica" é um assunto — precisa ser traduzido para o código de assunto correspondente na tabela do CNJ.
- "Mais recentes" implica ordenação por data e um corte — quantos? Se o usuário não disse, ele precisa assumir um padrão razoável.
- "Traga os processos" significa devolver identificação suficiente para o juiz abrir cada processo — número, vara, data, situação. Não o inteiro teor.
O plano que ele monta
| Passo | Tool que ele aciona | Por quê |
|---|---|---|
| 1 | consultar_assunto("violência doméstica") |
Converter o termo em linguagem natural para o código de assunto |
| 2 | buscar_processos(codigo_assunto, limite=5) |
Consultar a base, ordenada por data de distribuição, dentro do nível de acesso de quem pergunta |
| 3 | detalhar_processo(numero_processo) |
Para cada resultado, trazer classe, órgão julgador, comarca e último movimento |
| 4 | resposta final | Apresentar a lista pronta para o juiz abrir cada processo no sistema |
Cada uma dessas Tools é uma função Python que você escreve. Não há mágica nenhuma: o LLM não sabe consultar bancos de dados. Ele sabe decidir qual das suas funções chamar, com quais argumentos, e em que ordem — e é exatamente isso que o torna útil.
Onde o Alfred para — e por quê
Repare no que a lista não inclui: abrir a petição inicial e resumi-la. O Agent entrega número, vara, data e situação; a partir daí você abre o processo no sistema de sempre.
Essa fronteira é deliberada, por três motivos:
- É onde está o ganho real. O trabalho que consome tempo é descobrir quais processos olhar. Uma vez que você tem os números, abrir os autos é um clique. Automatizar a parte fácil e arriscar a difícil seria trocar o problema de lugar.
- O inteiro teor não mora na base analítica. As tabelas de consulta guardam metadados — número, classe, assunto, movimentos. As peças ficam no sistema de autos digitais, com controle de acesso próprio. Ir buscá-las exigiria contornar esse controle, que existe por um motivo.
- Resumo de peça é onde o modelo erra caro. Um número de processo errado você percebe na hora: o sistema não acha. Um resumo errado de uma inicial parece perfeitamente plausível — e é exatamente por parecer que ele é perigoso.
O Agent te leva até o documento certo, mais rápido. A leitura continua sua.
Compare os dois Alfreds e repare no que não mudou: o mecanismo é idêntico. O que mudou foi apenas o conjunto de Tools disponíveis. Trocar "cafeteira" por "consulta à base de processos" não exige um agente mais inteligente — exige Tools diferentes.
Essa é a razão pela qual este curso passa tanto tempo em Tools: é aí que mora a diferença entre um agente que serve para alguma coisa e um que não serve.
O que este curso vai construir
O objetivo do curso é que você termine com um Agent seu, especializado em um tema judicial que você escolher, rodando na sua máquina. O exemplo da violência doméstica é o que vamos desenvolver junto; na Unidade 4 você troca o tema pelo que for útil ao seu gabinete.
Ele não vai julgar nada, não vai redigir decisão e não vai substituir leitura de autos. Ele vai encontrar e organizar — reduzindo o tempo entre "preciso ver os processos sobre X" e ter a lista de processos na frente.
Agora de forma mais rigorosa
Com a visão geral em mente, aqui está uma definição mais precisa:
Um Agent é um sistema que usa um modelo de IA para interagir com seu ambiente a fim de atingir um objetivo definido pelo usuário. Ele combina raciocínio, planejamento e execução de Actions (frequentemente através de Tools externas) para cumprir tarefas.
Pense no Agent como tendo duas partes principais:
1. O Cérebro (o modelo de IA)
É onde acontece todo o pensamento. O modelo cuida do raciocínio e do planejamento. Ele decide quais Actions tomar de acordo com a situação.
2. O Corpo (capacidades e Tools)
Representa tudo aquilo que o Agent está equipado para fazer.
O conjunto de ações possíveis depende do que o agente recebeu. Por exemplo: como humanos não têm asas, não conseguem executar a Action "voar" — mas conseguem "andar", "correr", "pular", "pegar".
Esta é a ideia mais importante da unidade, e a que mais gera confusão depois: um Agent não consegue fazer nada além do que você entregou a ele. Ele não descobre capacidades sozinho.
Se o Alfred judiciário não tiver uma Tool de consulta à base de processos, ele não consulta processos. E aqui está a parte perigosa: ele não necessariamente vai dizer que não consegue. Um LLM produz o texto mais provável — e o texto mais provável depois de "traga os processos sobre violência doméstica" é uma lista de processos com número, vara e data. Com formato impecável. E inteiramente inventados.
Um agente sem as Tools certas não falha de forma barulhenta. Ele falha de forma convincente.
O espectro da agency
Seguindo essa definição, Agents existem em um espectro contínuo, com graus crescentes de agency:
| Grau | Descrição | Como se chama | Padrão de código |
|---|---|---|---|
| ☆☆☆ | A saída do modelo não afeta o fluxo do programa | Simple processor | processa_saida(resposta_llm) |
| ★☆☆ | A saída do modelo decide o fluxo de controle básico | Router | if decisao_llm(): caminho_a() else: caminho_b() |
| ★★☆ | A saída do modelo determina qual função executar | Tool caller | roda_funcao(tool_escolhida, args_escolhidos) |
| ★★★ | A saída do modelo controla a iteração e a continuação | Multi-step Agent | while deve_continuar(): executa_proximo_passo() |
| ★★★ | Um fluxo agêntico pode iniciar outro | Multi-Agent | if gatilho(): executa_agente() |
Tabela adaptada do guia conceitual do smolagents.
O Alfred judiciário que vamos construir é um multi-step Agent (★★★): ele precisa encadear várias chamadas, e o resultado de uma determina a próxima — o código do assunto só existe depois da primeira consulta, e o número do processo só existe depois da busca.
Repare que "agent" não é sim ou não — é um grau. E mais agency não é melhor por definição: quanto mais o modelo controla o fluxo, mais difícil fica prever, testar e auditar o comportamento. Em contexto institucional, essa previsibilidade normalmente vale mais do que autonomia.
Regra prática: use o menor grau de agency que resolve o seu problema. Se uma consulta fixa resolve, não construa um agente.
Que modelo de IA usamos em Agents?
O modelo mais comum é um LLM (Large Language Model), que recebe texto e produz texto.
Exemplos conhecidos: GPT (OpenAI), Llama (Meta), Gemini (Google), Qwen (Alibaba) — este último é o que usamos no curso, através do Ollama. Vamos aprofundar na próxima seção.
Também é possível usar modelos que aceitam outras entradas, como um VLM (Vision Language Model), que entende imagens além de texto. É o que seria necessário para ler uma peça digitalizada, que é imagem e não texto. Nosso Agent não vai por esse caminho — ele para nos metadados do processo —, mas vale saber que a categoria existe.
Como uma IA age sobre o ambiente?
LLMs são modelos impressionantes, mas só sabem gerar texto.
No entanto, se você pedir a um aplicativo de chat que gere uma imagem, ele gera. Como?
Os desenvolvedores implementaram funcionalidades adicionais — as Tools — que o LLM pode acionar.
O mecanismo é mais simples do que parece: o LLM continua apenas gerando texto. O que muda é que esse texto é interpretado pelo programa ao redor como uma instrução — "chame a Tool X com os argumentos Y" — e o programa é quem executa a ação. Detalhamos na seção Tools.
Que tipo de tarefa um Agent consegue fazer?
Qualquer tarefa que implementemos através de Tools.
Por exemplo, uma Tool que envia e-mail:
def enviar_mensagem_para(destinatario, mensagem):
"""Útil para enviar uma mensagem de e-mail a um destinatário."""
...
O LLM vai gerar a chamada quando precisar:
enviar_mensagem_para("Chefe", "Podemos adiar a reunião de hoje?")
O projeto das Tools é decisivo e tem grande impacto na qualidade do seu Agent. Algumas tarefas exigem Tools muito específicas; outras se resolvem com genéricas, como busca na web.
Note que Actions não são a mesma coisa que *Tools. Uma Action pode envolver o uso de várias Tools para se completar. No nosso exemplo, a Action "trazer os processos mais recentes sobre violência doméstica" consome três Tools* diferentes.
Onde isso é útil no Judiciário
Triagem por assunto. Encontrar todos os processos de um tema em um acervo, ordenados por critério — o caso que vamos construir.
Perguntas em linguagem natural sobre o acervo. "Quantos processos de execução fiscal estão parados há mais de 180 dias nesta vara?" — sem depender de alguém escrever o SQL a cada nova pergunta.
Localização por combinação de critérios. Cruzar assunto, classe, comarca e faixa de data em uma consulta só, para montar pauta ou preparar mutirão.
Acompanhamento de movimentação. Listar processos cujo último movimento é de determinado tipo, ou que não se movem desde certa data.
O que une esses quatro casos: todos reduzem tempo de busca, nenhum produz decisão.
O agente serve para te levar mais rápido até o documento certo. A leitura do documento, a valoração e a decisão continuam sendo integralmente humanas — e todo resultado que ele apresentar precisa ser conferido contra a fonte antes de embasar qualquer conclusão. As seções seguintes deixam claro por que isso não é excesso de cautela: o modelo produz o texto mais provável, não o verdadeiro, e as duas coisas coincidem com frequência alta o bastante para enganar, mas não o bastante para confiar.
Resumindo: um Agent é um sistema que usa um modelo de IA (normalmente um LLM) como motor de raciocínio para:
- Entender linguagem natural: interpretar instruções humanas e responder de forma coerente.
- Raciocinar e planejar: analisar informação, decidir e traçar estratégias.
- Interagir com o ambiente: coletar informação, executar Actions e observar os resultados.
Agora vamos reforçar com um quiz curto e sem nota. Depois, mergulhamos no "cérebro do Agent": os LLMs.