Agent SDK 호스팅

​

서브프로세스 모델

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

​

로컬 디스크에 존재하는 상태

​

세션 패턴 선택

​

임시 세션

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

​

장기 실행 세션

​

하이브리드 세션

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

​

다중 에이전트 컨테이너

​

컨테이너 제공

​

컨테이너 기반 샌드박싱

• 샌드박스를 실행하는 주체: 샌드박스형 서비스 제공자는 사용자를 위해 인프라를 운영하며, 자체 호스팅 옵션은 자신의 인프라에서 실행할 소프트웨어를 제공합니다.
• 콜드 스타트 지연: “샌드박스 생성”에서 “첫 번째 요청을 수락할 준비”까지의 시간입니다. 임시 패턴은 1초 미만의 시작이 필요합니다. 장기 실행 패턴은 더 많은 시간을 허용합니다.
• 지속적 스토리지: 제공자가 내구성 있는 볼륨을 제공하는지 또는 임시 디스크만 제공하는지 여부입니다. 하이브리드 패턴은 샌드박스 내부 또는 그 옆에 어딘가에 내구성 있는 스토리지가 필요합니다.
• 가격 책정 모델: 초당, 요청당 또는 시간당 정액 청구입니다. 초당 가격 책정은 버스트 임시 워크로드에 적합합니다. 시간당 가격 책정은 장기 실행 세션에 적합합니다.
• 네트워킹: 사용자 정의 송신 규칙, 아웃바운드 프록시 및 규제 환경을 위한 프라이빗 VPC 피어링 지원입니다.

• Modal Sandbox, 데모 구현 포함
• Cloudflare Sandboxes
• Daytona
• E2B
• Fly Machines
• Vercel Sandbox

​

런타임 종속성

• Python SDK의 경우 Python 3.10+ 또는 TypeScript SDK의 경우 Node.js 18+
• 두 SDK 패키지 모두 호스트 플랫폼용 네이티브 Claude Code 바이너리를 번들로 제공하므로 생성된 CLI에 대해 별도의 Claude Code 또는 Node.js 설치가 필요하지 않습니다.

​

리소스

​

네트워크

​

프로덕션 배포 문제 처리

​

세션 및 상태 지속성

• 트랜스크립트만: SessionStore는 트랜스크립트를 미러링하며, CLAUDE.md 메모리 파일이나 다른 작업 디렉토리 아티팩트는 미러링하지 않습니다. 공유 볼륨을 마운트하거나 별도로 동기화하십시오.
• 미러링, 대체 아님: 서브프로세스는 먼저 로컬 디스크에 쓰고, 스토어는 각 배치의 복사본을 받습니다. 로컬 쓰기가 권한이 있습니다.
• mirror_error 메시지: 스토어가 거부하거나 시간 초과되면 SDK는 { type: "system", subtype: "mirror_error" } 메시지를 내보내고 재시도 없이 쿼리를 계속합니다. 스토어 지속성이 중요한 경우 이에 대해 경고하십시오.

​

관찰성

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

​

인증 및 비밀

• Anthropic API: 서브프로세스는 환경에서 ANTHROPIC_API_KEY를 읽습니다. 비밀 관리자에서 제공하거나 ANTHROPIC_BASE_URL을 설정하여 모델 호출을 컨테이너 외부에서 키를 주입하는 프록시를 통해 라우팅하십시오. 프록시 패턴에 대해서는 자격 증명 관리를 참조하고, 지원되는 인증 방법에 대해서는 SDK 개요를 참조하십시오.
• 인바운드: 에이전트 컨테이너 앞의 게이트웨이에 인증을 배치하십시오. 에이전트는 사전 인증된 요청을 받아야 하며 사용자 토큰을 검증하는 구성 요소가 아니어야 합니다.
• 아웃바운드 도구: 에이전트 환경에서 도구 자격 증명을 유지하십시오. 아웃바운드 호출을 요청이 컨테이너를 떠난 후 API 키를 주입하는 프록시를 통해 라우팅하십시오. 에이전트가 호출을 수행합니다. 프록시가 자격 증명을 추가합니다.

​

확장 및 동시성

호스트당 에이전트 = (호스트 RAM - 오버헤드) / (세션당 RAM 상한)

​

비용

​

다중 테넌트 격리

• TypeScript에서 settingSources: []를 전달하거나 Python에서 setting_sources=[]를 전달하여 파일 시스템 설정이 로드되지 않도록 하십시오.
• env에서 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1을 설정하십시오. ~/.claude/projects/<project>/memory/의 자동 메모리는 settingSources에 관계없이 시스템 프롬프트에 로드됩니다. settingSources가 제어하지 않는 다른 입력에 대해서는 settingSources가 제어하지 않는 것을 참조하십시오.
• CLAUDE_CONFIG_DIR을 테넌트별 디렉토리로 지정하여 테넌트가 ~/.claude.json 글로벌 구성을 공유하지 않도록 하십시오.
• 테넌트별 작업 디렉토리를 사용하십시오. 모든 query() 호출에서 cwd를 명시적으로 전달하십시오.
• 프록시에서 테넌트별 송신 규칙을 적용하십시오(예: 서로 다른 아웃바운드 IP, 자격 증명 또는 도메인 허용 목록). 이렇게 하면 손상된 테넌트가 다른 테넌트의 아웃바운드 정책을 통해 데이터를 유출할 수 없습니다.

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

​

알려진 제한사항

​

다음 단계

• 호스팅 쿡북: Docker, Modal, Kubernetes용 배포 가능한 코드가 포함된 노트북 안내입니다.
• 세션 저장소: SessionStore 어댑터를 사용하여 호스트 간에 트랜스크립트를 유지합니다.
• 관찰성: OTEL 추적, 메트릭 및 로그를 수집기로 내보냅니다.
• 보안 배포: 네트워크 제어, 자격증명 관리 및 격리 강화입니다.
• 비용 추적: 세션별 토큰 및 비용 회계입니다.