Hosting Agent SDK

Deploy Agent SDK ใน production: สถาปัตยกรรม subprocess, session persistence, scaling, observability, และ multi-tenant isolation สำหรับ Docker, Kubernetes, และ sandbox providers

Agent SDK spawn และ supervise subprocess claude CLI ที่เป็นเจ้าของ shell, working directory, และ session files บน disk การ host มันไม่เหมือนกับการ host stateless API wrapper ทุก running agent คือ process ที่ดำเนินอยู่นานผูกกับ local state ซึ่งกำหนดวิธีที่คุณจัดสรร resources, persist sessions, และ scale ข้ามหลาย tenants

หน้านี้ครอบคลุมการ self-hosting บน infrastructure ของตัวเอง สำหรับ Dockerfiles ที่ deploy ได้และ Kubernetes manifests ดู hosting cookbook

info

สำหรับการ hardening ด้านความปลอดภัยนอกเหนือจาก sandboxing พื้นฐาน รวมถึง network controls, credential management, และ isolation options ดู Secure Deployment

The Subprocess Model

ทุกการตัดสินใจด้านการ host ในหน้านี้มาจากวิธีที่ SDK รัน agent เมื่อ code ของคุณเรียก query() SDK จะ spawn process claude CLI แยกต่างหากและสื่อสารผ่าน stdio subprocess นั้นเป็นเจ้าของ shell, working directory, และ JSONL session transcripts บน local disk

session agent หนึ่งอันจะ map ไปยัง subprocess หนึ่งอัน การรัน N concurrent sessions หมายถึง N subprocesses แต่ละอันมี process tree และ transcript file ของตัวเอง ค่า default พวกมันทั้งหมด inherit working directory ของแอปพลิเคชันของคุณ ดังนั้นส่ง cwd บนแต่ละ query() call เมื่อ sessions ต้องการ filesystems แยกกัน:

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

query(prompt=prompt, options=ClaudeAgentOptions(cwd="/work/session-a"))

State ที่อยู่บน local disk

State	ตำแหน่ง default
Session transcripts	`~/.claude/projects/` หรือ directory `projects/` ภายใต้ `CLAUDE_CONFIG_DIR` หากตั้งค่าไว้
`CLAUDE.md` memory files	`~/.claude/CLAUDE.md` สำหรับ user tier และ working directory ของ session สำหรับ project tier
Working-directory artifacts	Working directory ของ session

เพื่อ persist transcripts ข้ามหลาย hosts ให้ configure adapter SessionStore สำหรับ memory files และ working-directory artifacts อื่นๆ ต้องการ storage strategy ของตัวเอง

เลือก Session Pattern

Ephemeral sessions

สร้าง container สำหรับแต่ละ user task และทำลายมันเมื่อ task เสร็จสมบูรณ์ ดีที่สุดสำหรับ one-off tasks

ตัวอย่าง workloads: bug investigation และ fix, invoice และ receipt extraction, document translation

Long-running sessions

รัน persistent container instances เพื่อให้บริการงานที่ต่อเนื่อง ดีที่สุดสำหรับ agents ที่ดำเนินการอัตโนมัติ

ตัวอย่าง workloads: email agent ที่จัดการและตอบอีเมล, site builder, chat bot

ใน TypeScript ใช้ streamInput() เพื่อเพิ่ม turns ไปยัง active session และ startup() เพื่อ pre-warm subprocesses ใน Python ใช้ ClaudeSDKClient เพื่อ hold session เปิดข้าม turns

Hybrid sessions

Ephemeral containers ที่ hydrate จาก SessionStore เมื่อ startup และ persist updates กลับ ดีที่สุดสำหรับ sessions ที่ span หลาย interactions แต่ว่างระหว่างพวกมัน

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

declare const userInput: string;
declare const sessionId: string;
declare const sessionStore: SessionStore;

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

from claude_agent_sdk import query, ClaudeAgentOptions

async for message in query(
    prompt=user_input,
    options=ClaudeAgentOptions(
        resume=session_id,
        session_store=session_store,
    ),
):
    ...

Multi-agent container

รัน multiple SDK subprocesses ภายใน container เดียว ดีที่สุดสำหรับ agents ที่ต้องทำงานร่วมกันอย่างใกล้ชิด

ให้แต่ละ agent มี working directory ของตัวเองและ isolate settings loading

Provision the Container

Container-based sandboxing

รัน SDK ภายใน sandboxed container สำหรับ process isolation, resource limits, network control, และ ephemeral filesystem

Providers ที่ควรประเมิน:

Runtime dependencies

Container ต้องการเพียง language runtime ของ SDK:

Python 3.10+ สำหรับ Python SDK หรือ Node.js 18+ สำหรับ TypeScript SDK
ทั้งสอง SDK packages มี native Claude Code binary สำหรับ host platform ดังนั้นไม่ต้องการ Claude Code หรือ Node.js แยกต่างหากสำหรับ spawned CLI

Resources

1 GiB RAM, 5 GiB disk, และ 1 CPU ต่อ agent เป็นจุดเริ่มต้นที่สมเหตุสมผล memory usage เติบโตตาม session length และ tool activity

Network

SDK ต้องการ outbound HTTPS ไปยัง api.anthropic.com สำหรับ production ให้ route outbound traffic ผ่าน egress proxy ที่บังคับ domain allowlists, inject credentials, และ log requests

Handle Production Concerns

Session และ State Persistence

Local disk default จะหายไปเมื่อ restart, scale-down, หรือย้ายไปยัง node อื่น สำหรับ sessions ที่ user คาดหวังจะ resume ให้ mirror transcript ไปยัง durable storage ด้วย adapter SessionStore

Observability

SDK inherit OpenTelemetry configuration จาก environment ตั้ง OTEL environment variables ที่ระดับ container หรือ orchestrator:

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

Auth และ Secrets

สาม auth concerns ที่สำคัญในเวลา hosting:

Anthropic API: subprocess อ่าน ANTHROPIC_API_KEY จาก environment
Inbound: วาง authentication ที่ gateway ด้านหน้า agent container
Outbound tools: เก็บ tool credentials ออกจาก agent environment, route outbound calls ผ่าน proxy ที่ inject API keys

Scaling และ Concurrency

แต่ละ session รันใน subprocess ของตัวเอง ดังนั้น concurrency บน host ถูกจำกัดด้วยจำนวน subprocesses ที่ RAM ของมันสามารถรองรับได้

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

Cost

Anthropic token cost มักจะ dominate container infrastructure cost อย่างมาก container ที่ provisioned น้อยที่สุดรันประมาณ $0.05 ต่อชั่วโมง ในขณะที่ agent session ที่ยาวเดี่ยวอาจใช้ไปหลาย dollars ใน tokens ดู Cost tracking สำหรับ per-session token accounting

Multi-tenant Isolation

เพื่อ isolate tenants ภายใน shared container:

ส่ง settingSources: [] ใน TypeScript หรือ setting_sources=[] ใน Python เพื่อไม่ให้ filesystem settings โหลด
ตั้ง CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 ใน env
ชี้ CLAUDE_CONFIG_DIR ไปยัง per-tenant directory
ใช้ per-tenant working directory โดยส่ง cwd อย่างชัดเจนทุก query() call

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

from claude_agent_sdk import query, ClaudeAgentOptions

async for message in query(
    prompt=prompt,
    options=ClaudeAgentOptions(
        cwd=tenant_dir,
        setting_sources=[],
        env={
            "CLAUDE_CONFIG_DIR": config_dir,
            "CLAUDE_CODE_DISABLE_AUTO_MEMORY": "1",
        },
    ),
):
    ...

ข้อจำกัดที่รู้จัก

ข้อจำกัด	สิ่งที่ควรทำ
ไม่มี top-level session timeout	ตั้ง `maxTurns` ใน `Options` เพื่อจำกัดจำนวน tool-use round trips
Memory เติบโตใน long sessions	Cap session length หรือ recycle subprocesses เป็นระยะ
Large parallel-subagent fanouts อาจ hit rate limits	แบ่งงานเป็น batches เล็กกว่าแทนการ dispatch แบบ wide

ขั้นตอนถัดไป

Hosting cookbook: notebook walkthrough พร้อม deployable code สำหรับ Docker, Modal, และ Kubernetes
Session storage: persist transcripts ข้ามหลาย hosts ด้วย adapter SessionStore
Observability: export OTEL traces, metrics, และ logs
Secure deployment: network controls, credential management, และ isolation hardening
Cost tracking: per-session token และ cost accounting

The Subprocess Model​

State ที่อยู่บน local disk​

เลือก Session Pattern​

Ephemeral sessions​

Long-running sessions​

Hybrid sessions​

Multi-agent container​

Provision the Container​

Container-based sandboxing​

Runtime dependencies​

Resources​

Network​

Handle Production Concerns​

Session และ State Persistence​

Observability​

Auth และ Secrets​

Scaling และ Concurrency​

Cost​

Multi-tenant Isolation​

ข้อจำกัดที่รู้จัก​

ขั้นตอนถัดไป​