Tutorial do Claude Agent SDK: exemplos em Python e TypeScript

O Claude Agent SDK permite executar, dentro do seu próprio programa em Python ou TypeScript, o mesmo ciclo de agente que alimenta o Claude Code. Você envia um prompt, e o Claude lê arquivos, executa comandos, edita código e chama suas próprias funções até terminar o trabalho, transmitindo cada etapa para você conforme avança. Este tutorial monta o SDK em camadas: uma primeira consulta em cada linguagem, ferramentas personalizadas, subagentes, hooks, limites de gasto e sessões retomáveis. Todo trecho segue a documentação atual, então você pode colá-lo, definir uma variável de ambiente e executar.

O que o Agent SDK faz

Um agente é um programa que decide o próprio próximo passo. Ele lê um pedido, escolhe uma ferramenta, analisa o resultado e continua até concluir a tarefa. O Agent SDK entrega esse ciclo pronto: as mesmas ferramentas integradas, o sistema de permissões, o gerenciamento de contexto e os hooks que funcionam dentro do Claude Code, expostos como uma biblioteca para Python e TypeScript.

A diferença prática em relação a chamar a API diretamente está em quem escreve o ciclo. Com o Client SDK, você envia uma mensagem, verifica se o Claude pediu uma ferramenta, executa a ferramenta, devolve o resultado e repete. Com o Agent SDK, você chama query() uma vez e itera sobre as mensagens que chegam enquanto o Claude faz o trabalho.

Cada volta desse ciclo segue o mesmo ritmo. O Claude recebe o prompt e as definições das ferramentas e então decide se responde ou chama uma ferramenta. O SDK executa a ferramenta e devolve o resultado, e o ciclo se repete até que o Claude não tenha mais nada a fazer ou um limite o interrompa. Cada etapa chega ao seu código como uma mensagem, por isso os exemplos a seguir se parecem com processamento de fluxo, e não com uma única requisição e resposta. Isso também significa que você pode mostrar o progresso ao usuário, registrar cada chamada de ferramenta ou interromper a execução antes do fim.

SDK, Client SDK ou CLI

Quatro opções parecem semelhantes, então esta tabela as separa por quem executa o agente.

💡 Dica: Para conduzir o mesmo ciclo a partir de outra linguagem, execute a CLI como um subprocesso com a flag -p e --output-format json.

O que você precisa antes

Três itens devem estar prontos antes da primeira linha de código:

• Python 3.10+ ou Node.js 18+
• Uma conta na Anthropic com uma credencial de API obtida no Claude Console
• Uma pasta de código para o agente trabalhar, porque, por padrão, ele pode ler arquivos no diretório de trabalho e em seus subdiretórios

Os dois pacotes incluem um binário nativo do Claude Code, então uma instalação normal não exige nada extra. Duas situações quebram isso: o pip recorrer à distribuição de código-fonte (o caso típico é o Windows ARM64) e uma instalação do npm que ignora dependências opcionais. Nos dois casos, instale o Claude Code nativamente e o SDK o encontrará.

Instalar e autenticar

Instalar o pacote

Para Python, crie um ambiente virtual e instale o pacote:

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

Copiar prompt

No PowerShell do Windows, a linha de ativação é .venv\Scripts\Activate.ps1. Para TypeScript, inicie um projeto e adicione o pacote junto com tsx:

npm init -y
npm pkg set type=module
npm install @anthropic-ai/claude-agent-sdk
npm install --save-dev tsx

Copiar prompt

Definir "type": "module" permite usar await no nível superior do seu script, e tsx executa arquivos TypeScript sem uma etapa de build.

Configure suas credenciais

O SDK lê sua credencial a partir de uma variável de ambiente no shell que executa o agente:

export ANTHROPIC_API_KEY=your-api-key

Copiar prompt

$env:ANTHROPIC_API_KEY = "your-api-key"

Copiar prompt

O SDK não carrega arquivos .env por conta própria. Se você guarda a credencial em um deles, carregue-o antes com python-dotenv ou com o pacote dotenv. Provedores de nuvem também funcionam: defina CLAUDE_CODE_USE_BEDROCK=1 para o Amazon Bedrock, CLAUDE_CODE_USE_VERTEX=1 para o Google Cloud ou CLAUDE_CODE_USE_FOUNDRY=1 para o Microsoft Foundry, e depois configure as credenciais desse provedor.

💡 Nota de política: A menos que a Anthropic tenha aprovado previamente, produtos de terceiros construídos sobre o SDK podem não oferecer login pelo claude.ai nem os mesmos limites de taxa. Use credenciais de API para tudo o que você publicar.

Seu primeiro agente em duas linguagens

Crie um arquivo chamado utils.py com dois bugs propositais. Uma lista vazia quebra a média, e um usuário inexistente quebra a busca pelo nome:

def calculate_average(numbers):
    total = 0
    for num in numbers:
        total += num
    return total / len(numbers)


def get_user_name(user):
    return user["name"].upper()

Copiar prompt

O agente abaixo é somente leitura. Ele pode examinar o arquivo, mas não tem permissão para alterar nada.

A versão em Python

import asyncio
from claude_agent_sdk import (
    query,
    ClaudeAgentOptions,
    AssistantMessage,
    ResultMessage,
    TextBlock,
)


async def main():
    options = ClaudeAgentOptions(
        system_prompt="You review Python code and report crash risks in plain language.",
        allowed_tools=["Read", "Glob", "Grep"],
        max_turns=8,
    )

    async for message in query(
        prompt="Look at utils.py and list every input that would crash it.",
        options=options,
    ):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if isinstance(block, TextBlock):
                    print(block.text)
        elif isinstance(message, ResultMessage):
            print(f"Finished: {message.subtype}, cost: ${message.total_cost_usd}")


asyncio.run(main())

Copiar prompt

Veja o que cada parte faz:

• query() retorna um iterador assíncrono, então você faz um loop com async for enquanto o Claude pensa, chama ferramentas e lê resultados
• allowed_tools pré-aprova Read, Glob e Grep, três ferramentas que podem inspecionar arquivos, mas nunca modificá-los
• Os blocos AssistantMessage trazem o texto do Claude e suas chamadas de ferramenta, então filtrar por TextBlock gera uma saída legível
• ResultMessage chega por último, com subtype, total_cost_usd, num_turns e session_id

A versão em TypeScript

Salve isto como agent.ts e execute com npx tsx agent.ts:

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Look at utils.py and list every input that would crash it.",
  options: {
    systemPrompt: "You review Python code and report crash risks in plain language.",
    allowedTools: ["Read", "Glob", "Grep"],
    maxTurns: 8
  }
})) {
  if (message.type === "assistant" && message.message?.content) {
    for (const block of message.message.content) {
      if ("text" in block) console.log(block.text);
    }
  } else if (message.type === "result") {
    console.log(`Finished: ${message.subtype}, cost: $${message.total_cost_usd}`);
  }
}

Copiar prompt

Execute qualquer um dos scripts e você deverá ver o Claude ler utils.py, descrever os dois erros (a divisão por zero em uma lista vazia e o TypeError em um usuário inexistente) e terminar com uma linha como Finished: success. Se aparecer um erro de autenticação como Not logged in, a variável de ambiente está ausente no shell que iniciou o script, que é o erro mais comum na primeira execução.

A lógica é idêntica nas duas linguagens, mas os nomes das opções mudam de capitalização. Mantenha esta tabela por perto, porque ela explica a maioria dos momentos de "por que isso não funciona" quando você porta código entre os dois SDKs.

As listas de ferramentas são o que permite aumentar ou reduzir a autonomia:

💡 Dois comportamentos a esperar: query() de uma única execução lança uma exceção depois de retornar um resultado de erro, como atingir o limite de turnos, então envolva o loop em try/except ou try/catch quando o script precisar continuar rodando. E, por padrão, o SDK lê a pasta .claude/ do seu projeto e ~/.claude/, da mesma forma que a CLI, de modo que configurações, skills e hooks definidos ali também se aplicam ao seu agente.

Criar ferramentas personalizadas

As ferramentas integradas cuidam de arquivos e do shell. Sua própria lógica, como uma consulta a um banco de dados ou uma chamada a uma API interna, pertence a uma ferramenta personalizada: uma função envolvida em um servidor MCP em processo, que roda dentro da sua aplicação, e não como um processo separado.

Uma ferramenta tem quatro partes: um nome, uma descrição que o Claude lê para decidir quando chamá-la, um esquema de entrada e um handler assíncrono que retorna um array content. Escreva a descrição como você instruiria um colega novo.

Você registra o servidor por meio de mcp_servers (mcpServers em TypeScript). O nome que você dá ao servidor nesse dicionário passa a fazer parte do nome completo da ferramenta, seguindo o padrão mcp__{server}__{tool}. Inclua esse nome completo nas ferramentas permitidas e a chamada será executada sem um pedido de permissão.

Uma ferramenta em Python

import asyncio
from typing import Any
from claude_agent_sdk import (
    tool,
    create_sdk_mcp_server,
    query,
    ClaudeAgentOptions,
    ResultMessage,
)

ORDERS = {"A100": "shipped", "A101": "packing"}


@tool("get_order_status", "Look up the status of an order by its id", {"order_id": str})
async def get_order_status(args: dict[str, Any]) -> dict[str, Any]:
    status = ORDERS.get(args["order_id"])
    if status is None:
        return {
            "content": [{"type": "text", "text": f"No order {args['order_id']}"}],
            "is_error": True,
        }
    return {"content": [{"type": "text", "text": f"Order {args['order_id']}: {status}"}]}


shop_server = create_sdk_mcp_server(
    name="shop", version="1.0.0", tools=[get_order_status]
)


async def main():
    options = ClaudeAgentOptions(
        mcp_servers={"shop": shop_server},
        allowed_tools=["mcp__shop__get_order_status"],
    )
    async for message in query(prompt="Where is order A100?", options=options):
        if isinstance(message, ResultMessage) and message.subtype == "success":
            print(message.result)


asyncio.run(main())

Copiar prompt

Uma ferramenta em TypeScript

O TypeScript descreve as entradas das ferramentas com Zod, então execute npm install zod primeiro:

import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";

const orders: Record<string, string> = { A100: "shipped", A101: "packing" };

const getOrderStatus = tool(
  "get_order_status",
  "Look up the status of an order by its id",
  { order_id: z.string().describe("Order id such as A100") },
  async (args) => {
    const status = orders[args.order_id];
    if (!status) {
      return {
        content: [{ type: "text", text: `No order ${args.order_id}` }],
        isError: true
      };
    }
    return { content: [{ type: "text", text: `Order ${args.order_id}: ${status}` }] };
  }
);

const shopServer = createSdkMcpServer({
  name: "shop",
  version: "1.0.0",
  tools: [getOrderStatus]
});

for await (const message of query({
  prompt: "Where is order A100?",
  options: {
    mcpServers: { shop: shopServer },
    allowedTools: ["mcp__shop__get_order_status"]
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

Copiar prompt

💡 Dica: Para falhas previsíveis, como um id de pedido inexistente, retorne is_error: True (isError: true em TypeScript) com sua própria mensagem. O Claude lê essa mensagem e pode tentar de novo ou explicar o problema, em vez de receber apenas o texto de uma exceção.

Subagentes, hooks e limites

Um agente funcionando é um começo. Três recursos mantêm um agente maior previsível: os subagentes dividem o trabalho, os hooks controlam cada chamada de ferramenta e os limites interrompem uma sessão descontrolada.

Delegar para subagentes

Um subagente é uma instância separada de agente que o agente principal cria para uma tarefa focada. Cada um começa com um contexto novo, então um revisor pode ler dezenas de arquivos sem inflar a conversa principal, e apenas a mensagem final dele volta para o pai. Você os define com a opção agents e adiciona Agent às ferramentas permitidas.

Cada definição precisa de uma description (quando o Claude deve usá-lo) e de um prompt (seu comportamento). Campos opcionais incluem tools, para restringir o que ele pode acessar, e model, que aceita os aliases sonnet, opus, haiku, fable e inherit, ou um ID completo de modelo.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition


async def main():
    options = ClaudeAgentOptions(
        allowed_tools=["Read", "Grep", "Glob", "Agent"],
        agents={
            "code-reviewer": AgentDefinition(
                description="Reviews code for security and maintainability problems.",
                prompt="You are a careful reviewer. Report concrete problems with file names.",
                tools=["Read", "Grep", "Glob"],
                model="sonnet",
            ),
            "test-runner": AgentDefinition(
                description="Runs the test suite and summarizes failures.",
                prompt="Run the tests, then list each failing test with its error.",
                tools=["Bash", "Read", "Grep"],
            ),
        },
    )
    async for message in query(
        prompt="Use the code-reviewer agent to check the auth module",
        options=options,
    ):
        if hasattr(message, "result"):
            print(message.result)


asyncio.run(main())

Copiar prompt

A versão em TypeScript usa objetos simples:

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Use the code-reviewer agent to check the auth module",
  options: {
    allowedTools: ["Read", "Grep", "Glob", "Agent"],
    agents: {
      "code-reviewer": {
        description: "Reviews code for security and maintainability problems.",
        prompt: "You are a careful reviewer. Report concrete problems with file names.",
        tools: ["Read", "Grep", "Glob"],
        model: "sonnet"
      }
    }
  }
})) {
  if ("result" in message) console.log(message.result);
}

Copiar prompt

Mencionar o subagente pelo nome no prompt, como acima, garante que o Claude o use. Sem isso, o Claude compara a tarefa com cada description, então descrições vagas significam delegações perdidas.

💡 Nota sobre a versão: A ferramenta aparece como Agent nos blocos de uso de ferramenta. Versões anteriores a chamavam de Task, e a lista de ferramentas na mensagem de inicialização ainda usa esse nome, então trate os dois nomes ao detectar chamadas de subagentes no fluxo de mensagens.

Bloquear chamadas arriscadas com hooks

Hooks são callbacks executados em pontos fixos do ciclo do agente. O mais útil é PreToolUse, que dispara antes de uma ferramenta rodar e pode negá-la. Um matcher filtra pelo nome da ferramenta, por exemplo Bash ou Write|Edit. Retorne {} para permitir a chamada.

Este hook em Python recusa qualquer comando de shell que contenha uma remoção recursiva:

import asyncio
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, HookMatcher


async def block_destructive_bash(input_data, tool_use_id, context):
    command = input_data["tool_input"].get("command", "")
    if "rm -rf" in command:
        return {
            "hookSpecificOutput": {
                "hookEventName": input_data["hook_event_name"],
                "permissionDecision": "deny",
                "permissionDecisionReason": "Recursive deletes are blocked",
            }
        }
    return {}


async def main():
    options = ClaudeAgentOptions(
        allowed_tools=["Bash", "Read"],
        hooks={
            "PreToolUse": [HookMatcher(matcher="Bash", hooks=[block_destructive_bash])]
        },
    )

    async with ClaudeSDKClient(options=options) as client:
        await client.query("Clean up the build folder")
        async for message in client.receive_response():
            print(message)


asyncio.run(main())

Copiar prompt

E a mesma proteção em TypeScript:

import { query, HookCallback, PreToolUseHookInput } from "@anthropic-ai/claude-agent-sdk";

const blockDestructiveBash: HookCallback = async (input) => {
  const pre = input as PreToolUseHookInput;
  const toolInput = pre.tool_input as Record<string, unknown>;
  const command = String(toolInput?.command ?? "");

  if (command.includes("rm -rf")) {
    return {
      hookSpecificOutput: {
        hookEventName: pre.hook_event_name,
        permissionDecision: "deny",
        permissionDecisionReason: "Recursive deletes are blocked"
      }
    };
  }
  return {};
};

for await (const message of query({
  prompt: "Clean up the build folder",
  options: {
    allowedTools: ["Bash", "Read"],
    hooks: { PreToolUse: [{ matcher: "Bash", hooks: [blockDestructiveBash] }] }
  }
})) {
  if (message.type === "result") console.log(message.subtype);
}

Copiar prompt

Quando vários hooks correspondem, eles rodam em paralelo e a resposta mais restritiva prevalece. Um único deny bloqueia a chamada, não importa o que os outros retornem, então escreva cada hook para funcionar de forma independente.

Limitar turnos e gastos

Os modos de permissão definem o nível padrão de confiança. Escolha um com permission_mode ou permissionMode:

Dois limites numéricos protegem sua carteira. max_turns (maxTurns) limita os turnos agênticos, e max_budget_usd (maxBudgetUsd) limita o gasto estimado. Ao atingi-los, a consulta termina com os subtipos de resultado error_max_turns ou error_max_budget_usd. As requisições de subagentes contam para o mesmo total_cost_usd, então um prompt que se desdobra em muitos subagentes continua submetido ao mesmo limite.

💡 Dica para tarefas sem supervisão: Combine dontAsk com uma lista explícita de ferramentas permitidas. Tudo fora dessa lista é negado imediatamente, em vez de esperar por um humano que não está lá.

Três erros aparecem repetidamente nos primeiros agentes:

• Conceder Bash cedo demais. Comece com ferramentas somente leitura e adicione Edit ou Bash apenas quando a tarefa exigir.
• Descrições vagas de subagentes. O Claude delega com base no texto de description, então "agente auxiliar" é ignorado, enquanto "Revisa código em busca de problemas de segurança" é usado.
• Nenhum limite na primeira execução. Defina max_turns e max_budget_usd antes de apontar o agente para um repositório grande.

Manter o contexto entre sessões

Cada chamada de query() inicia uma nova sessão. Quando uma pergunta de acompanhamento deve lembrar o que o agente já leu e decidiu, você precisa de uma forma de levar a sessão adiante.

Várias rodadas em Python

ClaudeSDKClient controla a sessão para você. Cada client.query() continua a mesma conversa:

import asyncio
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions


async def main():
    options = ClaudeAgentOptions(allowed_tools=["Read", "Edit", "Glob", "Grep"])

    async with ClaudeSDKClient(options=options) as client:
        await client.query("Inspect the auth module")
        async for message in client.receive_response():
            print(message)

        # Same session, so the agent remembers the first answer
        await client.query("Now refactor it to use JWT")
        async for message in client.receive_response():
            print(message)


asyncio.run(main())

Copiar prompt

Retomar em TypeScript

O TypeScript não tem um objeto cliente, então você captura o session_id da mensagem de resultado e o passa de volta por meio de resume:

import { query } from "@anthropic-ai/claude-agent-sdk";

let sessionId: string | undefined;

for await (const message of query({
  prompt: "Inspect the auth module",
  options: { allowedTools: ["Read", "Glob", "Grep"] }
})) {
  if (message.type === "result") sessionId = message.session_id;
}

for await (const message of query({
  prompt: "Now propose a refactor based on what you found",
  options: { resume: sessionId, allowedTools: ["Read", "Glob", "Grep"] }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

Copiar prompt

O Python aceita a mesma ideia como resume=session_id. As duas linguagens também oferecem continue_conversation=True / continue: true para retomar a sessão mais recente da pasta, e fork_session=True / forkSession: true para criar uma ramificação do histórico, de modo que você possa testar outra abordagem sem perder a original.

Dois limites importam na prática. As sessões armazenam a conversa, não os seus arquivos, então um agente bifurcado que edita código altera os arquivos reais. E os arquivos de sessão ficam na máquina que os criou, então retomar em outro host exige um adaptador de armazenamento de sessões ou uma transcrição copiada.

Use o Claude Sonnet 5 no PicassoIA

O Agent SDK roda na sua máquina, com as suas credenciais, então o PicassoIA não o substitui. É na etapa de rascunho que o PicassoIA ajuda. A redação de um prompt de sistema, de uma descrição de subagente ou de uma descrição de ferramenta define o quanto um agente se comporta bem, e testar a redação em uma interface de chat é mais rápido do que rodar um script dez vezes.

Rascunhe prompts antes de programar

O Claude Sonnet 5 foi criado para tarefas de programação em várias etapas e uso de ferramentas, o que o torna um bom substituto para ensaiar instruções de agente. Siga estes passos:

1. Abra a página do Claude Sonnet 5 no PicassoIA.
2. Cole o rascunho das instruções do agente no campo System Prompt.
3. Digite uma tarefa realista em Prompt, por exemplo o conteúdo de utils.py seguido de "liste cada entrada que poderia fazê-lo travar".
4. Defina o effort. O padrão é low, que desliga o raciocínio para obter a resposta mais rápida e mais barata. Aumente para high ou max em bugs que atravessam vários arquivos.
5. Deixe o max_tokens no padrão de 8192, o suficiente para código ou texto detalhado em uma única resposta.
6. Opcionalmente, anexe uma captura de tela de um erro pela entrada image, já que o modelo consegue lê-la.
7. Execute, ajuste a redação até a resposta corresponder ao que você quer e depois copie o texto final para system_prompt ou para o prompt de um subagente.

💡 Lembre-se: Isto ensaia apenas a redação. As ferramentas de arquivo, os hooks e o ciclo do agente continuam vindo do SDK na sua máquina.

Escolha o modelo Claude certo

O PicassoIA lista vários modelos Claude, e cada um serve a um tipo diferente de rascunho:

No próprio SDK, o campo model aceita os aliases descritos antes, então você pode rodar um modelo barato para os subagentes de rotina e um modelo mais forte para a thread principal.

Crie suas próprias imagens com o PicassoIA

Agora você tem um agente funcionando e o hábito de testar cada peça antes de publicá-la. O mesmo hábito melhora a geração de imagens, e o PicassoIA é um lugar rápido para praticar.

Abra o Seedream 4.5 ou o GPT Image 2 e escreva um prompt com a mesma estrutura usada nas fotos deste artigo: o sujeito e sua ação, o cenário, a direção da luz, a lente e uma ou duas texturas de superfície. Uma linha como "mãos digitando em uma mesa de madeira, luz suave de janela vinda da direita, lente de 85mm, profundidade de campo rasa, poeira visível no veio da madeira" dá ao modelo muito mais a trabalhar do que "um programador digitando".

Teste no próximo cabeçalho de blog, na foto de produto ou no banner de documentação de que você precisar. Mude um detalhe por vez, compare os resultados lado a lado e guarde o prompt que funciona. Quando quiser ver o que mais está disponível, navegue por todos os modelos em picassoia.com/en/all-models e comece sua primeira geração hoje.