Como construir o teu primeiro agente de IA: um modelo, algumas ferramentas e um ciclo

"Agente de IA" soa como algo que deveria exigir uma framework, uma base de dados vetorial e um fim de semana de configuração. Não exige. A própria definição da Anthropic é refrescantemente pequena: um agente é um LLM a usar ferramentas autonomamente num ciclo. Assim que percebes o padrão, consegues construir um primeiro agente útil em bem menos de cem linhas de código — e, igualmente importante, saber quando não o devias fazer.

O ciclo central

Todo o agente, por mais sofisticado que seja, é o mesmo ciclo de quatro passos:

1. Dás ao modelo um objetivo e uma lista de ferramentas que ele está autorizado a chamar.
2. O modelo decide se responde diretamente ou se chama uma ferramenta.
3. O teu código executa a ferramenta e devolve o resultado ao modelo.
4. Repete até o modelo dizer que terminou.

O modelo nunca toca no teu sistema de ficheiros ou na rede por si só. Ele apenas pede para executar uma ferramenta; o teu código decide se e como realmente o fazer. É nessa lacuna que vive toda a tua segurança.

Um exemplo concreto

Aqui está um agente mínimo que consegue responder a perguntas usando uma ferramenta de calculadora. O que importa é a estrutura — a mesma forma escala para edição de ficheiros, pesquisa na web ou consultas a bases de dados.

import anthropic

client = anthropic.Anthropic()

tools = [{
    "name": "calculator",
    "description": "Evaluate a basic arithmetic expression and return the result.",
    "input_schema": {
        "type": "object",
        "properties": {"expression": {"type": "string"}},
        "required": ["expression"],
    },
}]

def run_tool(name, args):
    if name == "calculator":
        # In real code, use a safe parser, not eval()
        return str(eval(args["expression"], {"__builtins__": {}}))
    return "unknown tool"

messages = [{"role": "user", "content": "What is 1894 * 37 plus 12?"}]

while True:
    resp = client.messages.create(
        model="claude-sonnet-4-6",
        max_tokens=1024,
        tools=tools,
        messages=messages,
    )
    messages.append({"role": "assistant", "content": resp.content})

    if resp.stop_reason != "tool_use":
        print(resp.content[0].text)
        break

    tool_results = []
    for block in resp.content:
        if block.type == "tool_use":
            result = run_tool(block.name, block.input)
            tool_results.append({
                "type": "tool_result",
                "tool_use_id": block.id,
                "content": result,
            })
    messages.append({"role": "user", "content": tool_results})

Esse ciclo while é o agente. O modelo vê a pergunta, pede para chamar a calculator com "1894 * 37 + 12", o teu código executa-a, devolve 70090 e o modelo escreve a resposta final. Troca a calculadora por um par read_file/write_file e tens um agente de programação primitivo.

As ferramentas são a parte que realmente importa

O modelo só é tão capaz quanto as ferramentas que lhe dás, e o design das ferramentas é onde a maioria dos primeiros agentes falha. As orientações da Anthropic sobre escrever ferramentas para agentes resumem-se a algumas regras:

• Nomeia e descreve as ferramentas como se estivesses a escrever para um novo colega de equipa. search_invoices(customer_id, date_range) é melhor do que um vago query(sql) — quanto mais claro o contrato, menos chamadas erradas.
• Devolve resultados com elevado sinal, não despejos em bruto. Se uma ferramenta devolve 5000 linhas de JSON, acabaste de gastar o orçamento de contexto do modelo em ruído. Reduz ao que é útil.
• Torna os erros instrutivos. "Ficheiro não encontrado: querias dizer config.yaml?" permite ao modelo recuperar; um simples rastreio de pilha normalmente não permite.

Salvaguardas antes de o deixares correr

Como o teu código executa cada chamada de ferramenta, a segurança é tua responsabilidade. Três salvaguardas a adicionar antes de qualquer agente tocar em algo real:

• Limita o ciclo. Adiciona uma contagem máxima de iterações para que um agente confuso não possa girar para sempre (e acumular uma fatura).
• Controla ações destrutivas. Tudo o que apaga, envia ou paga deve exigir confirmação ou correr primeiro contra um ambiente isolado (sandbox).
• Valida as entradas das ferramentas. Nunca faças eval() de strings não confiáveis nem passes a saída do modelo diretamente para uma shell. Trata cada argumento de ferramenta como entrada de utilizador não confiável — porque, na prática, é isso que é.

Quando NÃO construir um agente

A coisa mais útil de aprender cedo: muitos problemas não precisam de nenhum agente. Se os passos são conhecidos à partida — obter dados, resumi-los, enviar o resumo por email — um simples script com uma ou duas chamadas ao modelo é mais barato, mais rápido e mais fácil de depurar. A Anthropic chama a estes fluxos de trabalho (workflows) e recomenda-os sempre que o caminho é previsível. Recorre a um verdadeiro agente apenas quando o modelo precisa genuinamente de decidir o que fazer a seguir com base no que encontra.

Começa pelo ciclo de quatro passos acima, dá-lhe uma ou duas ferramentas bem descritas, limita as iterações e adiciona uma tarefa real. Vais aprender mais com um agente a funcionar do que com qualquer quantidade de documentação de frameworks.