📘 תיעוד 127

הגדרת הסוכן שלך

הגדרת הפעלות של Agent SDK: הרכבת אובייקט ה-options, קביעת המודל, הסביבה והמגבלות, ומציאת הדף של כל אפשרות תכונה.

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

לעיון בסוג ובערך ברירת המחדל של כל אפשרות, ראה את הפניות התיעוד של Options (TypeScript) ו-ClaudeAgentOptions (Python).

#העברת אפשרויות להפעלה

כל קריאה ל-query() מקבלת אובייקט אפשרויות: Options ב-TypeScript, ClaudeAgentOptions ב-Python. כל שדה הוא אופציונלי, והפעלה שמתחילה ללא אפשרויות רצה עם ערכי ברירת המחדל של ה-SDK. הדוגמה להלן מגדירה הפעלה לקריאה בלבד שמסכמת משימות TODO פתוחות בפרויקט. הזוגות מוצגים כ-TypeScript / Python במקומות שבהם האיות שונה:

• model: בוחר את המודל
• allowedTools / allowed_tools: מאשר מראש רשימת כלים לקריאה בלבד
• maxTurns / max_turns: מגביל את מספר התורות
• cwd: קובע את ספריית העבודה

TypeScript:

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

for await (const message of query({
  prompt: "Summarize the open TODOs in this repo",
  options: {
    model: "claude-sonnet-5",
    allowedTools: ["Read", "Glob", "Grep"],
    maxTurns: 8,
    cwd: "/path/to/repo",
  },
})) {
  if (message.type === "result" && message.subtype === "success" && !message.is_error) {
    console.log(message.result);
  }
}

Python:

import asyncio

from claude_agent_sdk import ClaudeAgentOptions, ResultMessage, query

async def main():
    options = ClaudeAgentOptions(
        model="claude-sonnet-5",
        allowed_tools=["Read", "Glob", "Grep"],
        max_turns=8,
        cwd="/path/to/repo",
    )

    async for message in query(
        prompt="Summarize the open TODOs in this repo",
        options=options,
    ):
        if isinstance(message, ResultMessage) and not message.is_error:
            print(message.result)

asyncio.run(main())

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

allowedTools (TypeScript) או allowed_tools (Python) מאשר מראש את הכלים המפורטים, כך שקריאות אליהם רצות מבלי לעצור לבקשת אישור. כלים שמחוץ לרשימה נשארים זמינים. כאשר Claude קורא לכלי שאינו ברשימה, מצב ההרשאות קובע אם הקריאה תרוץ. למידע נוסף, ראה Allow and deny rules.

#טעינת קובצי הגדרות

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

• settingSources / setting_sources: שולט באילו מקורות של מערכת הקבצים נטענים: משתמש, פרויקט ומקומי (user, project, local). קובצי הגדרות וקובצי CLAUDE.md מגיעים דרך מקורות אלה.
• settings: טוען נתיב לקובץ הגדרות או מחרוזת JSON ישירה (inline) בכל אחת מהשפות, וב-TypeScript מקבל גם אובייקט הגדרות. כל צורה שתעביר דורסת את הגדרות מערכת הקבצים של המשתמש, הפרויקט והמקומי; רק הגדרות מדיניות מנוהלת (managed policy) מדורגות גבוה יותר. הפניות התיעוד מפרטות את סדר העדיפות המלא תחת Settings precedence עבור TypeScript ותחת Settings precedence עבור Python.

העבר [] כדי להשבית הגדרות משתמש, פרויקט והגדרות מקומיות. למידע נוסף, ראה Use Claude Code features in the SDK.

#בחירת מודל

אלא אם האפשרות model, ההגדרות שלך או הסביבה שלך בוחרים מודל, הפעלה חדשה מתחילה ב-מודל ברירת המחדל של Claude Code. לגבי סדר המקורות הללו, ראה Setting your model. הגדר את model כדי לקבע מודל ספציפי, או כדי לבחור מודל קטן יותר עבור סוכנים מהירים וזולים יותר. הערך מקבל כינוי מודל (alias) או שם מודל מלא; כינויים והגרסאות שאליהן הם משויכים מפורטים תחת Model aliases.

הגדר את fallbackModel (TypeScript) או fallback_model (Python) כדי לציין מודל גיבוי. כאשר המודל הראשי עמוס או אינו זמין, ההפעלה עוברת למודל הגיבוי. נעשה ניסיון חוזר להשתמש במודל הראשי בתחילת כל תור משתמש, כך שההפעלה חוזרת אליו ברגע שההשבתה חולפת.

בכל אחת מהשפות, האפשרות מקבלת מודל בודד או רשימה מופרדת בפסיקים של גיבויים. לגבי הסדר ומגבלת השרשרת, ראה Fallback model chains. ב-TypeScript, מודל גיבוי הזהה ל-model זורק שגיאה בעת ההפעלה.

הדוגמאות להלן מציגות רשימת גיבוי ב-TypeScript וגיבוי בודד ב-Python:

TypeScript:

const options = {
  model: "claude-fable-5",
  fallbackModel: "claude-opus-5,claude-sonnet-5",
};

Python:

options = ClaudeAgentOptions(
    model="claude-fable-5",
    fallback_model="claude-opus-5",
)

הערה: לפרמטרי הבקשה של Messages API, שהם temperature, top_p ו-max_tokens, אין שדות באובייקט האפשרויות באף אחת מהשפות. הגדר במקום זאת את רמת המאמץ או תקרת הוצאה, או קרא ישירות ל-Messages API כאשר אתה זקוק לפרמטרים אלה.

#הגדרת משתני סביבה

האפשרות env מגדירה משתני סביבה עבור תהליך Claude Code שמריץ את ההפעלה שלך. השאלה האם הערכים שלך מחליפים את הסביבה העוברת בירושה או מתמזגים מעליה שונה בין השפות:

• TypeScript: env מחליף את סביבת תת-התהליך
• Python: ה-SDK ממזג את הערכים שלך מעל הסביבה העוברת בירושה, והערכים שלך דורסים את הערכים המורשים

ב-TypeScript, בצע פריסה של process.env לתוך env כדי לשמור על משתנים מורשים כמו PATH, HOME ו-ANTHROPIC_API_KEY. כאשר אתה משאיר את env ללא הגדרה, תת-התהליך יורש את הסביבה שלך בשתי השפות.

הדוגמה מנתבת את תעבורת ה-API דרך שער (gateway) על ידי הגדרת ANTHROPIC_BASE_URL.

TypeScript:

const options = {
  env: { ...process.env, ANTHROPIC_BASE_URL: "https://gateway.example.com" },
};

Python:

options = ClaudeAgentOptions(
    env={"ANTHROPIC_BASE_URL": "https://gateway.example.com"},
)

המשתנים שאתה מעביר יכולים גם להגדיר את Claude Code עצמו. לגבי המשתנים שתהליך Claude Code קורא, ראה Environment variables. כדי לכוונן פסקי זמן של API וזיהוי השהיות בדרך זו, פעל לפי הסעיף Handle slow or stalled API responses ב-הפניית TypeScript או ב-הפניית Python.

#הגדרת ספריית העבודה

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

Claude Code קורא את ספריית העבודה כדי לקבוע:

• הגדרות פרויקט ו-hooks: אילו הגדרות ו-hooks של הפרויקט נטענים
• מיומנויות (Skills): היכן מתגלות מיומנויות ההפעלה
• אחסון הפעלות: לאיזה פרויקט שייכת הפעלה שמורה

כדי לאפשר לכלים לגשת לקבצים מחוץ לספריית העבודה, הוסף נתיבים באמצעות additionalDirectories (TypeScript) או add_dirs (Python). לגבי היקף הרשאה זו, ראה Additional directories grant file access, not configuration.

#הגבלת תורות והוצאות

הגבל תורות והוצאות באמצעות maxTurns / max_turns ו-maxBudgetUsd / max_budget_usd. שתי המגבלות כבויות כאשר אינן מוגדרות. כאשר הפעלה מגיעה למגבלה, הריצה מסתיימת בהודעת תוצאה שתת-הסוג שלה מציין את שם המגבלה, error_max_turns או error_max_budget_usd. מה שקורה בהמשך שונה לפי מצב הקלט:

• קריאה חד-פעמית של query(): ה-SDK מניב (yields) את תוצאת המגבלה ולאחר מכן מעלה חריגה, לכן עטוף את הלולאה בבלוק try כדי להמשיך מעבר לשגיאה
• קלט מוזרם (Streaming input): ההפעלה נשארת פעילה מעבר לתוצאת מגבלה, וספירת ה-max-turns מתחילה מחדש עבור כל הודעה בתור. סך התקציב מצטבר לאורך ההודעות, וברגע שההוצאה מגיעה למגבלה, הודעות מאוחרות יותר באותה שיחה מסתיימות באותה תוצאת תקציב. פקודת /clear מתחילה את התקציב מחדש

שתי המגבלות מתייחסות ל-0 באופן שונה:

• maxTurns / max_turns: הערך 0 מריץ את ההפעלה ללא הגבלת תורות, בדומה להשארת האפשרות ללא הגדרה
• maxBudgetUsd / max_budget_usd: ה-CLI דוחה את 0 כסכום לא תקין בעת ההפעלה, וההפעלה לעולם לא רצה

למידע נוסף על שתי המגבלות, כולל הוצאות של תת-סוכנים (subagents), ראה Turns and budget.

#שינוי תצורה באמצע הפעלה

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

• TypeScript: מתודות על האובייקט שמוחזר מ-query()
• Python: מתודות על ClaudeSDKClient, מאחר ש-query() מחזיר איטרטור פשוט ללא מתודות בקרה

לשתי השפות יש את אותם ה-setters:

• setModel() / set_model(): מחליף את המודל. קריאה לפונקציה זו ללא מודל תחליף ל-מודל ברירת המחדל של Claude Code ולא ל-model שהעברת באפשרויות.
• setPermissionMode() / set_permission_mode(): מחליף את מצב ההרשאות

ל-TypeScript יש גם את applyFlagSettings() ו-updateSettings():

• applyFlagSettings(): מחיל הגדרות בזמן ריצה, כמו למשל ב-await session.applyFlagSettings({ effortLevel: "high" }). המתודה מקבלת מפתחות של קובצי הגדרות ולא שדות של אובייקט options, לכן עיין ב-הפניית applyFlagSettings() עבור הסכמה ועבור המפתחות שנכנסים לתוקף באמצע ההפעלה.
• updateSettings(): כותב קבוצה מורשית (allowlisted) של מפתחות לקובץ ההגדרות המקומי של הפרויקט, כמו למשל ב-await session.updateSettings("localSettings", { outputStyle: "Explanatory" }). המפתחות שנכתבו נכנסים לתוקף בבקשה הבאה של ההפעלה ונשמרים עבור הפעלות עתידיות שטוענות הגדרות local. השורה של המתודה ב-טבלת המתודות מפרטת את המפתחות המורשים ואת גרסת המינימום.

הדוגמה להלן מריצה הפעלה בת שני תורות, משנה את התצורה בין התורות, ומדפיסה את המודל שענה בכל תור. ב-TypeScript, זרם ההנחיות מעכב את ההודעה השנייה עד שה-setters סיימו לרוץ, והתור השני רץ על המודל החדש.

TypeScript:

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

function userMessage(text: string): SDKUserMessage {
  return { type: "user", message: { role: "user", content: text }, parent_tool_use_id: null };
}

// Hold the second prompt until the setters have run.
let startSecondTurn!: () => void;
const secondTurnReady = new Promise<void>((resolve) => {
  startSecondTurn = resolve;
});

async function* turnPrompts(): AsyncGenerator<SDKUserMessage, void> {
  yield userMessage("Reply with exactly: ready");
  await secondTurnReady;
  yield userMessage("Reply with exactly: done");
}

const session = query({
  prompt: turnPrompts(),
  options: {
    model: "claude-sonnet-5",
  },
});

let turnModel = "";
let completedTurns = 0;

for await (const message of session) {
  if (message.type === "assistant") {
    turnModel = message.message.model;
  } else if (message.type === "result") {
    completedTurns += 1;
    if (completedTurns === 1) {
      console.log(`First turn model: ${turnModel}`);
      await session.setModel("claude-opus-5");
      await session.setPermissionMode("acceptEdits");
      startSecondTurn();
    } else {
      console.log(`Second turn model: ${turnModel}`);
      break;
    }
  }
}

Python:

import asyncio

from claude_agent_sdk import AssistantMessage, ClaudeAgentOptions, ClaudeSDKClient

async def main():
    options = ClaudeAgentOptions(model="claude-sonnet-5")

    async with ClaudeSDKClient(options=options) as client:
        await client.query("Reply with exactly: ready")
        first_model = ""
        async for message in client.receive_response():
            if isinstance(message, AssistantMessage):
                first_model = message.model

        await client.set_model("claude-opus-5")
        await client.set_permission_mode("acceptEdits")

        await client.query("Reply with exactly: done")
        second_model = ""
        async for message in client.receive_response():
            if isinstance(message, AssistantMessage):
                second_model = message.model

    print(f"First turn model: {first_model}")
    print(f"Second turn model: {second_model}")

asyncio.run(main())

ב-Claude API, התוכנית מדפיסה First turn model: claude-sonnet-5, ולאחר מכן Second turn model: claude-opus-5 לאחר ההחלפה.

הערה: לכל מודל יש מטמון הנחיות (prompt cache) משלו, כך שלאחר החלפה באמצע הפעלה, הבקשה הבאה מחשבת מחדש את השיחה המלאה ללא מטמון בתעריפים של המודל החדש. למידע נוסף, ראה Switching models.

#הגדרת תכונות ספציפיות

הטבלה להלן ממפה כל אפשרות לתכונה שהיא מגדירה. לגבי אפשרויות שדף זה אינו מכסה, ראה את הפניות התיעוד עבור TypeScript ו-Python. אם אתה יודע מה המטרה שלך אך לא איזו אפשרות משרתת אותה, התחל מ-Choose the right feature.

#השלבים הבאים

כדי לראות תצורה מורכבת לכדי סוכנים עובדים:

• Quickstart: בנה והרץ סוכן ראשון מקצה לקצה
• Examples: מצא פרויקט שלם שניתן להרצה או מתכון מודרך של Claude Cookbook שמתאים למה שאתה רוצה לבנות
• Multi-tenant isolation: בודד את ההגדרות ואת הזיכרון של כל דייר (tenant) באמצעות settingSources / setting_sources, env ו-cwd