📘 תיעוד 168

הגדרת הסוכן

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

סשן של 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 ו-deny.

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

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

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

העבר [] כדי לבטל הגדרות user, project ו-local. למידע נוסף, ראה שימוש בתכונות Claude Code ב-SDK.

#בחירת מודל

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

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

בכל אחת מהשפות, האפשרות מקבלת מודל יחיד או רשימת גיבויים מופרדת בפסיקים. לסדר ולתקרת השרשרת, ראה שרשראות מודל גיבוי. ב-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 דרך שער על ידי הגדרת 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 קורא, ראה משתני סביבה. כדי לכוון פסקי זמן של API וזיהוי תקיעה בדרך הזו, עקוב אחרי הסעיף Handle slow or stalled API responses ב-הפניית TypeScript או ב-הפניית Python.

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

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

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

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

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

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

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

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

שתי התקרות מתייחסות ל-0 בצורה שונה:

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

למידע נוסף על שתי התקרות, כולל הוצאה של subagent, ראה תורות ותקציב.

#שינוי תצורה באמצע הסשן

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

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

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

• setModel() / set_model(): מחליף את המודל. קרא לו בלי מודל כדי לעבור ל-מודל ברירת המחדל של Claude Code ולא ל-model שהעברת באפשרויות. אם הסשן במצב auto ואתה עובר למודל שמצב auto לא תומך בו, הסשן משתנה למצב default. כדי לחזור למצב auto, ראה מצב Auto (auto).
• setPermissionMode() / set_permission_mode(): מחליף את מצב ההרשאות

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

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

הדוגמה למטה מריצה סשן של שני תורות, משנה את התצורה בין התורות, ומדפיסה את המודל שענה על כל תור. ב-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 אחרי המעבר.

הערה

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

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

הטבלה למטה ממפה כל אפשרות לתכונה שהיא מגדירה. לאפשרויות שהדף הזה לא מכסה, ראה את עמודי העזר של TypeScript ושל Python. אם אתה יודע את המטרה אבל לא איזו אפשרות משרתת אותה, התחל מבחירת התכונה הנכונה.

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

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

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