Criar Agentes Autónomos com o Claude Code SDK: Um Guia Prático para Programadores

Construir Agentes Autónomos com o Claude Code SDK: Um Guia Prático para Programadores

O Claude Code SDK — oficialmente designado Agent SDK — é uma biblioteca Python e TypeScript que permite controlar programaticamente o motor agêntico completo do Claude Code: sem terminal, sem uma pessoa ao teclado, apenas a sua aplicação a chamar uma função assíncrona query() e a receber em stream cada passo do trabalho do agente. Se já utilizou o Claude Code de forma interativa, o SDK dá-lhe esse mesmo ciclo de ler-ficheiros / editar-código / executar-comandos como uma biblioteca componível que pode incorporar em pipelines de CI, bots de revisão de código, orquestradores multi-agente ou em qualquer serviço de back-end.

O Que É o Agent SDK — e Porque Existe

O Claude Code é bem conhecido como uma ferramenta de terminal. Escreve-se um prompt, o agente raciocina sobre a sua base de código, chama ferramentas incorporadas (Read, Edit, Bash, Grep, entre outras) e devolve-lhe os resultados. Mas no momento em que se pretende automatizar esse ciclo — desencadear uma revisão em cada pull request, distribuir tarefas por vários subagentes especializados, ou construir um produto sobre ele — a CLI interativa é a abstração errada. É necessária uma biblioteca.

O Agent SDK preenche essa lacuna. De acordo com a documentação oficial da Anthropic, este expõe "as mesmas ferramentas, o mesmo ciclo de agente e a mesma gestão de contexto que alimentam o Claude Code, programáveis em Python e TypeScript." Isto não é linguagem de marketing — é a arquitetura literal. O SDK inicia o binário da CLI do Claude Code como um subprocesso gerido, comunica com ele via stdio, e apresenta tudo como um fluxo assíncrono de objetos de mensagem tipados que o seu código pode consumir e a que pode reagir.

Esta distinção é importante por várias razões:

Mesmo motor, interface diferente. Ao mudar da CLI para o SDK, não está a passar para uma ferramenta inferior ou mais simples. O SDK herda todas as capacidades da CLI — conectividade com servidores MCP, ciclo de vida de hooks, ficheiros de skills, memória CLAUDE.md, delegação em subagentes e o conjunto completo de ferramentas.

O SDK executa as ferramentas por si. Se utilizar o Anthropic Client SDK (o pacote Python/JS de nível mais baixo anthropic) e quiser que o Claude chame ferramentas, tem de implementar o ciclo de ferramentas você mesmo: chamar a API, detetar uma resposta de utilização de ferramenta, executar a ferramenta, devolver o resultado, repetir até o Claude parar. O Agent SDK colapsa todo esse ciclo num único async for message in query(...) — o Claude decide que ferramentas chamar, executa-as dentro do seu subprocesso e continua o ciclo até a tarefa estar concluída. Basta consumir o stream.

Concebido para funcionamento headless. Os pedidos de permissão da CLI — "permitir este comando bash?" — bloqueiam à espera de intervenção humana. O SDK substitui-os por uma opção permissionMode e um conjunto de modos de permissão — por exemplo, acceptEdits para aprovar automaticamente edições de ficheiros e bypassPermissions para executar tudo sem perguntar num ambiente de CI protegido — além de um callback de aprovação programático para fluxos personalizados. Os nomes e comportamentos exatos dos modos estão documentados na referência do SDK da Anthropic (consulte-a para a lista atual), mas o efeito é o mesmo: a sua automação nunca fica pendurada à espera de uma tecla.

O mesmo motor do Claude Code, duas interfaces: a CLI interativa para trabalho com intervenção humana, e o Agent SDK para automação programática e headless em que a sua aplicação controla o prompt e um modo de permissão substitui a caixa de diálogo de aprovação.

Instalar o SDK

A Anthropic publica dois pacotes:

• TypeScript: @anthropic-ai/claude-agent-sdk (npm)
• Python: claude-agent-sdk (pip; requer Python 3.10+)

O pacote TypeScript inclui um binário nativo do Claude Code para a sua plataforma, pelo que não é necessária uma instalação separada da CLI. A autenticação é feita através de uma variável de ambiente ANTHROPIC_API_KEY obtida na Anthropic Console. O SDK também suporta o Amazon Bedrock, o Google Vertex AI e o Microsoft Azure AI Foundry — consulte a documentação da Anthropic para os padrões de variáveis de ambiente relevantes.

Conceitos Fundamentais

Compreender quatro conceitos cobre a grande maioria da utilização real do SDK.

1. A Função query() e o Fluxo Assíncrono de Mensagens

Toda a interação com o SDK começa com query(). Passa-se uma string prompt e um objeto options; em troca, obtém-se um iterador assíncrono que devolve objetos de mensagem tipados à medida que o agente trabalha. O ciclo termina quando o agente conclui a tarefa ou encontra um erro.

As mensagens recebidas incluem:

• AssistantMessage — o texto de raciocínio do Claude e as descrições das chamadas a ferramentas
• ToolResultMessage — o resultado de cada execução de ferramenta
• ResultMessage — o resultado final, com um campo subtype que indica sucesso ou falha
• SystemMessage — eventos do ciclo de vida da sessão (o subtipo init carrega o session_id)

Na maioria do código de produção, filtra-se por ResultMessage para extrair o resultado final e, opcionalmente, regista-se os blocos AssistantMessage para seguir o que o agente fez.

2. Ferramentas e allowedTools

O conjunto de ferramentas incorporadas do SDK mapeia diretamente para as capacidades do Claude Code:

A opção allowedTools pré-aprova um subconjunto destas, concedendo efetivamente ao agente permissão para as chamar sem qualquer verificação adicional. Um agente de auditoria apenas de leitura pode listar apenas ["Read", "Glob", "Grep"]; uma automação completa pode incluir ["Read", "Edit", "Bash", "Glob", "Grep"].

3. Modos de Permissão

Os modos de permissão controlam o que acontece quando o agente quer usar uma ferramenta que não está pré-aprovada em allowedTools:

• acceptEdits — aprova automaticamente edições de ficheiros e operações comuns do sistema de ficheiros; pede confirmação para tudo o resto. Ideal para fluxos de trabalho de desenvolvimento fidedignos.
• dontAsk — recusa silenciosamente tudo o que não esteja em allowedTools. Ideal para agentes headless totalmente restritos.
• bypassPermissions — executa todas as ferramentas sem qualquer verificação. Utilizar apenas dentro de um ambiente protegido.

O SDK também expõe um callback de aprovação programático para que possa implementar lógica de aprovação totalmente personalizada, e os nomes dos modos disponíveis podem expandir-se ao longo do tempo — consulte a referência do SDK da Anthropic para a lista atual e autoritativa e o comportamento exato de cada modo. Em CI, quase sempre utilizará uma configuração rigorosamente delimitada e de recusa por defeito, ou bypassPermissions dentro de um contentor protegido que controla.

4. Sessões, Retoma e Contexto

Cada chamada a query() cria (ou retoma) uma sessão. O session_id da sessão chega na primeira SystemMessage com subtype === "init". Pode capturá-lo e passá-lo como resume: sessionId numa chamada subsequente para retomar exatamente onde a conversa ficou — as mesmas leituras de ficheiros, o mesmo histórico de raciocínio, a mesma janela de contexto.

É assim que se constroem agentes com múltiplas interações: uma chamada a query() analisa um módulo, captura o session_id, e uma segunda chamada a query() (com resume) refere-se a "ele" ou "o ficheiro que acabou de ler" sem ter de repetir a explicação. As transcrições de sessão são escritas por defeito no disco local; para produção, pode associar um adaptador SessionStore suportado por S3, Redis ou Postgres para que as sessões sobrevivam a reinícios de contentores.

Padrão de Construção 1: Um Bot de Revisão de Código em CI

Este é o caso de uso canónico de "automação headless". A cada pull request, uma tarefa de CI faz checkout do branch, executa um agente que lê os ficheiros alterados e publica um comentário de revisão.

O fluxo:

1. Um evento de PR desencadeia um workflow do GitHub Actions (ou uma tarefa de GitLab CI).
2. O runner faz checkout do branch e executa o seu script de revisão.
3. O seu script chama query() com um prompt de revisão, allowedTools: ["Read", "Glob", "Grep", "Bash"], e permissionMode: "dontAsk".
4. O Claude lê o diff, procura padrões, raciocina sobre as conclusões.
5. A ResultMessage transporta o texto da revisão; o seu script publica-o no PR através da API do GitHub.

A escolha de design fundamental é usar dontAsk com uma lista de ferramentas apenas de leitura. O agente não pode escrever ficheiros nem fazer chamadas de rede além do que as ferramentas permitem, pelo que a sua tarefa de CI não pode acidentalmente fazer merge de commits ou chamar APIs externas. Um limite de maxTurns (definido nas opções) delimita a profundidade do agente para que ciclos descontrolados não consumam o orçamento.

Para a arquitetura ilustrada deste fluxo, veja o diagrama abaixo.

Um pipeline de revisão de código totalmente automatizado. O agente do SDK executa dentro de um contentor de CI com uma lista de ferramentas apenas de leitura; as conclusões chegam em stream como uma ResultMessage e o seu código publica-as como um comentário de PR no GitHub. O agente nunca escreve ficheiros, nunca sai do contentor.

Pode estender este padrão com hooks — uma funcionalidade do SDK abordada no nosso artigo aprofundado sobre hooks do Claude Code — para registar cada chamada de ferramenta num ficheiro de auditoria, bloquear a leitura de caminhos de ficheiro específicos, ou emitir telemetria estruturada juntamente com a revisão.

Padrão de Construção 2: Cadeias de Ferramentas Multi-Agente

A opção agents do SDK permite definir subagentes nomeados, cada um com o seu próprio prompt de sistema, lista de ferramentas e permissões. O seu agente principal delega trabalho a estes através da ferramenta incorporada Agent. As mensagens dos subagentes incluem um campo parent_tool_use_id para que possa rastrear exatamente qual delegação produziu cada parte do resultado.

Um exemplo prático: uma cadeia de agentes de auditoria de segurança em que um subagente code-scanner encontra potenciais vulnerabilidades usando Grep e Glob, um subagente dependency-checker executa Bash para consultar os metadados dos seus pacotes, e um agente coordenador sintetiza ambos os relatórios numa auditoria unificada. Cada subagente tem o acesso mínimo a ferramentas necessário para a sua função, limitando o raio de impacto caso um subagente alucine um comando perigoso.

As cadeias multi-agente funcionam bem para tarefas que se decompõem naturalmente: um agente por área de responsabilidade, cada um com uma lista de ferramentas restrita, orquestrados por um coordenador que apenas precisa de Read e Agent. Para uma visão mais ampla de como as arquiteturas multi-agente se combinam com funcionalidades do Claude Code como a memória CLAUDE.md e os ficheiros de skills, consulte o nosso guia de harness engineering.

Padrão de Construção 3: Pipelines de Automação Headless

Para além da revisão de código, o SDK destaca-se em qualquer automação recorrente em que o agente é um passo de um pipeline maior:

Auditorias noturnas de dependências. Uma tarefa cron chama query() com um prompt para verificar pacotes desatualizados, executar scanners de segurança e produzir um relatório estruturado. A ferramenta Bash executa npm audit ou pip check; Read inspeciona os ficheiros de lock. A ResultMessage alimenta uma notificação no Slack.

Tradução e i18n ao fazer merge de PRs. Quando um PR é fundido, um webhook desencadeia um agente que lê os ficheiros de strings alterados com Glob e Read, produz versões traduzidas com Write, e abre um novo PR através de Bash (executando gh pr create).

Deteção de anomalias em logs. Passe a saída de logs recentes para um prompt de query(). O agente lê ficheiros de contexto adicionais se necessário, raciocina sobre os logs e emite uma conclusão estruturada. Não são necessárias escritas de ficheiros; uma lista de ferramentas apenas de leitura é suficiente.

Sincronização de documentação. Depois de os PRs serem fundidos, um agente lê os ficheiros-fonte atualizados e reescreve as páginas de documentação correspondentes, depois faz commit das alterações. O permissionMode: "acceptEdits" trata das escritas de ficheiros sem pedir confirmação.

O fio condutor comum: query() substitui uma integração de LLM feita à medida. Não implementa um ciclo de ferramentas, não gere manualmente janelas de contexto, nem analisa a saída do modelo para decidir o que executar a seguir. O agente trata da orquestração; você fornece o prompt e consome o resultado.

Um Exemplo Ilustrativo Detalhado: Um Agente de Correção de Bugs

O quickstart oficial demonstra este padrão de forma clara (o código abaixo segue a API documentada — verifique a sintaxe exata na documentação de quickstart da Anthropic):

Python ilustrativo (verifique a API exata na documentação oficial):

# Illustrative — confirm exact import paths and option names in official docs
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage

async def run_bug_fixer(file_path: str):
    async for message in query(
        prompt=f"Review {file_path} for bugs that would cause crashes. Fix any issues.",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Glob"],
            permission_mode="acceptEdits",
        ),
    ):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)
        elif isinstance(message, ResultMessage):
            print(f"Completed: {message.subtype}")

asyncio.run(run_bug_fixer("src/utils.py"))

TypeScript ilustrativo (verifique a API exata na documentação oficial):

// Illustrative — confirm exact import paths and option names in official docs
import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Review src/utils.ts for crash-causing bugs and fix them.",
  options: {
    allowedTools: ["Read", "Edit", "Glob"],
    permissionMode: "acceptEdits",
  },
})) {
  if (message.type === "assistant" && message.message?.content) {
    for (const block of message.message.content) {
      if ("text" in block) console.log(block.text);
    }
  }
  if (message.type === "result") console.log("Done:", message.subtype);
}

O que acontece quando isto é executado: o Claude lê utils.py (ou .ts) usando a ferramenta Read, raciocina sobre o código, identifica casos limite, e depois chama Edit para inserir tratamento defensivo. Vê o raciocínio e as chamadas de ferramentas a chegar em stream como objetos AssistantMessage; a ResultMessage final sinaliza a conclusão. Todo o ciclo do agente — incluindo reler o ficheiro para verificar a edição — é gerido pelo SDK.

É isto que torna o SDK diferente de chamar diretamente a API de modelos da Anthropic: não implementa a camada de execução de ferramentas. O Claude decide quando chamar Read, chama-a, recebe de volta o conteúdo do ficheiro e continua a raciocinar. O ciclo é autónomo.

Permissões, Sandboxing e Segurança em Produção

Executar agentes autónomos em produção requer pensar cuidadosamente sobre o que estes podem tocar. O SDK fornece vários controlos em camadas.

A delimitação de ferramentas é a primeira linha de defesa. Se um agente não precisar de Bash, não o inclua em allowedTools. Um agente apenas com ["Read", "Glob", "Grep"] não pode modificar ficheiros, executar comandos de shell ou fazer chamadas de rede, independentemente do que o seu prompt diga.

Os modos de permissão fornecem uma segunda barreira. dontAsk garante que tudo o que estiver fora de allowedTools é silenciosamente recusado em vez de pedir confirmação. Isto é crítico em ambientes headless — um pedido de confirmação que fica pendurado à espera de intervenção do utilizador irá bloquear o seu pipeline.

A opção cwd delimita o acesso do agente ao sistema de ficheiros a um diretório específico. Em ambientes multi-tenant, passe um diretório de trabalho por sessão para que os agentes de diferentes tenants não possam ler ficheiros uns dos outros.

O isolamento entre tenants requer passos adicionais: definir settingSources: [] para que nenhuma definição do sistema de ficheiros seja partilhada entre tenants; definir CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 para impedir o carregamento da memória automática; apontar CLAUDE_CONFIG_DIR para um caminho por tenant. Estes aspetos estão documentados em detalhe no guia de alojamento da Anthropic.

O sandboxing em contentores é a camada exterior. Para agentes de produção que precisem de acesso Bash, execute o SDK dentro de um contentor com o tráfego de saída de rede restrito aos domínios que autoriza explicitamente. Fornecedores como Modal, E2B, Cloudflare Sandboxes, Fly Machines e Vercel Sandbox são referidos na documentação da Anthropic como opções para implementações do SDK em sandbox.

maxTurns limita o número de idas e voltas de utilização de ferramentas, delimitando tanto o custo como os ciclos descontrolados. Defina-o com base na complexidade esperada da sua tarefa — uma revisão simples de leitura de ficheiros pode precisar de 5 a 10 turnos; uma refatoração complexa envolvendo múltiplos ficheiros pode precisar de 30 a 50.

Para equipas que constroem hooks de produção e fluxos de permissão, o nosso guia de hooks do Claude Code aborda em detalhe o ciclo de vida dos hooks PreToolUse e PostToolUse, incluindo como escrever callbacks de hooks que bloqueiam, transformam ou registam chamadas de ferramentas antes de estas serem executadas.

MCP: Ligar o Agente a Sistemas Externos

O SDK suporta totalmente o Model Context Protocol (MCP), que permite ligar o seu agente a qualquer sistema externo que exponha um servidor MCP: bases de dados, automação de navegador, Jira, Slack, GitHub, e centenas de servidores criados pela comunidade.

Configuram-se servidores MCP na opção mcpServers — cada entrada especifica um comando a executar e argumentos opcionais. O SDK inicia esses servidores como subprocessos, e o agente pode chamar as suas ferramentas da mesma forma que chama ferramentas incorporadas. É assim que se dá a um agente de revisão de código acesso ao seu sistema de gestão de issues, ou se liga um agente de documentação à base de conhecimento da sua empresa.

O modelo de permissões também se aplica às chamadas de ferramentas MCP — allowedTools pode incluir nomes de ferramentas MCP, e permissionMode rege o que acontece para ferramentas não listadas.

Armadilhas e Problemas Comuns

As sessões são locais ao subprocesso por defeito. As transcrições de sessão residem no disco local do anfitrião, em ~/.claude/projects/. Em implementações em contentores ou escaladas horizontalmente, isto significa que o estado da sessão se perde ao reiniciar ou ao ser reatribuído a outro nó. Utilize um adaptador SessionStore para qualquer sessão que precise de retomar entre contentores.

O modelo de subprocesso tem implicações de memória. Cada sessão em execução é um subprocesso separado. Executar cinquenta sessões concorrentes significa cinquenta processos do Claude Code. A orientação oficial é aproximadamente 1 GiB de RAM por agente como ponto de partida, mas o uso real de memória depende da duração da sessão e da atividade de ferramentas. Dimensione os seus contentores em conformidade e defina maxTurns para limitar a profundidade da sessão.

Grandes distribuições de subagentes atingem limites de taxa. Se o seu orquestrador delegar em vinte subagentes simultaneamente, é provável que atinja os limites de taxa da API da Anthropic. Divida grandes distribuições em lotes e adicione um pequeno atraso entre os envios.

bypassPermissions requer uma sandbox real. Este modo ignora todas as barreiras de permissão. Foi concebido para ambientes totalmente controlados, como contentores de CI onde o controlo total do contexto de execução é seu. Utilizá-lo na máquina de um programador — onde o agente tem acesso a chaves SSH, credenciais na cloud e caminhos de ficheiros arbitrários — é um risco de segurança.

O SDK TypeScript inclui o binário do Claude Code; o Python não o exige em separado. Mas ambos os SDKs fixam uma versão específica da CLI. Ao atualizar o pacote do SDK, atualiza também a CLI subjacente. Reveja o changelog antes de atualizações menores — as alterações de comportamento que quebram compatibilidade são anunciadas ali.

O texto dos prompts e as entradas das ferramentas não são incluídos nas exportações OTEL por defeito. Este é um comportamento de privacidade intencional. Se precisar de rastreio ao nível do prompt para depuração, tem de ativá-lo explicitamente através de variáveis de ambiente documentadas no guia de observabilidade da Anthropic.

Versões mais antigas do SDK podem não suportar modelos mais recentes. A documentação da Anthropic refere que modelos recentes podem exigir uma versão recente do SDK devido a alterações na API do parâmetro de "thinking", pelo que um SDK desatualizado pode falhar com um modelo novo. Verifique sempre o changelog e fixe uma versão conhecida como estável ao adotar novos modelos.

O SDK vs. a CLI: Qual É Que Precisa?

Para a maioria dos programadores, a resposta é ambos — e isso é intencional.

A CLI interativa é a ferramenta certa para o desenvolvimento do dia a dia: explorar uma base de código desconhecida, resolver um bug complexo de forma interativa, ou executar uma refatoração pontual. O SDK é a ferramenta certa para tudo o que precise de correr sem a presença de um humano: CI, tarefas agendadas, funcionalidades de aplicações e pipelines multi-agente.

O SDK e a CLI não são produtos concorrentes. Os fluxos de trabalho que desenvolve interativamente com a CLI traduzem-se diretamente em automação com o SDK — as mesmas ferramentas, os mesmos conceitos de permissão, a mesma memória CLAUDE.md e o mesmo sistema de skills. Um fluxo de revisão que prototipa hoje com claude no seu terminal torna-se amanhã um bot de CI alimentado pelo SDK.

Para equipas que utilizam a versão web do Claude Code (abordada no nosso guia do Claude Code na web), o SDK abre a porta a combinar sessões web com orquestração programática — inicie uma tarefa de longa duração a partir da web e depois interaja com ela de forma programática a partir do seu back-end.

Perguntas Frequentes

O que é exatamente o Claude Code SDK (Agent SDK)? É uma biblioteca Python (claude-agent-sdk) e TypeScript (@anthropic-ai/claude-agent-sdk) que expõe o motor agêntico completo do Claude Code — ferramentas, permissões, gestão de sessões, subagentes, MCP — como uma API assíncrona programável. Chama-se query(), passa-se um prompt e opções, e recebe-se em stream o trabalho do agente como objetos de mensagem tipados.

Preciso de ter o Claude Code instalado para usar o SDK? Para o SDK TypeScript, não — o pacote inclui um binário nativo do Claude Code. Para o SDK Python, o pacote claude-agent-sdk trata da dependência. É necessária uma chave de API da Anthropic obtida na Anthropic Console.

Posso usar o SDK com modelos diferentes do Claude na API da Anthropic? Sim. O SDK suporta o Amazon Bedrock, o Google Vertex AI, o Microsoft Azure AI Foundry, e o Claude Platform na AWS através de variáveis de ambiente. Também pode encaminhar pedidos através de um proxy personalizado definindo ANTHROPIC_BASE_URL.

Como uso o SDK num workflow do GitHub Actions? Adicione a sua ANTHROPIC_API_KEY como um segredo do GitHub Actions, faça checkout do branch do PR no seu workflow, instale o pacote do SDK e execute o seu script de agente. Utilize permissionMode: "dontAsk" com uma lista allowedTools apenas de leitura para que o agente não possa modificar ficheiros no seu ambiente de CI. A documentação da Anthropic também aborda uma integração dedicada com o GitHub Actions que automatiza a revisão de PRs e a triagem de issues sem escrever código SDK personalizado.

Qual é a diferença entre o Agent SDK e os Managed Agents? O Agent SDK é uma biblioteca que executa o ciclo do agente dentro do seu próprio processo e infraestrutura. Os Managed Agents são uma API REST alojada em que a Anthropic executa o agente e a sandbox — envia eventos e recebe os resultados em stream de volta. O SDK é melhor para prototipagem local e para agentes que trabalham diretamente no seu sistema de ficheiros; os Managed Agents são melhores para produção quando não se pretende gerir infraestrutura de contentores.

Como limito o que o agente pode aceder? Utilize allowedTools para restringir quais ferramentas estão disponíveis, permissionMode: "dontAsk" para recusar tudo o que estiver fora dessa lista, e cwd para delimitar o acesso ao sistema de ficheiros a um diretório específico. Para implementações multi-tenant, defina adicionalmente settingSources: [] e CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.

O SDK suporta saída em stream? Sim — o iterador assíncrono de query() transmite mensagens em tempo real. Se não precisar de saída em tempo real (para tarefas em segundo plano ou pipelines de CI onde só importa o resultado final), a documentação da Anthropic descreve um modo de turno único que recolhe todas as mensagens antes de devolver o resultado. Veja Streaming vs. single-turn mode na documentação oficial.

Posso executar vários agentes em paralelo? Sim. Cada chamada a query() inicia um subprocesso independente. Pode executar N sessões concorrentes — mas cada uma é um processo separado, pelo que deve provisionar memória em conformidade e ter atenção aos limites de taxa da API. Para distribuições concorrentes de subagentes a partir de um único orquestrador, divida os seus envios em lotes para evitar atingir os limites de taxa.

O que acontece se a sessão falhar a meio de uma tarefa? Por defeito, as transcrições de sessão são locais ao contentor e perdem-se ao reiniciar. Para sobreviver a reinícios, configure um adaptador SessionStore (S3, Redis ou Postgres) e passe-o nas opções. Pode então retomar a sessão pelo session_id num contentor novo.

Executar Agentes Sem uma Configuração Local

A proposta de valor do SDK é a automação — mas colocar essa automação a funcionar requer infraestrutura real: um runtime Python ou Node, uma chave de API, uma estratégia de contentores, uma decisão de sandboxing e tempo dedicado à modelação de permissões antes da primeira implementação em produção.

Para programadores que querem iterar sobre ideias de agentes sem essa sobrecarga de configuração, a Happycapy executa agentes ao estilo do Claude Code diretamente no navegador. Não há instalação local, nem gestão de subprocessos, nem provisionamento de contentores. Traz um prompt, a Happycapy trata do ambiente de execução — com acesso a mais de 150 modelos e uma sandbox segura na cloud. É um caminho rápido para prototipar o comportamento do agente que mais tarde irá produtizar com o SDK.

Comece gratuitamente em happycapy.ai

Guias relacionados

• Claude Code Hooks: The Power-User Guide to Automating Your Agent
• How Claude Code Review Actually Works: Diffs, Hooks, and What the Agent Catches
• Claude Code Web: How to Run Claude Code in Your Browser (No Install)
• What Is Harness Engineering? Building Reliable AI Agent Harnesses (2026)