میزبانیِ Agent SDK

این یک ترجمهٔ غیررسمی از مستندات Claude Code است که توسط مسیر تهیه شده. نسخهٔ مرجع و معتبر، مستندات رسمی انگلیسی است.

Agent SDK یک زیرفرایندِ claude CLI را اجرا و سرپرستی می‌کند که خودش صاحبِ یک شل، یک دایرکتوریِ کاری و فایل‌های نشست روی دیسک است. میزبانیِ آن مثلِ میزبانیِ یک wrapperِ بی‌حالتِ API نیست. هر ایجنتِ در حالِ اجرا یک فرایندِ بلندعمر است که به حالتِ محلی گره خورده، و همین تعیین می‌کند چطور منابع را تخصیص بدهی، نشست‌ها را پایدار کنی و در میانِ تننت‌ها مقیاس بدهی.

این صفحه self-hosting روی زیرساختِ خودت را پوشش می‌دهد: درکِ مدلِ زیرفرایند، انتخابِ یک الگوی نشست، آماده‌سازیِ کانتینر، و مدیریتِ دغدغه‌های production مثلِ پایداری، observability، احراز هویت و جداسازیِ چندتننتی. برای Dockerfileها و manifestهای Kubernetesِ آماده‌ی استقرار، به hosting cookbook نگاه کن.

اگر به کنترلِ زیرساخت، جداسازیِ سفارشی یا data planeِ خودت نیاز نداری، به‌جای آن Managed Agents را در نظر بگیر: یک REST APIِ میزبانی‌شده که Anthropic خودش ایجنت و sandbox را اجرا می‌کند، پس برنامه‌ی تو رویدادها را می‌فرستد و نتیجه را به‌صورتِ stream می‌گیرد، بدون هیچ زیرساختِ میزبانی‌ای برای اداره‌کردن.

یادداشت

برای سخت‌سازیِ امنیتی فراتر از sandboxingِ پایه، شاملِ کنترل‌های شبکه، مدیریتِ اعتبارنامه‌ها و گزینه‌های جداسازی، به Secure Deployment نگاه کن.

مدلِ زیرفرایند

هر تصمیمِ میزبانی در این صفحه از این برمی‌خیزد که SDK چطور ایجنت را اجرا می‌کند. وقتی کدِ تو query() را صدا می‌زند، SDK یک فرایندِ مجزای claude CLI را اجرا می‌کند و با آن از طریقِ stdio حرف می‌زند. آن زیرفرایند صاحبِ شل، دایرکتوریِ کاری و رونوشت‌های نشستِ JSONL روی دیسکِ محلی است.

هر نشستِ ایجنت به یک زیرفرایند نگاشت می‌شود. اجرای N نشستِ هم‌زمان یعنی N زیرفرایند، هرکدام با درختِ فرایند و فایلِ رونوشتِ خودش. به‌صورتِ پیش‌فرض همه‌شان دایرکتوریِ کاریِ برنامه‌ی تو را به ارث می‌برند، پس وقتی نشست‌ها به فایل‌سیستمِ جدا نیاز دارند، در هر فراخوانیِ query() گزینه‌ی cwd را پاس بده:

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

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

حالتی که روی دیسکِ محلی می‌نشیند

سه نوع حالتِ ایجنت به‌صورتِ پیش‌فرض روی فایل‌سیستمِ کانتینر می‌نشینند. هیچ‌کدام از ری‌استارتِ کانتینر، scale-down، یا انتقال به نودِ دیگر جان به در نمی‌برند.

حالت	مکانِ پیش‌فرض
رونوشت‌های نشست	~/.claude/projects/، یا دایرکتوریِ projects/ زیرِ CLAUDE_CONFIG_DIR اگر تنظیم شده باشد
فایل‌های حافظه‌ی CLAUDE.md	~/.claude/CLAUDE.md برای لایه‌ی کاربر و دایرکتوریِ کاریِ نشست برای لایه‌ی پروژه
آرتیفکت‌های دایرکتوریِ کاری	دایرکتوریِ کاریِ نشست

برای پایدارکردنِ رونوشت‌ها در میانِ هاست‌ها، یک آداپتورِ SessionStore پیکربندی کن. فایل‌های حافظه و دیگر آرتیفکت‌های دایرکتوریِ کاری به استراتژیِ ذخیره‌سازیِ خودشان نیاز دارند، مثلِ یک volumeِ mount‌شده یا یک sync با object-store.

برای اینکه ببینی نشست‌ها، resumption و forking در سطحِ API چطور کار می‌کنند، به Sessions نگاه کن.

یک الگوی نشست انتخاب کن

این چهار الگو چرخه‌ی حیاتِ نشست را پوشش می‌دهند: اینکه یک کانتینر نسبت به نشست‌هایی که سرویس می‌دهد چقدر عمر می‌کند. برای اینکه کانتینر کجا اجرا شود، hosting cookbook کدِ آماده‌ی استقرار برای Dockerِ محلی، Modal و Kubernetes دارد. یک الگوی نشست را از اینجا و یک مقصدِ استقرار را از cookbook انتخاب کن.

نشست‌های زودگذر (Ephemeral)

برای هر کارِ کاربر یک کانتینر بساز و وقتی کار تمام شد آن را نابود کن. بهترین گزینه برای کارهای یک‌باره. کاربر ممکن است در حینِ تکمیلِ کار هنوز با AI تعامل کند، اما به‌محضِ اتمام، کانتینر نابود می‌شود.

نمونه‌بارها شاملِ بررسی و رفعِ باگ، استخراجِ فاکتور و رسید، ترجمه‌ی سند و تبدیلِ مدیا است.

کانتینر یک entrypointِ یک‌باره را اجرا می‌کند که SDK را صدا می‌زند و خارج می‌شود. مثالِ زیر یک نسخه‌ی کمینه‌ی TypeScript را نشان می‌دهد. آن را به‌صورتِ entrypoint.mts ذخیره کن یا در package.json مقدارِ "type": "module" بگذار تا awaitِ سطح‌بالا در دسترس باشد.

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

نشست‌های بلندعمر (Long-running)

نمونه‌های کانتینرِ پایدار را اجرا کن، که اغلب چند فرایندِ SDK را در هر کانتینر میزبانی می‌کنند، تا به کارِ مستمر سرویس بدهی. بهترین گزینه برای ایجنت‌هایی که خودمختار اقدام می‌کنند، محتوا سرو می‌کنند، یا جریان‌های پرحجمِ پیام را مدیریت می‌کنند.

نمونه‌بارها شاملِ یک ایجنتِ ایمیل که نامه‌های ورودی را triage و پاسخ می‌دهد، یک site builder که از طریقِ پورت‌های کانتینر یک سایتِ قابلِ‌ویرایشِ هر-کاربر میزبانی می‌کند، و یک چت‌باتی که ترافیکِ پیوسته‌ی پلتفرمی مثلِ Slack را مدیریت می‌کند.

کانتینر یک endpointِ HTTP یا WebSocket را افشا می‌کند و هر نشستِ فعال را به یک query بلندعمر و زیرفرایندِ پشتِ آن نگاشت می‌کند. در TypeScript، از streamInput() برای افزودنِ نوبت‌ها به یک نشستِ فعال و از startup() برای گرم‌کردنِ پیشاپیشِ زیرفرایندها در برابرِ ترافیکِ ورودی استفاده کن. در Python، از ClaudeSDKClient برای نگه‌داشتنِ یک نشستِ باز در میانِ نوبت‌ها استفاده کن. کانتینر را طوری اندازه بگیر که بتواند بیشینه‌ی تعدادِ نشست‌های هم‌زمان را در حافظه نگه دارد.

نشست‌های ترکیبی (Hybrid)

کانتینرهای زودگذری که در آغاز از یک SessionStore hydrate می‌شوند و به‌روزرسانی‌ها را به آن برمی‌گردانند. بهترین گزینه برای نشست‌هایی که در طولِ تعاملاتِ بسیار کشیده می‌شوند اما بینِ آن‌ها بی‌کار می‌مانند. کانتینر در دوره‌های بی‌کاری خاموش می‌شود و وقتی کاربر برگشت دوباره روشن می‌شود.

نمونه‌بارها شاملِ یک مدیرِ پروژه‌ی شخصی با check-inهای منقطع، تحقیقِ عمیق که در طولِ ساعت‌ها مکث و resume می‌کند، و یک ایجنتِ پشتیبانیِ مشتری که تاریخچه‌ی تیکت را در میانِ تعاملات بارگذاری می‌کند.

idle timeoutِ ارائه‌دهنده‌ات را با میزانِ تکراری که انتظار داری کاربران برگردند تنظیم کن. خاموش‌کردنِ یک کانتینر بدونِ پیکربندیِ SessionStore، رونوشت را همراهِ آن از دست می‌دهد، پس این store برای این الگو الزامی است، نه اختیاری.

این الگو بر resumeکردنِ یک نشست با شناسه و یک storeِ مشترکِ متصل می‌چرخد:

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

from claude_agent_sdk import query, ClaudeAgentOptions

async for message in query(
    prompt=user_input,
    options=ClaudeAgentOptions(
        resume=session_id,            # looked up from your database by user
        session_store=session_store,  # S3, Redis, Postgres, or your own adapter
    ),
):
    ...

برای interfaceِ کاملِ SessionStore و آداپتورهای مرجع، به Session storage نگاه کن.

کانتینرِ چندایجنتی (Multi-agent)

چند زیرفرایندِ SDK را درونِ یک کانتینر اجرا کن. بهترین گزینه برای ایجنت‌هایی که باید از نزدیک با هم همکاری کنند، مثلاً شبیه‌سازی‌های چندایجنتی که ایجنت‌ها در یک محیطِ مشترک با هم تعامل می‌کنند.

به هر ایجنت دایرکتوریِ کاریِ خودش را بده تا فایل‌های یکدیگر را بازنویسی نکنند، و بارگذاریِ تنظیمات را جدا کن تا فایل‌های CLAUDE.mdِ هر-ایجنت بینِ ایجنت‌ها نشت نکنند. برای گزینه‌های مشخص به جداسازیِ چندتننتی نگاه کن.

کانتینر را آماده کن

sandboxing مبتنی بر کانتینر

SDK را درونِ یک کانتینرِ sandbox‌شده اجرا کن تا جداسازیِ فرایند، محدودیتِ منابع، کنترلِ شبکه و یک فایل‌سیستمِ زودگذر داشته باشی. چند ارائه‌دهنده در محیط‌های کانتینریِ sandbox‌شده تخصص دارند که با مدلِ Agent SDK جور درمی‌آیند.

پرسش‌هایی که هنگامِ انتخابِ ارائه‌دهنده باید پاسخ بدهی:

• چه کسی sandbox را اجرا می‌کند: یک ارائه‌دهنده‌ی sandbox-as-a-service زیرساخت را برایت اداره می‌کند، در حالی که گزینه‌های self-hosted نرم‌افزاری به تو می‌دهند که خودت روی سیستمِ خودت اجرا کنی.
• تأخیرِ Cold-start: از «بساز یک sandbox» تا «آماده برای پذیرشِ اولین درخواست» چقدر طول می‌کشد. الگوهای زودگذر به شروع‌های زیرِ ثانیه نیاز دارند. الگوهای بلندعمر بیشتر تحمل می‌کنند.
• ذخیره‌سازیِ پایدار: اینکه ارائه‌دهنده volumeهای بادوام عرضه می‌کند یا فقط دیسکِ زودگذر. الگوی ترکیبی جایی به ذخیره‌سازیِ بادوام نیاز دارد، چه درونِ sandbox چه کنارِ آن.
• مدلِ هزینه: هزینه‌ی per-second، per-request، یا ساعتیِ ثابت. هزینه‌ی per-second مناسبِ بارهای زودگذرِ پرنوسان است. ساعتی مناسبِ نشست‌های بلندعمر است.
• شبکه: پشتیبانی از قوانینِ سفارشیِ egress، پراکسی‌های خروجی و peeringِ خصوصیِ VPC برای محیط‌های مقررات‌محور.

ارائه‌دهندگانی برای ارزیابی:

• Modal Sandbox، با یک پیاده‌سازیِ نمونه
• Cloudflare Sandboxes
• Daytona
• E2B
• Fly Machines
• Vercel Sandbox

برای گزینه‌های self-hosted مثلِ Docker، gVisor و Firecracker، و پیکربندیِ تفصیلیِ جداسازی، به Isolation Technologies نگاه کن.

وابستگی‌های Runtime

کانتینر فقط به runtimeِ زبانِ SDKِ تو نیاز دارد:

• Python 3.10+ برای Python SDK، یا Node.js 18+ برای TypeScript SDK
• هر دو پکیجِ SDK یک باینریِ بومیِ Claude Code را برای پلتفرمِ هاست بسته‌بندی می‌کنند، پس برای CLIِ اجراشده به نصبِ جداگانه‌ی Claude Code یا Node.js نیازی نیست

باینریِ بسته‌بندی‌شده به نسخه‌ی پکیجِ SDK pin شده است، پس راهِ به‌روزرسانیِ CLI همان به‌روزرسانیِ SDK است. SDK از semver پیروی می‌کند: انتشارهای patch را به‌طورِ پیوسته بگیر و پیش از گرفتنِ یک minor، changelogِ TypeScript یا Python را مرور کن.

منابع

۱ GiB RAM، ۵ GiB دیسک و ۱ CPU برای هر ایجنت نقطه‌ی شروعِ معقولی برای یک نمونه‌ی تازه‌اجراشده است. مصرفِ حافظه با طولِ نشست و فعالیتِ ابزار رشد می‌کند، پس به‌جای خط‌پایه‌ی بی‌کار، برای طولِ نشست‌ها و هم‌زمانی‌ای که واقعاً نیاز داری اندازه بگیر. برای اینکه ببینی چند ایجنت در هر هاست جا می‌شود، به مقیاس‌دهی و هم‌زمانی نگاه کن.

شبکه

SDK به HTTPSِ خروجی به api.anthropic.com نیاز دارد، یا به endpointِ منطقه‌ای ارائه‌دهنده‌ات هنگامِ اجرا روی Bedrock یا Vertex. اگر ایجنت‌هایت از سرورهای MCP یا ابزارهای بیرونی استفاده می‌کنند، به دسترسیِ خروجی به آن endpointها هم نیاز دارند. برای production، ترافیکِ خروجی را از یک egress proxy عبور بده که allowlistِ دامنه را اعمال می‌کند، اعتبارنامه‌ها را تزریق می‌کند و درخواست‌ها را لاگ می‌کند. برای الگوی کامل به Secure Deployment نگاه کن.

برای ترافیکِ ورودی، یک پورتِ HTTP یا WebSocket روی کانتینر افشا کن. برنامه‌ی تو درخواست‌های کلاینت را روی آن پورت مدیریت می‌کند و SDK را درون‌برنامه‌ای صدا می‌زند؛ خودِ زیرفرایند روی شبکه گوش نمی‌دهد.

دغدغه‌های production را مدیریت کن

پیش از shipکردنِ یک ایجنتِ self-hosted، این تصمیم‌ها را پشتِ سر بگذار.

پایداریِ نشست و حالت

دیسکِ محلیِ پیش‌فرض با ری‌استارت، scale-down یا انتقال به نودِ دیگر از دست می‌رود. برای هر نشستی که کاربر انتظار دارد resume کند، رونوشت را با یک آداپتورِ SessionStore به ذخیره‌سازیِ بادوام آینه کن. برای آداپتورهای S3، Redis و Postgres و یک conformance suite برای آداپتورِ خودت، به پیاده‌سازی‌های مرجع نگاه کن.

سه چیز درباره‌ی رفتارِ SessionStore باید بدانی:

• فقط رونوشت‌ها: SessionStore رونوشت‌ها را آینه می‌کند، نه فایل‌های حافظه‌ی CLAUDE.md یا دیگر آرتیفکت‌های دایرکتوریِ کاری را. یک volumeِ مشترک mount کن یا آن‌ها را جداگانه sync کن.
• آینه، نه جایگزین: زیرفرایند اول روی دیسکِ محلی می‌نویسد، و store یک رونوشت از هر batch را دریافت می‌کند. نوشته‌های محلی مرجع باقی می‌مانند.
• پیام‌های mirror_error: اگر store رد کند یا timeout بدهد، SDK یک پیامِ { type: "system", subtype: "mirror_error" } منتشر می‌کند و query را بدونِ retry ادامه می‌دهد. اگر بادوامیِ store اهمیت دارد، روی این‌ها alert بگذار.

Observability

ایجنت‌های Agent SDK فرایندهای بلندعمری هستند که فراخوانیِ ابزار را در طولِ بسیاری round-tripِ API ایجاد می‌کنند. بدونِ telemetry نمی‌توانی ببینی کدام ابزارها اجرا شدند، چقدر طول کشیدند، یا کجا یک نشست گیر کرد.

SDK پیکربندیِ OpenTelemetry را از محیط به ارث می‌برد. متغیرهای محیطیِ OTEL را در سطحِ کانتینر یا orchestrator تنظیم کن تا هر فراخوانیِ query()، spanها، metricها و رویدادهای log را به collectorِ تو صادر کند. مثالِ زیر صادراتِ OTLP را برای هر سه سیگنال فعال می‌کند. CLAUDE_CODE_ENHANCED_TELEMETRY_BETA فقط برای traceها لازم است؛ اگر تنها metricها و logها را صادر می‌کنی آن را حذف کن.

.env

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

متنِ پرامپت و ورودی‌های ابزار به‌صورتِ پیش‌فرض در صادرات گنجانده نمی‌شوند. برای پرچم‌های opt-in به Control sensitive data in exports و برای کاتالوگِ کاملِ سیگنال به Observability نگاه کن.

احراز هویت و رازها

سه دغدغه‌ی احراز هویت در زمانِ میزبانی اهمیت دارند:

• API انتروپیک: زیرفرایند ANTHROPIC_API_KEY را از محیطِ خودش می‌خواند. آن را از secret managerِ خودت تأمین کن، یا ANTHROPIC_BASE_URL را تنظیم کن تا فراخوانی‌های مدل را از یک پراکسی عبور بدهی که کلید را بیرونِ کانتینر تزریق می‌کند. برای الگوی پراکسی به Credential management و برای روش‌های احراز هویتِ پشتیبانی‌شده به مرورِ کلیِ SDK نگاه کن.
• ورودی: احراز هویت را روی یک gateway جلوی کانتینرِ ایجنت بگذار. ایجنت باید درخواست‌های ازپیش‌احرازشده دریافت کند و نباید مؤلفه‌ای باشد که توکن‌های کاربر را اعتبارسنجی می‌کند.
• ابزارهای خروجی: اعتبارنامه‌های ابزار را بیرونِ محیطِ ایجنت نگه دار. فراخوانی‌های خروجی را از یک پراکسی عبور بده که کلیدهای API را بعد از خروجِ درخواست از کانتینر تزریق می‌کند. ایجنت فراخوانی را انجام می‌دهد؛ پراکسی اعتبارنامه را اضافه می‌کند.

مقیاس‌دهی و هم‌زمانی

هر نشست در زیرفرایندِ خودش اجرا می‌شود، پس هم‌زمانی روی یک هاست با این محدود می‌شود که RAMِ آن چند زیرفرایند را می‌تواند نگه دارد.

هر هاست را با این فرمول اندازه بگیر:

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

سقفِ per-session را با اجرای یک نشستِ نماینده تا طولِ هدفت زیرِ بارِ موردِانتظارِ ابزار اندازه‌گیری کن و peak RSS را ثبت کن. نقطه‌ی شروعِ ۱ GiB در منابع یک کف است، نه سقف.

مسیریابیِ مقیاس‌دهیِ افقی به الگوی تو بستگی دارد. برای نشست‌های بلندعمر، که کانتینرها نشست‌های بسیاری نگه می‌دارند، یک استخر از کانتینرها را پشتِ یک load balancer اجرا کن و هر نشست را با hashingِ سازگار روی sessionId به یک کانتینر pin کن. یک نشستِ pin‌شده تا زمانی که evict شود یا کانتینر ری‌استارت شود، همان کانتینر و در نتیجه همان زیرفرایندِ در حالِ اجرا را می‌زند.

fanoutهای بزرگِ ساب‌ایجنت‌های هم‌زمان از یک نشستِ واحد می‌توانند به rate limitهای API بخورند. کار را به batchهای کوچک‌تر بشکن، به‌جای صدورِ یک dispatchِ پهن.

هزینه

هزینه‌ی توکنِ Anthropic معمولاً به اندازه‌ی یک مرتبه‌ی بزرگی یا بیشتر بر هزینه‌ی زیرساختِ کانتینر غلبه دارد. یک کانتینرِ با حداقل تخصیصِ منابع تقریباً $0.05 در ساعت اجرا می‌شود، در حالی که یک نشستِ ایجنتِ بلند به‌تنهایی می‌تواند دلارها توکن خرج کند. برای حساب‌داریِ توکنِ per-session به Cost tracking نگاه کن.

جداسازیِ چندتننتی

رفتارِ پیش‌فرضِ SDK تنظیمات و فایل‌های حافظه‌ی CLAUDE.md را از فایل‌سیستم می‌خواند. در یک کانتینرِ مشترک که به چند تننت سرویس می‌دهد، آن فایل‌ها می‌توانند کانتکستِ یک تننت را به نشستِ تننتِ دیگر نشت بدهند.

برای جداسازیِ تننت‌ها درونِ یک کانتینرِ مشترک:

• در TypeScript مقدارِ settingSources: [] یا در Python مقدارِ setting_sources=[] را پاس بده تا هیچ تنظیماتِ فایل‌سیستمی بارگذاری نشود.
• مقدارِ CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 را در env تنظیم کن. Auto memory در ~/.claude/projects/<project>/memory/ صرفِ‌نظر از settingSources در system prompt بارگذاری می‌شود. برای دیگر ورودی‌هایی که بی‌قیدوشرط بارگذاری می‌شوند، به What settingSources does not control نگاه کن.
• مقدارِ CLAUDE_CONFIG_DIR را به یک دایرکتوریِ هر-تننت اشاره بده تا تننت‌ها configِ سراسریِ ~/.claude.json را به اشتراک نگذارند.
• از یک دایرکتوریِ کاریِ هر-تننت استفاده کن. در هر فراخوانیِ query() مقدارِ cwd را صریحاً پاس بده.
• قوانینِ egressِ هر-تننت را روی پراکسیِ خودت اعمال کن، مثلِ IPهای خروجی، اعتبارنامه‌ها یا allowlistهای دامنه‌ی متمایز، تا یک تننتِ compromise‌شده نتواند داده را از طریقِ سیاستِ خروجیِ تننتِ دیگر استخراج کند.

مثالِ زیر چهار گزینه‌ی سطح‌SDK را با هم اعمال می‌کند. tenantDir و configDir را طوری بساز که هر تننت مسیری بگیرد که هیچ تننتِ دیگری نتواند بخواند. در TypeScript، env محیطِ زیرفرایند را جایگزین می‌کند، پس ...process.env را spread کن تا متغیرهای ارث‌برده‌ای مثلِ PATH و ANTHROPIC_API_KEY حفظ شوند. در Python، env روی محیطِ ارث‌برده merge می‌شود.

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

برای کنترل‌های شبکه‌ی هر-تننت، به Secure Deployment نگاه کن.

محدودیت‌های شناخته‌شده

این‌ها را در طراحیِ استقرارت در نظر بگیر.

محدودیت	چه باید کرد
نبودِ session timeoutِ سطح‌بالا	یک نشست خودبه‌خود timeout نمی‌شود. در Options مقدارِ maxTurns را تنظیم کن تا تعدادِ round-tripهای tool-use پیش از توقفِ ایجنت محدود شود.
رشدِ حافظه در نشست‌های طولانی	طولِ نشست را محدود کن یا زیرفرایندها را دوره‌ای بازیافت کن. به مقیاس‌دهی و هم‌زمانی نگاه کن.
fanoutهای بزرگِ ساب‌ایجنتِ موازی می‌توانند به rate limit بخورند	کار را به batchهای کوچک‌تر بشکن، به‌جای صدورِ یک dispatchِ پهن.
نبودِ deadlineِ wall-clock برای هر ساب‌ایجنت	هر ساب‌ایجنت را با maxTurns در AgentDefinitionِ خودش محدود کن. فقط برای ساب‌ایجنت‌های background، CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS یک watchdogِ stall تنظیم می‌کند که وقتی یک ساب‌ایجنتِ run_in_background تولیدِ خروجی را متوقف کند فعال می‌شود؛ این یک deadlineِ زمانِ-کلِ‌اجرا نیست.

گام‌های بعدی

• Hosting cookbook: راهنمای گام‌به‌گامِ notebook با کدِ آماده‌ی استقرار برای Docker، Modal و Kubernetes.
• Session storage: پایدارکردنِ رونوشت‌ها در میانِ هاست‌ها با یک آداپتورِ SessionStore.
• Observability: صادراتِ traceها، metricها و logهای OTEL به collectorِ تو.
• Secure deployment: کنترل‌های شبکه، مدیریتِ اعتبارنامه‌ها و سخت‌سازیِ جداسازی.
• Cost tracking: حساب‌داریِ توکن و هزینه‌ی per-session.