Hospedagem do Agent SDK

​

O modelo de subprocess

query({ prompt, options: { cwd: "/work/session-a" } })

​

Estado que vive no disco local

​

Escolha um padrão de sessão

​

Sessões efêmeras

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

const prompt = process.env.TASK_PROMPT!;
for await (const message of query({ prompt, options: { maxTurns: 20 } })) {
  console.log(message);
}

​

Sessões de longa duração

​

Sessões híbridas

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

declare const userInput: string;
declare const sessionId: string;          // looked up from your database by user
declare const sessionStore: SessionStore; // S3, Redis, Postgres, or your own adapter

for await (const message of query({
  prompt: userInput,
  options: { resume: sessionId, sessionStore },
})) {
  // ...
}

​

Container multi-agente

​

Provisionar o container

​

Sandboxing baseado em container

• Quem executa o sandbox: um provedor de sandbox-as-a-service opera a infraestrutura para você, enquanto as opções auto-hospedadas fornecem software para você executar em sua própria infraestrutura.
• Latência de cold-start: quanto tempo desde “criar um sandbox” até “pronto para aceitar a primeira solicitação”. Padrões efêmeros precisam de inicializações em menos de um segundo. Padrões de longa duração toleram mais.
• Armazenamento persistente: se o provedor oferece volumes duráveis ou apenas disco efêmero. O padrão híbrido precisa de armazenamento durável em algum lugar, seja no sandbox ou ao lado dele.
• Modelo de preços: faturamento por segundo, por solicitação ou por hora fixa. Preços por segundo adequam-se a cargas de trabalho efêmeras intermitentes. Preços por hora adequam-se a sessões de longa duração.
• Rede: suporte para regras de egresso personalizadas, proxies de saída e peering de VPC privada para ambientes regulados.

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

​

Dependências de runtime

• Python 3.10+ para o Python SDK, ou Node.js 18+ para o TypeScript SDK
• Ambos os pacotes SDK incluem um binário Claude Code nativo para a plataforma do host, portanto nenhuma instalação separada de Claude Code ou Node.js é necessária para o CLI gerado

​

Recursos

​

Rede

​

Lidar com preocupações de produção

​

Persistência de sessão e estado

• Apenas transcrições: SessionStore espelha transcrições, não arquivos de memória CLAUDE.md ou outros artefatos do diretório de trabalho. Monte um volume compartilhado ou sincronize-os separadamente.
• Espelho, não substituição: o subprocess escreve no disco local primeiro, e o armazenamento recebe uma cópia de cada lote. As escritas locais permanecem autoritárias.
• Mensagens mirror_error: se o armazenamento rejeitar ou expirar, o SDK emite uma mensagem { type: "system", subtype: "mirror_error" } e continua a consulta sem tentar novamente. Alerte sobre essas se a durabilidade do armazenamento for importante.

​

Observabilidade

CLAUDE_CODE_ENABLE_TELEMETRY=1
CLAUDE_CODE_ENHANCED_TELEMETRY_BETA=1
OTEL_TRACES_EXPORTER=otlp
OTEL_METRICS_EXPORTER=otlp
OTEL_LOGS_EXPORTER=otlp
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
OTEL_EXPORTER_OTLP_ENDPOINT=http://collector.example.com:4318

​

Autenticação e segredos

• API Anthropic: o subprocess lê ANTHROPIC_API_KEY de seu ambiente. Forneça-o do seu gerenciador de segredos ou defina ANTHROPIC_BASE_URL para rotear chamadas de modelo através de um proxy que injeta a chave fora do container. Veja Gerenciamento de credenciais para o padrão de proxy e Visão geral do SDK para métodos de autenticação suportados.
• Entrada: coloque a autenticação em um gateway na frente do container do agente. O agente deve receber solicitações pré-autenticadas e não deve ser o componente que valida tokens de usuário.
• Ferramentas de saída: mantenha as credenciais de ferramentas fora do ambiente do agente. Rotear chamadas de saída através de um proxy que injeta chaves de API depois que a solicitação sai do container. O agente faz a chamada; o proxy adiciona a credencial.

​

Dimensionamento e concorrência

agentes por host = (RAM do host - overhead) / (limite de RAM por sessão)

​

Custo

​

Isolamento multi-tenant

• Passe settingSources: [] em TypeScript ou setting_sources=[] em Python para que nenhuma configuração do sistema de arquivos seja carregada.
• Defina CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 em env. Auto memory em ~/.claude/projects/<project>/memory/ é carregada no prompt do sistema independentemente de settingSources. Veja O que settingSources não controla para as outras entradas que são carregadas incondicionalmente.
• Aponte CLAUDE_CONFIG_DIR para um diretório por tenant para que os tenants não compartilhem a configuração global ~/.claude.json.
• Use um diretório de trabalho por tenant. Passe cwd explicitamente em cada chamada query().
• Aplique regras de saída por tenant em seu proxy, como IPs de saída distintos, credenciais ou listas de permissão de domínio, para que um tenant comprometido não possa exfiltrar dados através da política de saída de outro tenant.

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

declare const prompt: string;
declare const tenantDir: string;
declare const configDir: string;

for await (const message of query({
  prompt,
  options: {
    cwd: tenantDir,
    settingSources: [],
    env: {
      ...process.env,
      CLAUDE_CONFIG_DIR: configDir,
      CLAUDE_CODE_DISABLE_AUTO_MEMORY: "1",
    },
  },
})) {
  // ...
}

​

Limitações conhecidas

​

Próximas etapas

• Guia de hospedagem: passo a passo do notebook com código implantável para Docker, Modal e Kubernetes.
• Armazenamento de sessão: persistir transcrições entre hosts com um adaptador SessionStore.
• Observabilidade: exportar rastreamentos OTEL, métricas e logs para seu coletor.
• Implantação segura: controles de rede, gerenciamento de credenciais e endurecimento de isolamento.
• Rastreamento de custos: contabilidade de tokens e custos por sessão.