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

Sandboxing Baseado em Container

Para segurança e isolamento, o SDK deve ser executado dentro de um ambiente de container sandboxed. Isso fornece:

• Isolamento de processo - Ambiente de execução separado por sessão
• Limites de recursos - Restrições de CPU, memória e armazenamento
• Controle de rede - Restringir conexões de saída
• Sistemas de arquivos efêmeros - Estado limpo para cada sessão

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 de rede

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

Compreendendo a Arquitetura do SDK

Ao contrário 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:

• Cloudflare Sandboxes
• Modal Sandboxes
• Daytona
• E2B
• Fly Machines
• Vercel Sandbox

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 o destrua quando concluída.

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ção 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 Site: Hospeda sites personalizados por usuário com recursos de edição ao vivo servidos 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 Projeto Pessoal: 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 várias 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 entre si em simulações como videogames.

Perguntas Frequentes

Como me comunico com meus 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 são os tokens, containers variam com base no que você provisiona, mas um custo mínimo é aproximadamente 5 centavos por hora de 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 um sandbox pode desligar. Você desejará ajustar este tempo limite com base na frequência com que acha que a resposta do usuário pode ser.

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

O Claude Code CLI é versionado com semver, portanto qualquer mudança significativa será versionada.

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

• 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