Agent SDK: construir um agente próprio

A Ana tem uma loja online pequena, em Velas, que vende queijo e doces de São Jorge. Todas as manhãs exporta as encomendas da noite para um ficheiro e passa meia hora a copiá-las para uma lista. Já pediste ao Claude Code para fazer isto à mão, e funciona. Mas a Ana não quer abrir o terminal às sete da manhã. Quer um programa que o faça sozinho.

O conceito: o mesmo motor, outro volante

No terminal, o Claude Code é uma conversa: tu pedes, ele propõe, tu aprovas. O motor por baixo faz sempre o mesmo ciclo: lê, decide, usa uma ferramenta, vê o resultado e repete até acabar.

O Agent SDK dá-te esse motor dentro de um programa teu, em Python ou TypeScript. O pedido, as ferramentas e os limites passam a estar escritos no código. O que fazer com a resposta também: guardar num ficheiro, juntar a um registo, deitar fora.

A diferença importante é que ninguém está a olhar. No terminal, és tu o travão. Num programa, os travões têm de estar escritos.

Dois usos realistas:

• um agente que lê o ficheiro das encomendas da loja e escreve a lista do dia;
• um agente que todas as manhãs compara uma página com a de ontem e resume o que mudou (fazes este na lição 05).

Como se faz hoje: o programa mais pequeno

Isto é como está a 6 de Outubro de 2026; se o ecrã for diferente, procura o botão com o mesmo nome. Guia: code.claude.com/docs/en/agent-sdk/quickstart.

Precisas de Python 3.10 ou mais recente. Numa pasta nova, cria um ambiente virtual e instala o pacote:

python3 -m venv .venv
source .venv/bin/activate
pip install claude-agent-sdk

No Windows, cria o ambiente com py -m venv .venv e activa-o com .venv\Scripts\Activate.ps1. O pacote já traz o motor do Claude Code, por isso na maioria dos casos não precisas de instalar mais nada.

Agora o programa, num ficheiro agente.py:

import asyncio
from pathlib import Path
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

async def main():
    encomendas = Path("encomendas.txt").read_text(encoding="utf-8")   # quem lê é o teu código
    opcoes = ClaudeAgentOptions(
        cwd=".",                         # pasta inicial do agente (não é uma caixa fechada)
        disallowed_tools=["*"],          # sem ferramentas: recebe texto, devolve texto
        permission_mode="dontAsk",       # o que precisaria de autorização é recusado
        max_turns=5,                     # tecto de voltas
        max_budget_usd=0.50,             # tecto de gasto desta execução
    )
    try:
        async for msg in query(
            prompt="Faz uma lista destas encomendas: cliente, produto, quantidade. Não inventes nada.\n\n" + encomendas,
            options=opcoes,
        ):
            if isinstance(msg, ResultMessage):
                print(msg.result)
                print("Fim:", msg.subtype, "| custo estimado:", msg.total_cost_usd)
    except Exception as erro:
        print("Parou com erro:", erro)

asyncio.run(main())

Corre-o com python agente.py. O agente vai mandando mensagens enquanto trabalha; este programa ignora-as e só imprime a última, o ResultMessage, com a resposta, o motivo do fim e o custo estimado.

Os travões, linha a linha

• disallowed_tools=["*"] tira todas as ferramentas ao agente: recebe texto e devolve texto, e quem lê e grava ficheiros é o teu código. Um nome sozinho, como "Bash", tira só essa. É o disallowed_tools que proíbe; o allowed_tools, que este exemplo não usa, só aprova sem perguntar e não proíbe nada.
• cwd é a pasta onde o agente começa, não uma caixa fechada. Se lhe desses a ferramenta de leitura, podia ler qualquer ficheiro da pasta, incluindo um .env com a chave; por isso o ficheiro vai no pedido.
• permission_mode="dontAsk" recusa tudo o que precisaria de autorização, em vez de ficar à espera.
• max_turns e max_budget_usd param o agente. Quando um deles chega ao limite, o motivo do fim é error_max_turns ou error_max_budget_usd, e o SDK lança um erro a seguir. Por isso o ciclo está dentro de um try.

Guia: code.claude.com/docs/en/agent-sdk/permissions.

A chave e o tecto de gasto

O SDK precisa de uma chave de API na variável ANTHROPIC_API_KEY. Guarda-a no .env, fora do Git, como na lição 1/06. O SDK não lê o .env sozinho: o teu programa tem de o carregar antes de chamar o SDK.

A documentação é clara: um programa feito para outras pessoas usa uma chave de API, não o login da tua conta claude.ai.

O max_budget_usd trava uma execução, mas é um travão aproximado: conta custos estimados e só é verificado entre voltas, por isso a execução pode passar um pouco do valor. O limite de gasto na consola do fornecedor, que puseste na lição 1/06, trava o mês. Precisas dos dois. Os valores dependem do modelo e do plano: consulta a página Estado actual.

E do lado da OpenAI?

O caminho mais curto é o codex exec "pedido": corre o Codex sem conversa e escreve a resposta final no ecrã. Por omissão, só pode ler. Para programas existe também o Codex SDK, em Python (pip install openai-codex) e TypeScript. Guia: learn.chatgpt.com/docs/non-interactive-mode.

Não confundas com o OpenAI Agents SDK (pacote openai-agents). É outra coisa: uma biblioteca para construíres agentes de raiz com os modelos da OpenAI, sem o motor do Codex.