O Claude Agent SDK difere das APIs LLM tradicionais sem estado, pois mantém o estado conversacional e executa comandos em um ambiente persistente. Este guia aborda a arquitetura, considerações de hospedagem e melhores práticas para implantar agentes baseados em SDK em produção.

Requisitos de Hospedagem

Sandbox Baseada em Container

Para segurança e isolamento, o SDK deve ser executado dentro de um ambiente de container em sandbox. Isso fornece isolamento de processo, limites de recursos, controle de rede e sistemas de arquivos efêmeros.

O SDK também suporta configuração de sandbox programática para execução de comandos.

Requisitos do Sistema

Cada instância do SDK requer:

• Dependências de tempo de execução

  • Python 3.10+ (para SDK Python) ou Node.js 18+ (para SDK TypeScript)
  • Node.js (obrigatório pelo Claude Code CLI)
  • Claude Code CLI: npm install -g @anthropic-ai/claude-code

• Alocação de recursos

  • Recomendado: 1GiB de RAM, 5GiB de disco e 1 CPU (varie isso com base em sua tarefa conforme necessário)

• Acesso à rede

  • HTTPS de saída para api.anthropic.com
  • Opcional: Acesso a servidores MCP ou ferramentas externas

Entendendo a Arquitetura do SDK

Diferentemente das chamadas de API sem estado, o Claude Agent SDK opera como um processo de longa duração que:

• Executa comandos em um ambiente de shell persistente
• Gerencia operações de arquivo dentro de um diretório de trabalho
• Manipula execução de ferramentas com contexto de interações anteriores

Opções de Provedor de Sandbox

Vários provedores se especializam em ambientes de container seguro para execução de código de IA:

• Modal Sandbox - implementação de demonstração
• Cloudflare Sandboxes
• Daytona
• E2B
• Fly Machines
• Vercel Sandbox

Para opções auto-hospedadas (Docker, gVisor, Firecracker) e configuração detalhada de isolamento, consulte Tecnologias de Isolamento.

Padrões de Implantação em Produção

Padrão 1: Sessões Efêmeras

Crie um novo container para cada tarefa do usuário e destrua-o quando concluído.

Melhor para tarefas únicas, o usuário ainda pode interagir com a IA enquanto a tarefa está sendo concluída, mas uma vez concluída, o container é destruído.

Exemplos:

• Investigação e Correção de Bugs: Depurar e resolver um problema específico com contexto relevante
• Processamento de Faturas: Extrair e estruturar dados de recibos/faturas para sistemas contábeis
• Tarefas de Tradução: Traduzir documentos ou lotes de conteúdo entre idiomas
• Processamento de Imagem/Vídeo: Aplicar transformações, otimizações ou extrair metadados de arquivos de mídia

Padrão 2: Sessões de Longa Duração

Manter instâncias de container persistentes para tarefas de longa duração. Frequentemente executando múltiplos processos Claude Agent dentro do container com base na demanda.

Melhor para agentes proativos que tomam ações sem entrada do usuário, agentes que servem conteúdo ou agentes que processam grandes quantidades de mensagens.

Exemplos:

• Agente de Email: Monitora emails recebidos e triagem autônoma, responde ou toma ações com base no conteúdo
• Construtor de Sites: Hospeda sites personalizados por usuário com capacidades de edição ao vivo servidas através de portas de container
• Chatbots de Alta Frequência: Manipula fluxos contínuos de mensagens de plataformas como Slack onde tempos de resposta rápidos são críticos

Padrão 3: Sessões Híbridas

Containers efêmeros que são hidratados com histórico e estado, possivelmente de um banco de dados ou dos recursos de retomada de sessão do SDK.

Melhor para containers com interação intermitente do usuário que inicia trabalho e desliga quando o trabalho é concluído, mas pode ser continuado.

Exemplos:

• Gerenciador de Projetos Pessoais: Ajuda a gerenciar projetos contínuos com check-ins intermitentes, mantém contexto de tarefas, decisões e progresso
• Pesquisa Profunda: Conduz tarefas de pesquisa de múltiplas horas, salva descobertas e retoma investigação quando o usuário retorna
• Agente de Suporte ao Cliente: Manipula tickets de suporte que abrangem múltiplas interações, carrega histórico de tickets e contexto do cliente

Padrão 4: Containers Únicos

Execute múltiplos processos Claude Agent SDK em um container global.

Melhor para agentes que devem colaborar estreitamente. Este é provavelmente o padrão menos popular porque você terá que evitar que agentes sobrescrevam um ao outro.

Exemplos:

• Simulações: Agentes que interagem uns com os outros em simulações como videogames.

FAQ

Como me comunico com minhas sandboxes?

Ao hospedar em containers, exponha portas para se comunicar com suas instâncias do SDK. Sua aplicação pode expor endpoints HTTP/WebSocket para clientes externos enquanto o SDK é executado internamente dentro do container.

Qual é o custo de hospedar um container?

Descobrimos que o custo dominante de servir agentes é os tokens, containers variam com base no que você provisiona, mas um custo mínimo é aproximadamente 5 centavos por hora em execução.

Quando devo desligar containers ociosos versus mantê-los aquecidos?

Isso provavelmente depende do provedor, diferentes provedores de sandbox permitirão que você defina diferentes critérios para tempos limite de ociosidade após os quais uma sandbox pode desligar. Você desejará ajustar este tempo limite com base em com que frequência você acha que a resposta do usuário pode ocorrer.

Com que frequência devo atualizar o Claude Code CLI?

O Claude Code CLI é versionado com semver, portanto quaisquer mudanças significativas serão versionadas.

Como monitoro a saúde do container e o desempenho do agente?

Como containers são apenas servidores, a mesma infraestrutura de logging que você usa para o backend funcionará para containers.

Por quanto tempo uma sessão de agente pode ser executada antes de atingir o tempo limite?

Uma sessão de agente não atingirá o tempo limite, mas recomendamos definir uma propriedade 'maxTurns' para evitar que Claude fique preso em um loop.

Próximas Etapas

• Implantação Segura - Controles de rede, gerenciamento de credenciais e endurecimento de isolamento
• SDK TypeScript - Configurações de Sandbox - Configure sandbox programaticamente
• Guia de Sessões - Saiba mais sobre gerenciamento de sessão
• Permissões - Configure permissões de ferramentas
• Rastreamento de Custos - Monitore o uso da API
• Integração MCP - Estenda com ferramentas personalizadas