📘 תיעוד 129

כיצד פועלת לולאת הסוכן

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

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

הן ה-SDK ל-TypeScript והן ה-SDK ל-Python כוללים קובץ בינארי מקורי של Claude Code, כך שמרבית ההתקנות אינן דורשות התקנה נפרדת של Claude Code. ראה את הערת ההתקנה במדריך ההתחלה המהירה עבור ההתקנות שכן דורשות זאת.

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

#מבט חטוף על הלולאה

כל הפעלת סוכן (session) פועלת לפי אותו מחזור:

1. קבלת הבקשה (prompt). קלוד מקבל את הבקשה שלך, יחד עם הוראת המערכת (system prompt), הגדרות הכלים והיסטוריית השיחה. ה-SDK מפיק SystemMessage עם תת-סוג "init" שמכיל מטא-דאטה של ההפעלה.
2. הערכה ותגובה. קלוד מעריך את המצב הנוכחי וקובע כיצד להמשיך. הוא עשוי להגיב בטקסט, לבקש קריאה לכלי אחד או יותר, או שניהם. ה-SDK מפיק AssistantMessage המכיל את הטקסט ואת כל הבקשות לקריאות כלים.
3. ביצוע כלים. ה-SDK מריץ כל כלי שהתבקש ואוסף את התוצאות. כל קבוצת תוצאות של כלים מוזנת בחזרה לקלוד לצורך ההחלטה הבאה. ניתן להשתמש ב-hooks כדי ליירט, לשנות או לחסום קריאות לכלים לפני הפעלתן.
4. חזרה. שלבים 2 ו-3 חוזרים על עצמם כמחזור. כל מחזור מלא הוא תור (turn) אחד. קלוד ממשיך לקרוא לכלים ולעבד תוצאות עד שהוא מפיק תגובה ללא קריאות לכלים.
5. החזרת תוצאה. ה-SDK מפיק AssistantMessage סופי עם תגובת הטקסט (ללא קריאות לכלים), ולאחריו ResultMessage עם הטקסט הסופי, ניצול הטוקנים, עלות ו-session ID.

שאלה מהירה ("אילו קבצים נמצאים כאן?") עשויה לקחת תור אחד או שניים של קריאה ל-Glob ותגובה עם התוצאות. משימה מורכבת ("שכתב את מודול האימות ועדכן את הבדיקות") יכולה לשרשר עשרות קריאות לכלים על פני תורות רבים, קריאת קבצים, עריכת קוד והרצת בדיקות, כאשר קלוד מתאים את גישתו על סמך כל תוצאה.

#תורות והודעות

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

חשוב כיצד עשויה להיראות הפעלה מלאה עבור הבקשה "Fix the failing tests in auth.ts".

תחילה, ה-SDK שולח את הבקשה שלך לקלוד ומפיק SystemMessage עם מטא-דאטה של ההפעלה. לאחר מכן הלולאה מתחילה:

1. תור 1: קלוד קורא ל-Bash כדי להריץ npm test. ה-SDK מפיק AssistantMessage עם קריאת הכלי, מבצע את הפקודה, ולאחר מכן מפיק UserMessage עם הפלט (שלושה כשלים).
2. תור 2: קלוד קורא ל-Read על auth.ts ו-auth.test.ts. ה-SDK מחזיר את תוכן הקבצים ומפיק AssistantMessage.
3. תור 3: קלוד קורא ל-Edit כדי לתקן את auth.ts, ואז קורא ל-Bash כדי להריץ שוב את npm test. כל שלוש הבדיקות עוברות בהצלחה. ה-SDK מפיק AssistantMessage.
4. תור סופי: קלוד מפיק תגובת טקסט בלבד ללא קריאות לכלים: "Fixed the auth bug, all three tests pass now." ה-SDK מפיק AssistantMessage סופי עם טקסט זה, ולאחריו ResultMessage עם אותו הטקסט בתוספת עלות ושימוש.

אלה היו ארבעה תורות: שלושה עם קריאות לכלים, ותגובת טקסט סופית אחת.

באפשרותך להגביל את הלולאה באמצעות max_turns / maxTurns, הסופר תורות של שימוש בכלים בלבד. לדוגמה, max_turns=2 בלולאה שלעיל היה עוצר לפני שלב העריכה. ניתן גם להשתמש ב-max_budget_usd / maxBudgetUsd כדי להגביל תורות על סמך סף הוצאה.

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

#סוגי הודעות

במהלך ריצת הלולאה, ה-SDK מפיק זרם (stream) של הודעות. כל הודעה נושאת סוג המציין מאיזה שלב בלולאה היא הגיעה. חמשת הסוגים העיקריים הם:

• SystemMessage: אירועי מחזור חיי ההפעלה. השדה subtype מבדיל ביניהם:

  • "init": מטא-דאטה של ההפעלה עבור הריצה. כאשר hook מסוג SessionStart או Setup רץ בעת הפעלת ה-session, הודעות מחזור החיים של ה-hook שלו מגיעות לפני הודעת ה-init.
  • "compact_boundary": מופעל לאחר דחיסה (compaction).
  • "informational": הודעות סטטוס בטקסט רגיל מהלולאה.
  • "worker_shutting_down": הלולאה תסתיים לאחר התור הנוכחי מכיוון שהמארח יוצא או ש-Remote Control התנתק.

  ב-TypeScript, כל תת-סוג מלבד "init" הוא טיפוס עצמאי בתוך איחוד הטיפוסים SDKMessage ולא תת-סוג של SDKSystemMessage.

• AssistantMessage: נפלט לאחר כל תגובה של קלוד, כולל תגובת הטקסט הסופית. מכיל בלוקי תוכן טקסטואליים ובלוקים של קריאות לכלים מאותו תור.

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

• StreamEvent: נפלט רק כאשר הודעות חלקיות מופעלות. מכיל אירועי הזרמה גולמיים מה-API (הפרשי טקסט, מקטעי קלט של כלים). ראה הזרמת תגובות.

• ResultMessage: מסמן את סיום לולאת הסוכן. מכיל את תוצאת הטקסט הסופית, ניצול הטוקנים, עלות ו-session ID. בדוק את השדה subtype כדי לקבוע אם המשימה הצליחה או הגיעה למגבלה. מספר קטן של אירועי מערכת עוקבים, כגון prompt_suggestion, עשויים להגיע אחריו, לכן עבור בלולאה על הזרם עד להשלמתו במקום לעצור בתוצאה. ראה טיפול בתוצאה.

חמשת הסוגים הללו מכסים את מלוא מחזור החיים של לולאת הסוכן. שני ה-SDKs מפיקים גם אירועי ניטור (observability) כגון סטטוס מגבלות קצב (rate-limit) והודעות משימה שאינם נדרשים להנעת הלולאה. ראה את הפניית סוגי ההודעות ב-Python ואת הפניית סוגי ההודעות ב-TypeScript עבור הרשימות המלאות.

#טיפול בהודעות

באילו הודעות תטפל תלוי במה שאתה בונה:

• תוצאות סופיות בלבד: טפל ב-ResultMessage כדי לקבל את הפלט, העלות, והאם המשימה הצליחה או הגיעה למגבלה.
• עדכוני התקדמות: טפל ב-AssistantMessage כדי לראות מה קלוד עושה בכל תור, כולל לאילו כלים הוא קרא.
• הזרמה חיה: הפעל הודעות חלקיות (include_partial_messages ב-Python, includePartialMessages ב-TypeScript) כדי לקבל הודעות StreamEvent בזמן אמת. ראה הזרמת תגובות בזמן אמת.

האופן שבו אתה בודק את סוגי ההודעות תלוי ב-SDK:

• Python: בדוק את סוגי ההודעות בעזרת isinstance() מול מחלקות שיובאו מ-claude_agent_sdk (לדוגמה, isinstance(message, ResultMessage)).
• TypeScript: בדוק את שדה המחרוזת type (לדוגמה, message.type === "result"). הטיפוסים AssistantMessage ו-UserMessage עוטפים את הודעת ה-API הגולמית בתוך שדה .message, כך שבלוקי התוכן נמצאים ב-message.message.content ולא ב-message.content.

#דוגמה: בדיקת סוגי הודעות וטיפול בתוצאות

Python:

import asyncio
from claude_agent_sdk import query, AssistantMessage, ResultMessage


async def main():
    try:
        async for message in query(prompt="Summarize this project"):
            if isinstance(message, AssistantMessage):
                print(f"Turn completed: {len(message.content)} content blocks")
            if isinstance(message, ResultMessage):
                if message.subtype == "success":
                    print(message.result)
                else:
                    print(f"Stopped: {message.subtype}")
    except Exception as error:
        
# A single-shot query() raises after yielding an error result. If the
        
# failure was an error result, the error subtype branches above have
        
# already run; connection or process failures yield no result message.
        print(f"Session ended with an error: {error}")


asyncio.run(main())

TypeScript:

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

try {
  for await (const message of query({ prompt: "Summarize this project" })) {
    if (message.type === "assistant") {
      console.log(`Turn completed: ${message.message.content.length} content blocks`);
    }
    if (message.type === "result") {
      if (message.subtype === "success") {
        console.log(message.result);
      } else {
        console.log(`Stopped: ${message.subtype}`);
      }
    }
  }
} catch (error) {
  // A single-shot query() throws after yielding an error result. If the
  // failure was an error result, the error subtype branches above have
  // already run; connection or process failures yield no result message.
  console.log(`Session ended with an error: ${error}`);
}

#ביצוע כלים

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

#כלים מובנים

ה-SDK כולל את אותם הכלים שמניעים את Claude Code:

ב-מודלים שאינם מקבלים את כלי מעקב המשימות, Claude Code מספק את TaskCreate ו-TaskUpdate רק כאשר אתה בוחר בכך מפורשות (opt in).

מעבר לכלים המובנים, באפשרותך:

• לחבר שירותים חיצוניים באמצעות שרתי MCP (מסדי נתונים, דפדפנים, ממשקי API).
• להגדיר כלים מותאמים אישית באמצעות מטפלי כלים מותאמים אישית (custom tool handlers).
• לטעון מיומנויות (skills) של הפרויקט דרך מקורות הגדרות (setting sources) עבור תהליכי עבודה לשימוש חוזר.

#הרשאות כלים

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

• allowed_tools / allowedTools מאשר אוטומטית את הכלים הרשומים. סוכן לקריאה בלבד עם ["Read", "Glob", "Grep"] ברשימת הכלים המורשים שלו מריץ כלים אלה מבלי לבקש אישור. כלים שאינם רשומים עדיין זמינים אך דורשים הרשאה.
• disallowed_tools / disallowedTools חוסם את הכלים הרשומים, ללא תלות בהגדרות אחרות. ראה הרשאות עבור הסדר שבו כללים נבדקים לפני שכלי רץ.
• permission_mode / permissionMode שולט ברמת הפיקוח האנושי הרצויה. ה-SDK מעריך את המצב הפעיל יחד עם כללי ההרשאה והחסימה שלך בסדר קבוע, המתואר ב-כיצד מוערכות הרשאות. ראה מצב הרשאה עבור המצבים הזמינים.

באפשרותך גם להגדיר היקף עבור כלים בודדים באמצעות כללים כגון "Bash(npm *)" כדי לאפשר פקודות ספציפיות בלבד. ראה הרשאות לתחביר הכללים המלא.

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

#ביצוע כלים במקביל

כאשר קלוד מבקש מספר קריאות לכלים בתור יחיד, שני ה-SDKs יכולים להריץ אותם במקביל או בסדרתיות בהתאם לכלי. כלים לקריאה בלבד (כמו Read, Glob, Grep וכלים של MCP המסומנים כקריאה בלבד) יכולים לרוץ במקביל. כלים המשנים מצב (כמו Edit, Write ו-Bash) רצים בסדרתיות כדי למנוע התנגשויות.

כלים מותאמים אישית פועלים כברירת מחדל בסדרתיות. כדי לאפשר ביצוע במקביל עבור כלי מותאם אישית, הגדר readOnlyHint בהערות (annotations) שלו. הן ה-SDK של TypeScript והן של Python משתמשים בשם שדה זה מתוך ה-MCP SDK.

#שליטה על אופן ריצת הלולאה

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

#תורות ותקציב

כאשר אחת המגבלות מגיעה לסופה, ה-SDK מחזיר ResultMessage עם תת-סוג שגיאה תואם (error_max_turns או error_max_budget_usd). ראה טיפול בתוצאה לגבי אופן בדיקת תת-סוגים אלה, ואת ClaudeAgentOptions / Options עבור התחביר.

תקרת התקציב מכסה גם סוכני משנה (subagents): ההוצאה שלהם נספרת כחלק מסך הכל. ברגע שההוצאה מגיעה לתקרה, יצירת סוכן משנה נוסף נכשלת עם Budget limit reached, ו-Claude Code עוצר את כל סוכני המשנה שעדיין רצים ברקע. התנהגויות אכיפת התקרה דורשות את Claude Code גרסה v2.1.217 ואילך.

עם קלט בהזרמה (streaming input), הודעה שעדיין ממתינה בתור כאשר תור מסתיים במגבלת מקסימום תורות נשארת בתור. Claude Code אינו מוסיף אותה לקריאת המודל האחרונה של אותו תור. הוא מתחיל תור חדש עבור ההודעה, וספירת מקסימום התורות מתחילה מחדש עבור תור זה.

#רמת מאמץ (Effort level)

האפשרות effort שולטת בכמות שיקול הדעת (reasoning) שקלוד מפעיל. רמות מאמץ נמוכות יותר משתמשות בפחות טוקנים לתור ומפחיתות עלויות. לא כל המודלים תומכים בפרמטר המאמץ. ראה Effort לגבי המודלים התומכים בו.

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

הערה: הפרמטר effort ממיר בין זמני תגובה (latency) ועלות טוקנים לבין עומק שיקול הדעת בתוך כל תגובה. חשיבה מורחבת (Extended thinking) היא תכונה נפרדת המפיקה בלוקי thinking בפלט, והשדה display ב-ThinkingConfig עבור Python או TypeScript קובע אם תקבל את הטקסט שלהם. הן בלתי תלויות: ניתן להגדיר effort: "low" עם חשיבה מורחבת מופעלת, או effort: "max" בלעדיה.

השתמש ברמת מאמץ נמוכה יותר עבור סוכנים המבצעים משימות פשוטות ומוגדרות היטב (כמו רישום קבצים או הרצת grep בודד) כדי להפחית עלות וזמני תגובה. הגדר את effort באפשרויות ה-query() ברמה העליונה עבור ההפעלה כולה, או לכל סוכן משנה בנפרד באמצעות השדה effort ב-AgentDefinition כדי לדרוס את הרמה שהוגדרה להפעלה.

#מצב הרשאה

אפשרות מצב ההרשאה (permission_mode ב-Python, permissionMode ב-TypeScript) שולטת בשאלה האם הסוכן מבקש אישור לפני שימוש בכלים:

עבור יישומים אינטראקטיביים, השתמש ב-"default" עם callback לאישור כלים כדי להציג בקשות אישור. עבור סוכנים אוטונומיים במכונת פיתוח, "acceptEdits" מאשר אוטומטית עריכות קבצים ופקודות מערכת קבצים נפוצות (mkdir, touch, mv, cp וכו') בעודו ממשיך להתנות פקודות Bash אחרות בכללי אישור. שמור את "bypassPermissions" עבור CI, קונטיינרים או סביבות מבודדות אחרות. ראה הרשאות לפרטים מלאים.

#מודל

אם לא תגדיר model, ה-SDK ישתמש בברירת המחדל של Claude Code, התלויה בשיטת האימות ובמנוי שלך. הגדר אותו במפורש (לדוגמה, model="claude-sonnet-5") כדי לקבע מודל ספציפי או כדי להשתמש במודל קטן יותר עבור סוכנים מהירים וזולים יותר. ראה מודלים עבור מזהים זמינים.

#חלון ההקשר

חלון ההקשר הוא כמות המידע הכוללת הזמינה לקלוד במהלך הפעלה (session). הוא אינו מתאפס בין תורות בתוך אותה הפעלה. הכל מצטבר: הוראת המערכת (system prompt), הגדרות הכלים, היסטוריית השיחה, קלטי הכלים ופלטי הכלים. תוכן שנשאר זהה בין תורות (הוראת מערכת, הגדרות כלים, CLAUDE.md) נשמר אוטומטית במטמון prompt cached, מה שמפחית עלויות וזמני תגובה עבור קידומות חוזרות. לגבי האופן שבו הוראת מערכת מותאמת אישית או טקסט append משפיעים על שימוש חוזר במטמון בין הפעלות שונות, ראה שינוי הוראות מערכת.

#מה צורך הקשר

להלן האופן שבו כל רכיב משפיע על ההקשר ב-SDK:

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

#דחיסה אוטומטית (Automatic compaction)

כאשר חלון ההקשר מתקרב למגבלה שלו, ה-SDK דוחס אוטומטית את השיחה: הוא מסכם היסטוריה ישנה יותר כדי לפנות מקום, תוך שמירה על חילופי הדברים האחרונים וההחלטות המרכזיות שלך ללא פגע. ה-SDK פולט הודעה עם type: "system" ו-subtype: "compact_boundary" בזרם כאשר זה מתרחש (ב-Python זוהי SystemMessage; ב-TypeScript זהו טיפוס נפרד מסוג SDKCompactBoundaryMessage).

הדחיסה מחליפה הודעות ישנות יותר בסיכום, כך שהוראות ספציפיות מתחילת השיחה עלולות שלא להישמר. מקומם של כללים קבועים הוא ב-CLAUDE.md (הנטען דרך settingSources) ולא בבקשה הראשונית, מכיוון שתוכן CLAUDE.md מוזרק מחדש בכל בקשה.

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

• הוראות סיכום ב-CLAUDE.md: רכיב הדחיסה קורא את קובץ ה-CLAUDE.md שלך כמו כל הקשר אחר, כך שתוכל לכלול סעיף המורה לו מה לשמר בעת הסיכום. רכיב הדחיסה מתאים לפי כוונה, כך שכותרת הסעיף היא במבנה חופשי.
• Hook מסוג PreCompact: הרץ לוגיקה מותאמת אישית לפני ביצוע הדחיסה, לדוגמה כדי לארכב את התמליל המלא. ה-hook מקבל שדה trigger (בערכים manual או auto). ראה hooks.
• דחיסה ידנית: שלח /compact כמחרוזת בקשה (prompt) כדי להפעיל דחיסה לפי דרישה. פקודות הנשלחות בדרך זו הן קלטי SDK רגילים. ראה שיגור פקודות לפי שם.

#דוגמה: הוראות סיכום ב-CLAUDE.md

הוסף סעיף לקובץ CLAUDE.md של הפרויקט שלך המורה לרכיב הדחיסה מה לשמר. שם הכותרת אינו מיוחד; השתמש בכל תווית ברורה.

# Summary instructions

When summarizing this conversation, always preserve:
- The current task objective and acceptance criteria
- File paths that have been read or modified
- Test results and error messages
- Decisions made and the reasoning behind them

#שמירה על יעילות ההקשר

מספר אסטרטגיות עבור סוכנים בעלי זמן ריצה ממושך:

• השתמש בסוכני משנה למשימות משנה. כל סוכן משנה מתחיל עם שיחה חדשה (ללא היסטוריית הודעות קודמת, אם כי הוא כן טוען הוראת מערכת משלו והקשר ברמת הפרויקט כמו CLAUDE.md). הוא אינו רואה את התורות של סוכן האב, ורק תגובתו הסופית חוזרת לסוכן האב כתוצאת כלי. ההקשר של הסוכן הראשי גדל באותו סיכום בלבד, ולא בכל תמליל משימת המשנה המלא. ראה מה סוכני משנה יורשים לפרטים.
• היה סלקטיבי בכלים. כל הגדרת כלי תופסת מקום בהקשר. השתמש בשדה tools ב-AgentDefinition כדי להגביל סוכני משנה לקבוצה המינימלית הנחוצה להם.
• שים לב לעלויות של שרתי MCP. מנגנון חיפוש כלי MCP משהה סכמות של כלי MCP כברירת מחדל וטוען אותן לפי דרישה. כאשר חיפוש הכלים כבוי או נסוג לטעינה מראש, כל שרת MCP מוסיף את כל סכמות הכלים שלו לכל בקשה, כך שמספר שרתים עם כלים רבים יכולים לצרוך הקשר משמעותי עוד לפני שהסוכן ביצע עבודה כלשהי. ראה הגדרת חיפוש כלים עבור התצורות שבהן הנסיגה חלה.
• השתמש במאמץ נמוך יותר למשימות שגרתיות. הגדר את effort כ-"low" עבור סוכנים שצריכים רק לקרוא קבצים או לרשום ספריות. הדבר מפחית את השימוש בטוקנים ואת העלות.

לפירוט מעמיק של עלויות הקשר לפי תכונה, ראה הבנת עלויות הקשר.

#הפעלות (Sessions) והמשכיות

כל אינטראקציה עם ה-SDK יוצרת או ממשיכה הפעלה (session). שמור את ה-session ID מתוך ResultMessage.session_id (זמין בשני ה-SDKs) כדי לחדש את הפעולה מאוחר יותר. ה-SDK של TypeScript חושף אותו גם כשדה ישיר בהודעת ה-SystemMessage מסוג init; ב-Python הוא מקונן בתוך SystemMessage.data.

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

ראה ניהול הפעלות למדריך המלא על דפוסי חידוש (resume), המשך (continue) ופיצול (fork). כדי לחדש הפעלות בין קונטיינרים נטולי מצב (stateless) או מארחי serverless, העבר מתאם session_store / sessionStore כך שה-SDK ישקף תמלילים למערכת ה-backend שלך ומארח אחר יוכל לחדש אותם. תהליך המשנה של Claude Code עדיין כותב לדיסק המקומי תחילה. ראה ארכיטקטורת כתיבה כפולה לגבי איזה עותק שורד הפעלה חדשה לעומת ריצה שחודשה מהמאגר, וכיצד לשמור על העותק המקומי ארעי (ephemeral).

הערה: ב-Python, המחלקה ClaudeSDKClient מטפלת ב-session IDs באופן אוטומטי בין קריאות מרובות. ראה את הפניית Python SDK לפרטים.

#טיפול בתוצאה

כאשר הלולאה מסתיימת, ה-ResultMessage מודיע לך מה קרה ומספק לך את הפלט. השדה subtype (הזמין בשני ה-SDKs) הוא הדרך העיקרית לבדוק את מצב הסיום.

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

כל תת-סוגי התוצאה כוללים את total_cost_usd, usage, num_turns ו-session_id כדי שתוכל לעקוב אחר עלויות ולחדש את הפעולה גם לאחר שגיאות. שני דברים שיש להיזהר מהם:

• לאחר קריסת הפעלה, התוצאה הסופית היא error_during_execution ששדות העלות שלה עשויים להיות מאופסים וש-stop_reason שלה הוא null, והתהליך מסתיים לאחר פליטתה. ראה שחזור סכומים כוללים לאחר קריסת הפעלה.
• ב-Python, השדות total_cost_usd, usage ו-model_usage מוגדרים כאופציונליים, לכן בדוק שאינם None לפני שאתה קורא אותם.

השדה usage מכסה רק את לולאת הסוכן הראשית. השתמש ב-modelUsage, או model_usage ב-Python, עבור חישוב טוקנים ועלויות של כל עץ הקריאות. ראה מעקב אחר עלויות ושימוש לפרטים על פירוש שדות ה-usage.

הערה: כאשר שאילתה מסתיימת בתוצאת שגיאה:

• קריאת query() חד-פעמית (single-shot) פולטת את הודעת התוצאה הסופית, ולאחר מכן מעלה שגיאה הכוללת את טקסט הכשל, כגון Reached maximum number of turns. העלאת השגיאה היא מכוונת. עטוף את הלולאה בבלוק try אם הקוד שלך צריך להמשיך לרוץ אחריה. תהליך ה-Claude Code הבסיסי יוצא גם הוא עם קוד יציאה שאינו אפס.
• הפעלה עם קלט בהזרמה נשארת פעילה, ותוכל להמשיך לשלוח הודעות, למעט לאחר קריסת הפעלה, אשר פולטת תוצאת error_during_execution סופית ומסיימת את התהליך.

התוצאה כוללת גם שדה stop_reason (ב-TypeScript: string | null, ב-Python: str | None) המציין מדוע המודל עצר את היצירה בתור הסופי שלו. ערכים נפוצים הם end_turn (המודל סיים כרגיל), max_tokens (הגיע למגבלת טוקני הפלט) ו-refusal (המודל סירב לבקשה). בתוצאות שגיאה שלולאת הסוכן הפיקה, stop_reason נושא את הערך מתגובת ה-assistant האחרונה לפני סיום הלולאה; התוצאה ש-Claude Code מייצר באופן מלאכותי לאחר קריסת הפעלה נושאת null.

כדי לזהות סירובים, בדוק stop_reason === "refusal" (ב-TypeScript) או stop_reason == "refusal" (ב-Python). ראה SDKResultMessage (TypeScript) או ResultMessage (Python) עבור הטיפוס המלא.

#מנגנוני הוק (Hooks)

מנגנוני Hooks הם פונקציות callback המופעלות בנקודות ספציפיות בלולאה: לפני שכלי רץ, אחרי שהוא מחזיר תשובה, כאשר הסוכן מסיים, וכן הלאה. כמה מה-hooks הנפוצים הם:

ה-hooks רצים בתהליך היישום שלך, לא בתוך חלון ההקשר של הסוכן, ולכן אינם צורכים הקשר. hooks יכולים גם לקצר את הלולאה: hook מסוג PreToolUse הדוחה קריאה לכלי מונע את ביצועה, וקלוד מקבל את הודעת הדחייה במקום זאת.

שני ה-SDKs תומכים בכל האירועים שלעיל. ה-SDK של TypeScript כולל אירועים נוספים ש-Python עדיין אינו תומך בהם. ראה שליטה בביצוע באמצעות hooks לרשימת האירועים המלאה, זמינות לפי SDK, וממשק ה-callback המלא.

#חיבור הכל ביחד

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

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

Python:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage


async def run_agent():
    session_id = None

    try:
        async for message in query(
            prompt="Find and fix the bug causing test failures in the auth module",
            options=ClaudeAgentOptions(
                allowed_tools=[
                    "Read",
                    "Edit",
                    "Bash",
                    "Glob",
                    "Grep",
                ],  
# Listing tools here auto-approves them (no prompting)
                setting_sources=[
                    "project"
                ],  
# Load CLAUDE.md, skills, hooks from current directory
                max_turns=30,  
# Prevent runaway sessions
                effort="high",  
# Thorough reasoning for complex debugging
            ),
        ):
            
# Handle the final result
            if isinstance(message, ResultMessage):
                session_id = message.session_id  
# Save for potential resumption

                if message.subtype == "success":
                    print(f"Done: {message.result}")
                elif message.subtype == "error_max_turns":
                    
# Agent ran out of turns. Resume with a higher limit.
                    print(f"Hit turn limit. Resume session {session_id} to continue.")
                elif message.subtype == "error_max_budget_usd":
                    print("Hit budget limit.")
                else:
                    print(f"Stopped: {message.subtype}")
                if message.total_cost_usd is not None:
                    print(f"Cost: ${message.total_cost_usd:.4f}")
    except Exception as error:
        
# A single-shot query() raises after yielding an error result. If the
        
# failure was an error result, the error subtype branches above have
        
# already run; connection or process failures yield no result message.
        print(f"Session ended with an error: {error}")


asyncio.run(run_agent())

TypeScript:

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

let sessionId: string | undefined;

try {
  for await (const message of query({
    prompt: "Find and fix the bug causing test failures in the auth module",
    options: {
      allowedTools: ["Read", "Edit", "Bash", "Glob", "Grep"], // Listing tools here auto-approves them (no prompting)
      settingSources: ["project"], // Load CLAUDE.md, skills, hooks from current directory
      maxTurns: 30, // Prevent runaway sessions
      effort: "high" // Thorough reasoning for complex debugging
    }
  })) {
    // Save the session ID to resume later if needed
    if (message.type === "system" && message.subtype === "init") {
      sessionId = message.session_id;
    }

    // Handle the final result
    if (message.type === "result") {
      if (message.subtype === "success") {
        console.log(`Done: ${message.result}`);
      } else if (message.subtype === "error_max_turns") {
        // Agent ran out of turns. Resume with a higher limit.
        console.log(`Hit turn limit. Resume session ${sessionId} to continue.`);
      } else if (message.subtype === "error_max_budget_usd") {
        console.log("Hit budget limit.");
      } else {
        console.log(`Stopped: ${message.subtype}`);
      }
      console.log(`Cost: $${message.total_cost_usd.toFixed(4)}`);
    }
  }
} catch (error) {
  // A single-shot query() throws after yielding an error result. If the
  // failure was an error result, the error subtype branches above have
  // already run; connection or process failures yield no result message.
  console.log(`Session ended with an error: ${error}`);
}

כאשר הסוכן מסיים בהצלחה, הדוגמה מדפיסה שורת Done: עם סיכום התיקון של הסוכן, ולאחר מכן שורה כגון Cost: $0.0312.

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

כעת, משהבנת את הלולאה, הנה לאן לפנות בהתאם למה שאתה בונה:

• עדיין לא הפעלת סוכן? התחל עם מדריך ההתחלה המהירה (quickstart) כדי להתקין את ה-SDK ולראות דוגמה מלאה הפועלת מקצה לקצה.
• מוכן להתחבר לפרויקט שלך? טען את CLAUDE.md, מיומנויות (skills) ו-hooks של מערכת הקבצים כדי שהסוכן יפעל לפי מוסכמות הפרויקט שלך באופן אוטומטי.
• בונה ממשק משתמש אינטראקטיבי? הפעל הזרמה (streaming) כדי להציג טקסט וקריאות לכלים בשידור חי תוך כדי ריצת הלולאה.
• זקוק לשליטה הדוקה יותר על מה שהסוכן יכול לעשות? נעל גישה לכלים באמצעות הרשאות, והשתמש ב-hooks כדי לבקר, לחסום או לשנות קריאות לכלים לפני ביצוען.
• מריץ משימות ארוכות או יקרות? העבר עבודה מבודדת ל-סוכני משנה (subagents) כדי לשמור על ההקשר הראשי שלך רזה.
• פורס כשירות? ראה אירוח ה-Agent SDK להנחיות לגבי קונטיינרים ו-serverless, ואת אחסון הפעלות (Session storage) לשמירת הפעלות ב-backend שלך.

לתמונה הרעיונית הרחבה יותר של לולאת הסוכן (שאינה ייעודית ל-SDK), ראה כיצד Claude Code פועל. למדריך מעשי לעיצוב לולאות ב-Claude Code, מלולאות מבוססות תורות ועד לולאות מבוססות יעדים ולולאות יזומות (proactive), ראה הנדסת לולאות: תחילת העבודה עם לולאות בבלוג.