📘 תיעוד 191

אירוח ה-Agent SDK

פריסת ה-Agent SDK בייצור: ארכיטקטורת subprocess, התמדה של סשנים, קנה מידה, observability, ובידוד multi-tenant עבור Docker, Kubernetes וספקי sandbox.

ה-Agent SDK מפעיל ומפקח על תהליך משנה של ה-CLI בשם claude, שבבעלותו shell, תיקיית עבודה וקבצי סשן על הדיסק. אירוח שלו אינו דומה לאירוח של מעטפת API חסרת מצב. כל סוכן שרץ הוא תהליך ארוך טווח הקשור למצב מקומי, וזה מעצב את אופן הקצאת המשאבים, שמירת הסשנים והגדלת הקנה מידה בין דיירים.

הדף הזה עוסק באירוח עצמי על התשתית שלכם. לקובצי Docker ולמניפסטים של Kubernetes שניתן לפרוס, ראו את ספר המתכונים לאירוח.

אם אין צורך להריץ את לולאת הסוכן עצמה על התשתית שלכם, שקלו את Managed Agents במקום זאת. Anthropic מארחת את לולאת הסוכן, והאפליקציה שלכם שולחת אירועים ומקבלת תוצאות בזרימה דרך ערכות ה-SDK של הלקוח או דרך ה-REST API. הרצת הכלים מתבצעת ב-sandbox בענן שמנוהל על ידי Anthropic, או ב-sandbox באירוח עצמי על התשתית שלכם.

#מודל ה-subprocess

כל החלטת אירוח בדף הזה נובעת מהאופן שבו ה-SDK מריץ את הסוכן. כשהקוד שלכם קורא ל-query(), ה-SDK מפעיל תהליך CLI נפרד בשם claude ומדבר איתו דרך stdio. תהליך המשנה הזה הוא הבעלים של ה-shell, של תיקיית העבודה ושל תמלילי הסשן בפורמט JSONL על הדיסק המקומי.

סשן סוכן אחד ממופה לתהליך משנה אחד. הרצה של N סשנים במקביל פירושה N תהליכי משנה, לכל אחד עץ תהליכים וקובץ תמליל משלו. כברירת מחדל כולם יורשים את תיקיית העבודה של האפליקציה. כשסשנים צריכים מערכות קבצים נפרדות, העבירו cwd נפרד באפשרויות של קריאת query() של כל סשן:

TypeScript

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

for await (const message of query({
  prompt: "Summarize the files in this directory",
  options: { cwd: "/work/session-a" },
})) {
  console.log(message);
}

Python

import asyncio

from claude_agent_sdk import ClaudeAgentOptions, query


async def main():
    async for message in query(
        prompt="Summarize the files in this directory",
        options=ClaudeAgentOptions(cwd="/work/session-a"),
    ):
        print(message)


asyncio.run(main())

דוגמאות TypeScript בדף זה משתמשות ב-await ברמה העליונה, ולכן שמרו אותן כקבצי .mts או הגדירו "type": "module" ב-package.json.

#מצב שחי על הדיסק המקומי

שלושה סוגים של מצב סוכן חיים כברירת מחדל על מערכת הקבצים של הקונטיינר. אף אחד מהם לא שורד הפעלה מחדש של קונטיינר, הקטנת קנה מידה, או מעבר לצומת אחר.

כדי לשמור תמלילים בין מארחים, הגדירו מתאם SessionStore. קבצי זיכרון ותוצרים אחרים בתיקיית העבודה צריכים אסטרטגיית אחסון משלהם, למשל volume מורכב או סנכרון מול object store.

לאופן שבו סשנים, חידוש ו-forking עובדים ברמת ה-API, ראו סשנים.

#בחירת תבנית סשן

ארבע התבניות האלה מכסות את מחזור החיים של הסשן: כמה זמן קונטיינר חי ביחס לסשנים שהוא משרת. לגבי המקום שבו הקונטיינר רץ, ל-ספר המתכונים לאירוח יש קוד לפריסה עבור Docker מקומי, Modal ו-Kubernetes. בחרו כאן תבנית סשן, ויעד פריסה מתוך ספר המתכונים.

#סשנים חולפים

צרו קונטיינר לכל משימת משתמש והשמידו אותו כשהמשימה מסתיימת. מתאים ביותר למשימות חד פעמיות. המשתמש עדיין יכול לתקשר עם ה-AI בזמן שהמשימה מושלמת, אבל לאחר ההשלמה הקונטיינר מושמד.

עומסי עבודה לדוגמה כוללים חקירת באג ותיקון, חילוץ חשבוניות וקבלות, תרגום מסמכים, והמרת מדיה.

הקונטיינר מריץ entrypoint חד פעמי שקורא את המשימה ממשתנה הסביבה TASK_PROMPT, קורא ל-SDK ויוצא.

TypeScript

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

Python

import asyncio
import os

from claude_agent_sdk import ClaudeAgentOptions, query


async def main():
    async for message in query(
        prompt=os.environ["TASK_PROMPT"],
        options=ClaudeAgentOptions(max_turns=20),
    ):
        print(message)


asyncio.run(main())

הסקריפט מדפיס כל הודעה עם הגעתה, כולל הודעת תוצאה שה-subtype שלה הוא success כשהמשימה מסתיימת בתוך מגבלת התורות. אם המשימה מגיעה למגבלת 20 התורות, ה-subtype של הודעת התוצאה הוא error_max_turns וקריאת query() זורקת שגיאה אחרי שהיא מניבה את ההודעה, ולכן עטפו את הלולאה בבלוק try אם הקונטיינר צריך לצאת בצורה נקייה. ראו טיפול בתוצאה עבור תת סוגי השגיאה.

#סשנים ארוכי טווח

הריצו מופעי קונטיינר מתמידים, לעתים קרובות עם כמה תהליכי SDK בכל קונטיינר, כדי לשרת עבודה מתמשכת. מתאים ביותר לסוכנים שפועלים באופן אוטונומי, מגישים תוכן, או מטפלים בזרמי הודעות בנפח גבוה.

עומסי עבודה לדוגמה כוללים סוכן דוא"ל שממיין ועונה לדואר נכנס, בונה אתרים שמארח אתר ניתן לעריכה לכל משתמש דרך פורטים של הקונטיינר, ובוט צ'אט שמטפל בתעבורה רציפה מפלטפורמה כמו Slack.

הקונטיינר חושף נקודת קצה HTTP או WebSocket וממפה כל סשן פעיל לשאילתה ארוכת טווח ולתהליך המשנה שמאחוריה. הקריאות שמשאירות סשנים פתוחים וחמים נבדלות בין ערכות ה-SDK:

• TypeScript: השתמשו ב-streamInput() כדי להוסיף תורות לסשן פעיל. קראו ל-startup() כדי לחמם מראש תהליכי משנה לקראת תעבורה נכנסת. אם תיקיית העבודה של סשן אינה ידועה עד שהבקשה הראשונה מגיעה, חממו מראש עם prewarm() במקום זאת.
• Python: השתמשו ב-ClaudeSDKClient כדי להחזיק סשן פתוח לאורך תורות.

קבעו את גודל הקונטיינר כך שיוכל להחזיק בזיכרון את המספר המרבי של סשנים במקביל.

#סשנים היברידיים

קונטיינרים חולפים שנטענים מ-SessionStore בעת ההפעלה ושומרים עדכונים בחזרה. מתאים ביותר לסשנים שנפרסים על פני אינטראקציות רבות אבל נחים ביניהן. הקונטיינר יורד בתקופות חוסר פעילות ועולה בחזרה כשהמשתמש חוזר.

עומסי עבודה לדוגמה כוללים מנהל פרויקטים אישי עם בדיקות לסירוגין, מחקר עומק שנעצר ומתחדש לאורך שעות, וסוכן תמיכת לקוחות שטוען היסטוריית פניות לאורך אינטראקציות.

כווננו את זמן חוסר הפעילות של הספק לפי התדירות שבה אתם מצפים שמשתמשים יחזרו. כיבוי קונטיינר בלי SessionStore מוגדר מאבד איתו את התמליל, ולכן המאגר נדרש לתבנית הזו, ולא אופציונלי.

התבנית נשענת על חידוש סשן לפי מזהה עם מאגר משותף מצורף:

TypeScript

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; // an object store, key-value store, database, or your own adapter

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

Python

from claude_agent_sdk import query, ClaudeAgentOptions, SessionStore
import asyncio

user_input: str = ...
session_id: str = ...              # looked up from your database by user
session_store: SessionStore = ...  # an object store, key-value store, database, or your own adapter


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


asyncio.run(main())

#קונטיינר מרובה סוכנים

הריצו כמה תהליכי משנה של ה-SDK בתוך קונטיינר אחד. מתאים ביותר לסוכנים שחייבים לשתף פעולה באופן הדוק, למשל סימולציות מרובות סוכנים שבהן הסוכנים מקיימים אינטראקציה זה עם זה בסביבה משותפת.

תנו לכל סוכן תיקיית עבודה משלו כדי שלא ידרסו זה את הקבצים של זה, ובודדו את טעינת ההגדרות כדי שקבצי CLAUDE.md של כל סוכן לא ידלפו בין סוכנים. ראו בידוד מרובה דיירים עבור האפשרויות הספציפיות.

#הקצאת הקונטיינר

#sandbox מבוסס קונטיינר

הריצו את ה-SDK בתוך קונטיינר מבודד לצורך בידוד תהליכים, מגבלות משאבים, בקרת רשת ומערכת קבצים חולפת.

שאלות שיש לענות עליהן בבחירת ספק:

• מי מריץ את ה-sandbox: ספק sandbox כשירות מפעיל את התשתית עבורכם, ואפשרויות באירוח עצמי נותנות לכם תוכנה להרצה על התשתית שלכם.
• השהיית cold start: כמה זמן מ"יצירת sandbox" עד "מוכן לקבל את הבקשה הראשונה". תבניות חולפות צריכות הפעלה של פחות משנייה. תבניות ארוכות טווח סובלות יותר.
• אחסון מתמיד: האם הספק מציע volumes עמידים או רק דיסק חולף. התבנית ההיברידית צריכה אחסון עמיד במקום כלשהו, בתוך ה-sandbox או לצידו.
• מודל תמחור: חיוב לפי שנייה, לפי בקשה, או שעתי קבוע. תמחור לפי שנייה מתאים לעומסים חולפים בפרצים. תמחור שעתי מתאים לסשנים ארוכי טווח.
• רשת: תמיכה בכללי egress מותאמים, בפרוקסי יוצא, וב-peering של VPC פרטי לסביבות מפוקחות.

לאפשרויות באירוח עצמי כמו Docker, gVisor ו-Firecracker, ולהגדרת בידוד מפורטת, ראו טכנולוגיות בידוד.

#תלויות זמן ריצה

הקונטיינר צריך את סביבת הריצה של שפת ה-SDK:

• Python 3.10+ עבור ה-SDK של Python, או Node.js 18.14+ עבור ה-SDK של TypeScript
• גם ה-SDK של TypeScript וגם ה-SDK של Python כוללים בינארי Claude Code מקורי לרוב ההתקנות, וה-CLI שמופעל אינו צריך התקנת Node.js נפרדת. ראו את הערת ההתקנה במדריך המהיר עבור ההתקנות שצריכות התקנה נפרדת של Claude Code מקורי.

הבינארי המצורף נעול לגרסת חבילת ה-SDK, ולכן עדכון ה-SDK הוא הדרך לעדכן את ה-CLI. ה-SDK עוקב אחרי semver: קחו גרסאות patch באופן רציף, ועברו על יומן השינויים של TypeScript או Python לפני לקיחת גרסת minor.

#משאבים

1 GiB RAM, 5 GiB דיסק, ו-1 CPU לכל סוכן הם נקודת פתיחה סבירה למופע שהופעל זה עתה. השימוש בזיכרון גדל עם אורך הסשן ועם פעילות הכלים, ולכן קבעו גודל לפי אורכי הסשן והמקביליות שאתם באמת צריכים, ולא לפי קו הבסיס בחוסר פעילות. ראו קנה מידה ומקביליות לאופן החישוב של מספר הסוכנים לכל מארח.

#רשת

ה-SDK צריך HTTPS יוצא אל api.anthropic.com, או אל נקודת הקצה האזורית של הספק כשרצים על Amazon Bedrock או על Agent Platform של Google Cloud. אם הסוכנים משתמשים ב-שרתי MCP או בכלים חיצוניים, הם צריכים גם גישה יוצאת אל נקודות הקצה האלה. לייצור, נתבו תעבורה יוצאת דרך פרוקסי egress שאוכף רשימות היתר של דומיינים, מזריק אישורים ורושם בקשות ביומן. ראו פריסה מאובטחת לתבנית המלאה.

לתעבורה נכנסת, חשפו פורט HTTP או WebSocket על הקונטיינר. האפליקציה שלכם מטפלת בבקשות לקוח בפורט הזה וקוראת ל-SDK מבפנים. תהליך המשנה עצמו אינו מאזין ברשת.

#טיפול בשיקולי ייצור

עברו על ההחלטות האלה לפני שמשחררים סוכן באירוח עצמי.

#התמדה של סשן ומצב

הדיסק המקומי בברירת המחדל אובד בהפעלה מחדש, בהקטנת קנה מידה, או במעבר לצומת אחר. לכל סשן שמשתמש מצפה לחדש, שקפו את התמליל לאחסון עמיד באמצעות מתאם SessionStore. ראו מימושי ייחוס לדוגמאות מתאמים לחנות אובייקטים, לחנות מפתח-ערך ולמסד נתונים, ולערכת התאמה משלכם.

שלושה דברים שכדאי לדעת על ההתנהגות של SessionStore:

• תמלילים בלבד: SessionStore משקף תמלילים, לא קבצי זיכרון CLAUDE.md ולא ארטיפקטים אחרים של ספריית העבודה. חברו אמצעי אחסון משותף או סנכרנו אותם בנפרד.
• שיקוף, לא החלפה: תהליך המשנה כותב קודם לדיסק המקומי, וה-SDK מעביר עותק של כל אצווה לחנות. התמליל המקומי של סשן חדש ממשיך להתקיים אחרי הריצה. ריצה שחודשה מהחנות מוחקת את העותק המקומי בסוף, כך שהחנות מחזיקה את העותק העמיד היחיד. ראו ארכיטקטורת כתיבה כפולה.
• הודעות mirror_error: כשה-SDK לא יכול למסור אצווה לחנות, הוא משליך את האצווה, פולט הודעה { type: "system", subtype: "mirror_error" }, וממשיך את השאילתה. התריעו על אלה אם עמידות החנות חשובה. ראו כתיבות שיקוף הן best-effort להתנהגות הניסיון החוזר ופסק הזמן.

#תצפיתיות

סוכני Agent SDK הם תהליכים ארוכי חיים שמפעילים קריאות כלים לאורך סבבי API רבים. בלי טלמטריה אי אפשר לראות אילו כלים רצו, כמה זמן הם לקחו, או איפה סשן נתקע.

ה-SDK יורש את תצורת OpenTelemetry מהסביבה. הגדירו את משתני הסביבה של OTEL ברמת המכולה או המתזמר כדי שכל קריאה ל-query() תייצא spans, מדדים ואירועי יומן לאספן שלכם. הדוגמה למטה מפעילה ייצוא OTLP לכל שלושת האותות. CLAUDE_CODE_ENHANCED_TELEMETRY_BETA נדרש רק ל-traces. השמיטו אותו אם אתם מייצאים מדדים ויומנים בלבד.

.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

טקסט הפרומפט וקלט הכלים לא נכללים בייצוא כברירת מחדל. ראו שליטה בנתונים רגישים בייצוא לדגלי ההצטרפות, ו-תצפיתיות לקטלוג האותות המלא.

#אימות וסודות

שלושה שיקולי אימות חשובים בזמן האירוח:

• Anthropic API: תהליך המשנה קורא את ANTHROPIC_API_KEY מהסביבה שלו. ספקו אותו ממנהל הסודות שלכם, או הגדירו ANTHROPIC_BASE_URL כדי לנתב קריאות מודל דרך פרוקסי שמזריק את המפתח מחוץ למכולה. ראו ניהול אישורים לדפוס הפרוקסי ו-הגדרה במדריך המהיר של ה-SDK לשיטות האימות הנתמכות.
• נכנס: שימו אימות בשער לפני מכולת הסוכן. הסוכן צריך לקבל בקשות שאומתו מראש, ולא צריך להיות הרכיב שמאמת אסימוני משתמש.
• כלים יוצאים: השאירו את אישורי הכלים מחוץ לסביבת הסוכן. נתבו קריאות יוצאות דרך פרוקסי שמזריק מפתחות API אחרי שהבקשה עוזבת את המכולה. הסוכן מבצע את הקריאה. הפרוקסי מוסיף את האישור.

#קנה מידה ומקביליות

כל סשן רץ בתהליך משנה משלו, ולכן המקביליות על מארח מוגבלת לפי כמה תהליכי משנה ה-RAM שלו יכול להחזיק.

מדדו כל מארח לפי הנוסחה הזאת:

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

מדדו את התקרה לכל סשן על ידי הרצת סשן מייצג עד האורך היעד תחת עומס הכלים הצפוי, ורישום שיא RSS. נקודת ההתחלה של 1 GiB ב-משאבים היא רצפה, לא התקרה.

ניתוב בקנה מידה אופקי תלוי בדפוס שלכם. לסשנים ארוכי טווח, שבהם מכולות מחזיקות סשנים רבים, הריצו מאגר מכולות מאחורי מאזן עומסים, וקבעו כל סשן למכולה אחת באמצעות גיבוב עקבי על sessionId. סשן מקובע ממשיך לפגוע באותה מכולה, ולכן באותו תהליך משנה רץ, עד שהוא מפונה או שהמכולה מופעלת מחדש.

#עלות

עלות הטוקנים של Anthropic בדרך כלל גדולה מעלות תשתית המכולות בסדר גודל או יותר. מכולה בהקצאה מינימלית עולה בערך $0.05 לשעה, בעוד שסשן סוכן ארוך יחיד יכול להוציא דולרים בטוקנים. ראו מעקב עלות לחשבונאות טוקנים לכל סשן.

#בידוד מרובה דיירים

התנהגות ברירת המחדל של ה-SDK קוראת הגדרות וקבצי זיכרון CLAUDE.md ממערכת הקבצים. במכולה משותפת שמשרתת כמה דיירים, הקבצים האלה יכולים להדליף הקשר של דייר אחד לסשן של דייר אחר.

כדי לבודד דיירים בתוך מכולה משותפת:

• העבירו settingSources: [] ב-TypeScript או setting_sources=[] ב-Python כדי לדלג על הגדרות משתמש, פרויקט ומקומיות.
• הגדירו CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 ב-env. זיכרון אוטומטי ב-~/.claude/projects/<project>/memory/ נטען לפרומפט המערכת בלי קשר ל-settingSources. ראו מה ש-settingSources לא שולט בו לקלטים האחרים שנטענים ללא תנאי.
• הפנו את CLAUDE_CONFIG_DIR לספרייה לכל דייר כדי שדיירים לא יחלקו את התצורה הגלובלית ~/.claude.json. כשכל ספריית תצורה משרתת ספריית עבודה אחת ואתם לא מעבירים SessionStore, אפשר גם להגדיר CLAUDE_CODE_PROJECT_DIR_NAME ב-env כדי לשמור את נתיבי התמליל תחתיה קצרים. נדרש TypeScript Agent SDK מגרסה v0.3.234 ואילך, או Python Agent SDK מגרסה v0.2.140 ואילך.
• השתמשו בספריית עבודה לכל דייר. העבירו cwd במפורש בכל קריאה ל-query().
• החילו כללי יציאה לכל דייר בפרוקסי שלכם, כגון כתובות IP יוצאות נפרדות, אישורים, או רשימות היתר של דומיינים, כדי שדייר שנפגע לא יוכל להוציא נתונים דרך מדיניות היציאה של דייר אחר.

הדוגמה למטה מחילה יחד את אפשרויות ההגדרות, הזיכרון האוטומטי, ספריית התצורה וספריית העבודה. בנו את tenantDir ואת configDir כך שכל דייר יקבל נתיב שאף דייר אחר לא יכול לקרוא. ב-TypeScript, env מחליף את סביבת תהליך המשנה, לכן פרשו ...process.env כדי לשמור משתנים שירשו כמו PATH ו-ANTHROPIC_API_KEY. ב-Python, env ממוזג מעל הסביבה שירשה.

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
import asyncio

prompt: str = ...
tenant_dir: str = ...
config_dir: str = ...


async def main():
    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",
            },
        ),
    ):
        ...


asyncio.run(main())

#מגבלות ידועות

תכננו סביבן בעיצוב הפריסה.

#פתרון כשלי פריסה

השתמשו בסעיף הזה כשסוכן שעובד על המכונה שלכם נכשל בשירות פרוס. כל פריט למטה מציין כשל ומקשר לרשומה שמכסה אותו:

• ה-CLI לא נמצא בתחילת השירות: ב-Python, מכולה או מנהל שירות מריצים את היישום עם PATH שונה מזה של המעטפת, ולכן התקנה שעובדת מקומית לא גלויה לתהליך. ב-TypeScript, בניית התמונה דילגה על התלויות האופציונליות של ה-SDK, או ש-pathToClaudeCodeExecutable מצביע על קובץ שלא קיים בתמונה. ראו Claude Code לא נמצא.
• ה-CLI קיים בתמונה אבל לא יופעל: Claude Code לא יכול להתחיל מקובץ בינארי שלא תואם לארכיטקטורה או ל-libc של המכולה, או מקובץ שאיבד את הרשאת ההרצה בבניית התמונה. ראו ההפעלה של Claude Code נכשלה.
• תהליך Claude Code יוצא באמצע הריצה: השגיאה שהיישום מקבל תלויה בשפת ה-SDK ובשאלה אם ה-CLI דיווח תחילה על תוצאת שגיאה. הרשומות תחת יציאת תהליך CLI מכסות כל הודעה.

#הצעדים הבאים

• ספר בישול לאירוח: הדרכה במחברת עם קוד לפריסה ל-Docker, ל-Modal ול-Kubernetes.
• אחסון סשן: שמירת תמלילים בין מארחים באמצעות מתאם SessionStore.
• תצפיתיות: ייצוא של traces, מדדים ויומנים של OTEL לאספן שלכם.
• פריסה מאובטחת: בקרות רשת, ניהול אישורים, והקשחת בידוד.
• מעקב עלות: חשבונאות טוקנים ועלות לכל סשן.