O que eu realmente aprendi construindo agentes autônomos

Acabei de concluir o curso de Agentes Autônomos (Agentic AI) pela FIAP. Em vez do post genérico de "concluí mais uma etapa", resolvi escrever o que eu gostaria de ter lido antes de começar: um guia técnico, com exemplos, sobre o que muda quando você para de fazer chamadas de LLM e começa a construir agentes de verdade.

Como boa parte disso é sobre comportamento em execução — e comportamento é difícil de transmitir em prosa — algumas partes deste texto são executáveis. Mexa nelas.

1. A diferença está no loop, não no modelo

A confusão mais comum: achar que agente é um prompt mais elaborado. Não é.

Uma chamada tradicional de LLM é linear: entrada → saída. Um agente é cíclico: ele decide, executa, observa o resultado e decide de novo — até atingir um critério de parada.

# Isso NÃO é um agente
response = llm.invoke("Calcule o custo de impressão deste modelo")

# Isso é
while not task_completed and steps < LIMIT:
    thought = llm.decide(goal, history, available_tools)

    if thought.action == "finalizar":
        break

    observation = execute(thought.action, thought.parameters)
    history.append((thought, observation))
    steps += 1

Repare no LIMIT. Ele não é detalhe de implementação — é requisito. Um agente sem critério de parada é uma fatura de API em progresso.

Abaixo, esse mesmo loop rodando. Comece com o teto em 3 e veja o que acontece.

2. Anatomia de um agente

Na prática, todo agente tem cinco peças: o modelo, que raciocina e decide; as ferramentas, que são como ele age no mundo; a memória, que é o que ele lembra dentro e entre execuções; o orquestrador, que é o loop que amarra tudo; e os guardrails, que são os limites de custo, escopo, permissão e validação.

Se falta ferramenta, você tem um chatbot. Se falta memória, você tem um agente amnésico que repete o mesmo erro. Se falta guardrail, você tem um problema.

3. Tool use: o ponto onde o agente vira útil

Function calling foi, para mim, o divisor de águas. O modelo não executa nada — ele descreve qual função quer chamar e com quais parâmetros. Quem executa é o seu código.

tools = [{
    "name": "calcular_custo_impressao",
    "description": "Calcula custo de um modelo 3D a partir de gramatura e tempo de impressão",
    "input_schema": {
        "type": "object",
        "properties": {
            "gramas": {"type": "number"},
            "horas": {"type": "number"},
            "material": {
                "type": "string",
                "enum": ["PLA", "PETG", "ABS"]
            }
        },
        "required": ["gramas", "horas", "material"]
    }
}]

Duas lições que custaram tempo:

A descrição da ferramenta é prompt. "Calcula custo" gera chamadas erradas. "Calcula custo total de produção incluindo filamento, energia e taxa de falha de 8%. Use apenas quando já tiver gramatura E tempo confirmados" gera chamadas certas. A descrição é onde você ensina quando usar, não só o que faz.

Schema rígido evita alucinação de parâmetro. enum em vez de string livre eliminou a maior parte dos meus erros de execução.

As duas lições parecem a mesma coisa, mas consertam defeitos diferentes. Combine as chaves abaixo para ver:

"description": "Calcula custo"
"material": { "type": "string" }

calcular_custo_impressao({
  "gramas": 84,
  "horas": null,
  "material": "plástico branco"
})

4. Memória: três tipos, três problemas diferentes

Aqui o curso me fez desfazer uma simplificação que eu carregava — "memória = histórico da conversa".

Curto prazo (contexto): o histórico da execução atual. Barato, mas finito. Em agentes longos você precisa de sumarização progressiva, senão estoura a janela no passo 15.

Longo prazo (semântica): embeddings em base vetorial. É onde entra RAG — e aqui vai o insight que mais mudou minha cabeça: RAG não é uma arquitetura concorrente do agente, é uma ferramenta dele. O agente decide se e quando buscar. Isso é bem diferente de recuperar contexto sempre, por padrão.

Se você executou o loop lá em cima, viu isso acontecer: no passo 2, buscar_conhecimento foi uma decisão do agente diante de um dado faltando — não uma recuperação automática antes de começar.

Episódica: o registro de execuções passadas — o que funcionou, o que falhou. É o que permite ao agente não repetir a mesma tentativa fracassada.

5. Multiagente: poderoso e superestimado

Sistemas multiagente (supervisor delegando para especialistas, ou pares colaborando) resolvem problemas reais de especialização e contexto. Mas o custo é alto: mais chamadas, mais latência, mais pontos de falha, e depuração muito mais difícil.

Meu critério depois do curso:

Só divida em múltiplos agentes quando um único agente estiver falhando por excesso de ferramentas ou de contexto — não porque a arquitetura fica bonita no diagrama.

Na maioria dos casos, um agente bem instrumentado com 6 ferramentas boas supera três agentes se coordenando mal.

6. Guardrails e observabilidade não são "fase 2"

O que eu não sabia que precisava, e agora considero obrigatório desde o primeiro commit:

• Teto de iterações e de custo por execução
• Validação de saída antes de qualquer ação irreversível
• Human-in-the-loop em ações que gravam, publicam, enviam ou gastam
• Log estruturado de cada passo — pensamento, ação, parâmetros, observação, tokens

Sem esse log, quando o agente faz algo estranho no passo 9 de 12, você não tem como saber por quê. Depuração de agente sem rastreabilidade é adivinhação.

7. Aplicando no mundo real

Eu já tinha um projeto que era quase um agente sem eu saber: uma extensão Chrome que raspa dados de modelos 3D, calcula custo de produção e gera listagem otimizada e imagem de produto via LLM.

Só que ela é um pipeline: passos fixos, na mesma ordem, sempre. Depois do curso, ficou claro o que falta para virar agente — e por que isso importa.

Num pipeline, se o scraping vem incompleto, o passo seguinte roda com dado ruim. Num agente, ele observa que faltou a gramatura, decide buscar de outra fonte ou pedir confirmação, e só então segue. A autonomia não está em fazer mais coisas — está em lidar com o caminho que deu errado.

No ambiente corporativo, especialmente em saúde, onde atuo, o raciocínio é o inverso: quanto maior a sensibilidade do dado, mais estreito o escopo do agente e mais obrigatório o humano no circuito. Agente autônomo em contexto regulado é excelente para preparar, cruzar e resumir informação — e nunca para decidir sozinho sobre ela.

O que eu levo do curso

• Agente é loop com critério de parada, não prompt elaborado.
• A qualidade das descrições das ferramentas define a qualidade das decisões.
• RAG é ferramenta do agente, não substituto dele.
• Comece com um agente e poucas ferramentas. Escale só quando doer.
• Observabilidade e guardrails vêm no dia 1, não quando o problema aparece.

E a lição que resume todas: construir um agente é 20% de LLM e 80% de engenharia de software clássica — tratamento de erro, idempotência, limites, logs, testes. A parte "IA" é a mais fácil.

Se você está começando nessa área, meu conselho é construir um agente pequeno e inútil de propósito, com 2 ferramentas, e observar o loop passo a passo. Você aprende mais em uma tarde fazendo isso do que em semanas lendo sobre frameworks.

Se você está trabalhando com Agentic AI, quero ouvir contra-argumentos: um agente único bem instrumentado ou arquitetura multiagente? Tenho defendido o primeiro. Me escreva — o link de contato está no rodapé.