Construa um Agente de IA

history := []Message{{Role: "user", Content: request}}
for turn := 0; turn < maxTurns; turn++ {
	decision, err := model.Next(history)
	if err != nil { return "", err }
	if decision.Final != "" { return decision.Final, nil }
	tool, ok := tools[decision.Tool]
	if !ok { return "", fmt.Errorf("tool desconhecida") }
	output, err := tool(decision.Input)
	if err != nil { return "", err }
	// Pedido e resultado alimentam a próxima decisão.
	history = append(history, Message{Role: "assistant", Content: decision.Tool},
		Message{Role: "tool", Content: output})
}

Uma conversa responde com texto. Um agente precisa fazer algo no meio do caminho. Imagine uma pessoa em uma central de atendimento: ela lê o pedido, decide consultar um sistema, anota o resultado e só então responde. Se ela consultar e jogar fora a anotação, a próxima decisão começa cega. Se continuar consultando para sempre, o atendimento nunca termina. O loop do agente é essa rotina operacional transformada em código.

O risco não é apenas receber uma resposta ruim. Um laço sem condição de parada pode consumir orçamento indefinidamente; um resultado omitido faz o modelo repetir a mesma chamada; uma tool escolhida por texto livre pode executar algo que a aplicação nunca ofereceu. Por isso o agente não é “um prompt maior”. Ele é uma máquina de estados sob controle do seu programa.

Em cada turno, o modelo devolve uma de duas intenções: pedir uma tool ou encerrar com resposta final. No primeiro caso, Go valida o nome, executa uma função registrada, acrescenta pedido e resultado ao histórico e consulta o modelo novamente. No segundo, o loop devolve a resposta. A API do modelo é uma dependência; a política do loop pertence à aplicação.

Fixtures gravadas substituem a rede durante aprendizado e teste. Elas reproduzem uma sequência conhecida — lookup, resultado, resposta final — e deixam você observar o protocolo. Depois, trocar a fixture pelo cliente estudado no mini Claude API não muda o núcleo. Esse isolamento é a razão do pré-requisito: você já conhece mensagens e tool calling; agora passa a orquestrá-los.

Há duas perguntas úteis ao revisar esse desenho. Primeiro: qual dado entra no próximo turno e de onde ele veio? Segundo: qual trecho autoriza um efeito? Se a resposta depender de convenção oral ou de texto escondido no prompt, o programa está delegando política demais. Tipos, registros e limites devem responder essas perguntas no código.

A visualização acompanha o estado, não o tempo de parede. Cada frame adiciona uma consequência observável do anterior. Isso permite conferir a sequência com uma fixture e repetir a execução byte por byte. Em um cliente real, latência e conteúdo variam; o protocolo e as guardas permanecem os mesmos.

Antes de rodar, preveja quantas vezes Next será chamado e qual conteúdo estará no último item do histórico. Depois altere a fixture para pedir upper duas vezes antes do final. Por fim, reduza o limite para um turno e observe que a resposta final deixa de ser alcançável. A pergunta é: qual evento permite ao próximo turno saber o que a tool produziu?