Hosting the Agent SDK

​

Model subprocess

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

​

State yang berada di disk lokal

​

Pilih pola sesi

​

Sesi Ephemeral

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);
}

​

Sesi berjalan lama

​

Sesi Hybrid

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 },
})) {
  // ...
}

​

Kontainer multi-agen

​

Menyediakan kontainer

​

Sandboxing berbasis kontainer

• Siapa yang menjalankan sandbox: penyedia sandbox-as-a-service mengoperasikan infrastruktur untuk Anda, sementara opsi self-hosted memberikan perangkat lunak untuk dijalankan di server Anda sendiri.
• Latensi cold-start: berapa lama dari “buat sandbox” hingga “siap menerima permintaan pertama.” Pola ephemeral memerlukan start sub-detik. Pola long-running dapat mentoleransi lebih banyak.
• Penyimpanan persisten: apakah penyedia menawarkan volume tahan lama atau hanya disk ephemeral. Pola hybrid memerlukan penyimpanan tahan lama di suatu tempat, baik di dalam sandbox atau di sampingnya.
• Model penetapan harga: per-detik, per-permintaan, atau penagihan per jam tetap. Penetapan harga per-detik cocok untuk beban kerja ephemeral yang bersifat bursty. Per jam cocok untuk sesi long-running.
• Jaringan: dukungan untuk aturan egress khusus, proxy outbound, dan peering VPC pribadi untuk lingkungan yang diatur.

• Modal Sandbox, dengan demo implementation
• Cloudflare Sandboxes
• Daytona
• E2B
• Fly Machines
• Vercel Sandbox

​

Dependensi runtime

• Python 3.10+ untuk Python SDK, atau Node.js 18+ untuk TypeScript SDK
• Kedua paket SDK menggabungkan binary Claude Code asli untuk platform host, jadi tidak perlu instalasi Claude Code atau Node.js terpisah untuk CLI yang dihasilkan

​

Sumber daya

​

Jaringan

​

Menangani kekhawatiran produksi

​

Persistensi sesi dan status

• Transkrip saja: SessionStore mencerminkan transkrip, bukan file memori CLAUDE.md atau artefak direktori kerja lainnya. Pasang volume bersama atau sinkronkan yang lain secara terpisah.
• Cermin, bukan penggantian: subprocess menulis ke disk lokal terlebih dahulu, dan penyimpanan menerima salinan setiap batch. Penulisan lokal tetap berwenang.
• Pesan mirror_error: jika penyimpanan menolak atau habis waktu, SDK memancarkan pesan { type: "system", subtype: "mirror_error" } dan melanjutkan kueri tanpa percobaan ulang. Beri peringatan pada ini jika daya tahan penyimpanan penting.

​

Observabilitas

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

​

Otentikasi dan rahasia

• API Anthropic: subprocess membaca ANTHROPIC_API_KEY dari lingkungannya. Suplai dari manajer rahasia Anda, atau atur ANTHROPIC_BASE_URL untuk merutekan panggilan model melalui proxy yang menyuntikkan kunci di luar kontainer. Lihat Manajemen kredensial untuk pola proxy dan Ikhtisar SDK untuk metode otentikasi yang didukung.
• Inbound: letakkan otentikasi di gateway di depan kontainer agen. Agen harus menerima permintaan yang telah diautentikasi sebelumnya dan tidak boleh menjadi komponen yang memvalidasi token pengguna.
• Alat outbound: jaga kredensial alat keluar dari lingkungan agen. Rutekan panggilan outbound melalui proxy yang menyuntikkan kunci API setelah permintaan meninggalkan kontainer. Agen membuat panggilan; proxy menambahkan kredensial.

​

Penskalaan dan konkurensi

agents per host = (host RAM - overhead) / (per-session RAM ceiling)

​

Biaya

​

Isolasi multi-tenant

• Lewatkan settingSources: [] dalam TypeScript atau setting_sources=[] dalam Python sehingga tidak ada pengaturan sistem file yang dimuat.
• Atur CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 dalam env. Memori otomatis di ~/.claude/projects/<project>/memory/ dimuat ke prompt sistem terlepas dari settingSources. Lihat Apa yang settingSources tidak kontrol untuk input lain yang dimuat tanpa syarat.
• Arahkan CLAUDE_CONFIG_DIR ke direktori per-tenant sehingga tenant tidak berbagi konfigurasi global ~/.claude.json.
• Gunakan direktori kerja per-tenant. Lewatkan cwd secara eksplisit pada setiap panggilan query().
• Terapkan aturan egress per-tenant di proxy Anda, seperti IP outbound yang berbeda, kredensial, atau daftar allowlist domain, sehingga tenant yang dikompromikan tidak dapat mengeksfiltrasikan data melalui kebijakan outbound tenant lain.

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",
    },
  },
})) {
  // ...
}

​

Keterbatasan yang Diketahui

​

Langkah Berikutnya

• Hosting cookbook: panduan notebook dengan kode yang dapat digunakan untuk Docker, Modal, dan Kubernetes.
• Session storage: pertahankan transkrip di seluruh host dengan adaptor SessionStore.
• Observability: ekspor jejak OTEL, metrik, dan log ke kolektor Anda.
• Secure deployment: kontrol jaringan, manajemen kredensial, dan pengerasan isolasi.
• Cost tracking: akuntansi token dan biaya per-sesi.