​
Hospedagem do Agent SDK

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.

​
Compreendendo a Arquitetura do SDK

​
Modelo de Processo de Longa Duração

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 shell persistente
  • Gerencia operações de arquivo dentro de um diretório de trabalho
  • Lida com execução de ferramentas com contexto de interações anteriores

​
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 runtime
    • Python 3.10+ (para Python SDK) ou Node.js 18+ (para TypeScript SDK)
    • Node.js (requerido pelo Claude Code CLI)
    • Claude Code CLI: npm install -g @anthropic-ai/claude-code
  • Alocação de recursos
    • Recomendado: 1GiB RAM, 5GiB de disco e 1 CPU (varie isso baseado na sua tarefa conforme necessário)
  • Acesso à rede
    • HTTPS de saída para api.anthropic.com
    • Opcional: Acesso a servidores MCP ou ferramentas externas

​
Opções de Provedores de Sandbox

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

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

​
Padrão 1: Sessões Efêmeras

Criar um novo container para cada tarefa do usuário, depois destruí-lo quando completo. Melhor para tarefas pontuais, o usuário ainda pode interagir com a AI enquanto a tarefa está sendo completada, mas uma vez completada o container é destruído. Exemplos:
  • Investigação e Correção de Bug: Depurar e resolver um problema específico com contexto relevante
  • Processamento de Fatura: Extrair e estruturar dados de recibos/faturas para sistemas de contabilidade
  • 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 baseado na demanda. Melhor para agentes proativos que tomam ação sem a 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 autonomamente triagem, responde ou toma ações baseadas no conteúdo
  • Construtor de Site: Hospeda sites customizados por usuário com capacidades de edição ao vivo servidas através de portas do container
  • Chat Bots de Alta Frequência: Lida com 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 é completado mas pode ser continuado. Exemplos:
  • Gerente de Projeto Pessoal: Ajuda a gerenciar projetos em andamento 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: Lida com tickets de suporte que abrangem múltiplas interações, carrega histórico de tickets e contexto do cliente

​
Padrão 4: Containers Únicos

Executar múltiplos processos Claude Agent SDK em um container global. Melhor para agentes que devem colaborar estreitamente juntos. Este é provavelmente o padrão menos popular porque você terá que prevenir que agentes sobrescrevam uns aos outros. Exemplos:
  • Simulações: Agentes que interagem uns com os outros em simulações como videogames.

​
FAQ

​
Como me comunico com meus sandboxes?

Ao hospedar em containers, exponha portas para se comunicar com suas instâncias SDK. Sua aplicação pode expor endpoints HTTP/WebSocket para clientes externos enquanto o SDK executa 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 baseado no que você provisiona mas um custo mínimo é aproximadamente 5 centavos por hora executando.

​
Quando devo desligar containers ociosos vs. mantê-los aquecidos?

Isso é provavelmente dependente do provedor, diferentes provedores de sandbox permitirão que você defina diferentes critérios para timeouts de ociosidade após os quais um sandbox pode desligar. Você vai querer ajustar esse timeout baseado na frequência que você pensa 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, então quaisquer mudanças que quebrem compatibilidade serão versionadas.

​
Como monitoro a saúde do container e performance 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 executar antes de dar timeout?

Uma sessão de agente não dará timeout, mas recomendamos definir uma propriedade ‘maxTurns’ para prevenir que Claude fique preso em um loop.

​
Próximos Passos