O que faz um sistema ser um agente

Tudo nos quatro cursos anteriores tinha o mesmo formato: você decide o que acontece, e o modelo preenche um passo. Você recupera trechos, monta um prompt, faz uma chamada, faz o parsing da resposta. O fluxo de controle é seu.

Um agente inverte isso. O modelo decide o que acontece em seguida, uma vez atrás da outra, e o seu código executa essas decisões até o modelo dizer que terminou.

Essa é a definição inteira, e a mudança é maior do que parece. Um pipeline tem um número fixo de passos, que você lê no código-fonte. Um agente percorre um número de passos que ninguém sabe de antemão, escolhidos por algo que não é o seu código.

Três níveis

flowchart TB
  A["Chamada única: uma requisição, uma resposta"] --> B["Workflow: várias chamadas, seu código decide a ordem"]
  B --> C["Agente: o modelo decide a ordem, e quando parar"]

Chamada única

Classifique esta mensagem. Resuma este documento. Tudo do curso de few-shot.

Workflow

Recupere, depois reordene, depois gere. São várias chamadas de modelo, mas a sequência está no seu código e é a mesma toda vez. O pipeline de RAG é um workflow.

Agente

"Descubra por que este cliente foi cobrado em dobro." O modelo consulta a tabela de pagamentos, nota um webhook duplicado, confere o log de webhooks, encontra uma retentativa e relata. Você não escreveu essa sequência, nem poderia, porque ela depende do que a primeira consulta devolveu.

Cada nível custa mais, é mais lento e é mais difícil de entender do que o anterior. Comece pelo primeiro e só desça quando a tarefa exigir.

As quatro perguntas antes de construir um

Antes de escolher o nível de agente, as quatro condições abaixo precisam valer.

Complexidade

A tarefa tem vários passos e é difícil de especificar de antemão? "Transforme este documento de design num pull request" se qualifica. "Extraia o título deste PDF" não: isso é uma chamada única fantasiada de agente.

Valor

O resultado justifica custo e latência maiores? Uma execução de agente são muitas chamadas de modelo e leva de segundos a minutos.

Viabilidade

O modelo é bom nessa tarefa? Um agente não conserta uma tarefa que o modelo erra numa chamada única. Ele repete o erro várias vezes e o agrava.

Custo do erro

Dá para pegar e reverter os erros? Testes, revisão e rollback tornam os erros contornáveis. Um agente que envia e-mails para clientes não tem como desfazer o envio.

Se alguma resposta for não, construa o workflow. O motivo vai além da cautela: um workflow com bug pode ser depurado, e um agente com bug vira uma história sobre o que aconteceu naquela vez.

O laço

Tirando a embalagem, todo agente é isto:

flowchart TB
  S["Envia mensagens + definições de ferramenta"] --> M["Modelo responde"]
  M --> D{"stop_reason"}
  D -->|"tool_use"| E["Executa as ferramentas pedidas"]
  E --> A["Anexa os resultados às mensagens"]
  A --> S
  D -->|"end_turn"| F["Pronto: o texto final é a resposta"]

É só isso. Você não precisa de uma API de agente especial. É o mesmo messages.create que você já vem chamando, dentro de um laço, com o seu código executando os pedidos de ferramenta do modelo e devolvendo os resultados. O resto deste curso trata do que acontece dentro desse laço quando ele encontra um sistema real: quais ferramentas você expõe, o que permite sem perguntar, como impedir que ele rode para sempre e como descobrir o que ele fez.

Autonomia é um ajuste

"Autônomo" tem mais de duas posições. A palavra mede o quanto o agente pode fazer sem perguntar:

A maioria dos agentes em produção fica na terceira linha, e o trabalho de design é decidir quais ferramentas ganham um portão. Um critério útil, e ao qual este curso volta sempre, é a reversibilidade. Ler uma tabela é reversível. Enviar um e-mail não é.

O que este curso cobre

Tudo aqui é Ruby puro usando a API do Claude, sem framework, porque o laço tem vinte linhas e entendê-lo é o objetivo.

1. O que faz um sistema ser um agente (você está aqui).
2. O laço agêntico, escrito à mão.
3. Projetando a superfície de ferramentas.
4. O tool runner, e quando manter o seu próprio laço.
5. Segurança: portões, orçamentos e o problema da injeção.
6. Execuções longas: contexto, memória e custo.
7. Juntando tudo: um agente como objetos Rails, e como saber se ele funciona.

A seguir: o laço em si, em código, com os três erros que todo mundo comete na primeira vez.