20. מצב Headless ו-Agent SDK

עד עכשיו דיברנו על Claude Code כעל שיחה אינטראקטיבית: אתם מקלידים, קלוד עונה, אתם מאשרים. אבל אותו מנוע בדיוק אפשר להריץ בלי ממשק בכלל: מתוך סקריפט, מתוך צנרת (pipeline) של פקודות, או כספרייה בתוך אפליקציה שאתם בונים. בפרק הזה נכיר את מצב Headless (הרצת claude -p מהטרמינל) ואת Agent SDK (בניית סוכן משלכם ב-Python או ב-TypeScript). הפרק מיועד בעיקר למפתחים, ומעמיק יותר מפרקים אחרים במדריך.

מצב Headless: קלוד בלי ממשק

הוספת הדגל -p (או --print) לכל פקודת claude מריצה אותה פעם אחת, בלי ממשק אינטראקטיבי: קלוד מקבל בקשה, מבצע אותה, מדפיס תשובה ויוצא. זה נקרא גם "מצב הדפסה" (print mode), ובעבר נקרא "מצב Headless" — השם עדיין נפוץ, וגם ה-CLI משתמש בו בתיעוד.

claude -p "מה עושה מודול ההתחברות בפרויקט הזה?"

למה זה שימושי:

• סקריפטים: להריץ בדיקה, לתקן קוד או לסכם קובץ כחלק מתהליך אוטומטי.
• CI/CD: לינטר מותאם, סקירת קוד אוטומטית, או יצירת commit בסוף pipeline.
• אוטומציה: עיבוד קבצים בכמות גדולה, בלי שמישהו יושב מול המסך.

קלוד Code יוצא עם קוד 0 כשההרצה הצליחה, וקוד שונה מ-0 כשהיא נכשלה — כך סקריפט יכול להסתעף לפי התוצאה. דגל לא תקין מדווח כשגיאה ל-stderr לפני שההרצה מתחילה; כשל בתוך ההרצה עצמה (למשל אימות חסר) מודפס כתוצאה ל-stdout.

מצב Bare: התחלה מהירה יותר

הדגל --bare מדלג על גילוי אוטומטי של Hooks, Skills, פקודות מותאמות, Subagents, Plugins, שרתי MCP, זיכרון אוטומטי ו-CLAUDE.md — כך ההרצה מתחילה מהר יותר, ומתנהגת אותו הדבר בכל מכונה, בלי תלות בהגדרות אישיות שמישהו הגדיר לעצמו.

claude --bare -p "סכם את README.md" --allowedTools "Read"

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

הדגל --output-format קובע איך התשובה חוזרת:

claude -p "סכם את הפרויקט הזה" --output-format json

שדה התשובה נקרא result. שימוש נפוח בכלי כמו jq מחלץ בדיוק מה שצריך:

# חילוץ התשובה בלבד
claude -p "סכם את הפרויקט הזה" --output-format json | jq -r '.result'

פלט לפי סכימה מוגדרת

עם --json-schema אפשר לחייב את קלוד להחזיר בדיוק את המבנה שאתם צריכים:

claude -p "חלץ את שמות הפונקציות הראשיות מ-auth.py" 
  --output-format json 
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}'

התוצאה המובנית מגיעה בשדה structured_output, לצד מטא-דאטה כמו שימוש בטוקנים.

סטרימינג בזמן אמת

עם --output-format stream-json יחד עם --verbose ו---include-partial-messages, אפשר לקבל את התשובה מילה-מילה, כשכל שורה היא אירוע JSON. השורה האחרונה היא הודעת result עם התשובה הסופית, העלות ומטא-דאטת השיחה. שימושי כשבונים ממשק משלכם שמציג את ההתקדמות של קלוד בזמן אמת.

שילוב בצנרת (pipe)

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

cat build-error.txt | claude -p 'הסבר בקצרה מה הגורם השורשי לשגיאת הבנייה הזו' > output.txt

Claude כחלק מסקריפט בנייה

דוגמה: סקריפט ב-package.json שמעביר את ה-diff מול main לקלוד ומבקש לאתר שגיאות כתיב:

{
  "scripts": {
    "lint:claude": "git diff main | claude -p "you are a typo linter. for each typo in this diff, report filename:line on one line and the issue on the next. return nothing else.""
  }
}

מריצים עם npm run lint:claude. העברת ה-diff בצנרת חוסכת לקלוד את הצורך בהרשאת Bash כדי לקרוא אותו בעצמו.

אישור כלים בלי אינטראקציה

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

claude -p "הרץ את סוויטת הבדיקות ותקן כשלים" 
  --allowedTools "Bash,Read,Edit"

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

לתהליכים שרצים לגמרי לבד, כמו משימה מתוזמנת, הוסיפו --permission-prompts none: כל מה שהיה דורש אישור אדם נדחה, קלוד מקבל הודעה שאין מי שיאשר ולא לנסות שוב, וההרצה ממשיכה. כללי הרשאות, Hooks מסוג PermissionRequest ומצב ההרשאות עדיין קובעים ראשונים — הדגל רק דוחה את מה שנשאר.

claude -p "עדכן את גרסאות התלויות והרץ בדיקות" --permission-mode auto --permission-prompts none

יצירת commit אוטומטית

claude -p "תסתכל על השינויים שנשמרו (staged) ותיצור commit עם הודעה מתאימה" 
  --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"

המשך שיחות ממצב Headless

--continue ממשיך את השיחה האחרונה, ו---resume עם מזהה שיחה ממשיך שיחה מסוימת:

# בקשה ראשונה
claude -p "סקור את הפרויקט לאיתור בעיות ביצועים"

# המשך אותה שיחה
claude -p "עכשיו תתמקד בשאילתות למסד הנתונים" --continue
claude -p "תן סיכום של כל הבעיות שנמצאו" --continue

כשמריצים כמה שיחות במקביל, שומרים את מזהה השיחה כדי להמשיך את הנכונה:

session_id=$(claude -p "התחל סקירה" --output-format json | jq -r '.session_id')
claude -p "תמשיך את הסקירה הזו" --resume "$session_id"

מה זה Agent SDK

ה-Agent SDK נותן לכם את אותם כלים, אותה לולאת פעולה (agent loop) ואותו ניהול הקשר שמפעילים את Claude Code — אבל כספרייה שאתם מפעילים מתוך קוד משלכם, ב-Python או ב-TypeScript. במקום להריץ תהליך claude ולפרש את הפלט שלו, אתם קוראים לפונקציה שמחזירה לכם זרם הודעות, ובונים סביבה אפליקציה, אוטומציה או מוצר שלם.

ה-SDK זמין כספרייה רק ל-Python ול-TypeScript. כדי להפעיל את אותה לולאת סוכן משפה אחרת, מריצים את ה-CLI כתת-תהליך עם -p ו---output-format json, כפי שראינו למעלה.

מה זמין דרך ה-SDK

דוגמת קוד מינימלית

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

1. התקנה: ב-TypeScript, npm install @anthropic-ai/claude-agent-sdk. ב-Python, pip install claude-agent-sdk (או uv add claude-agent-sdk). שתי הספריות כוללות בתוכן בינארי של Claude Code, כך שברוב המקרים אין צורך בהתקנה נפרדת.
2. מפתח API: יוצרים מפתח ב-Claude Console וקובעים אותו כמשתנה סביבה ANTHROPIC_API_KEY. ה-SDK לא טוען קובצי .env אוטומטית.
3. כתיבת הסוכן: קוראים לפונקציית query עם הבקשה ועם אפשרויות תצורה.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage

async def main():
    async for message in query(
        prompt="Review utils.py for bugs that would cause crashes. Fix any issues you find.",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Glob"],
            permission_mode="acceptEdits",
        ),
    ):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)
                elif hasattr(block, "name"):
                    print(f"Tool: {block.name}")
        elif isinstance(message, ResultMessage):
            print(f"Done: {message.subtype}")

asyncio.run(main())

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

for await (const message of query({
  prompt: "Review utils.py for bugs that would cause crashes. Fix any issues you find.",
  options: {
    allowedTools: ["Read", "Edit", "Glob"],
    permissionMode: "acceptEdits"
  }
})) {
  if (message.type === "assistant" && message.message?.content) {
    for (const block of message.message.content) {
      if ("text" in block) {
        console.log(block.text);
      } else if ("name" in block) {
        console.log(`Tool: ${block.name}`);
      }
    }
  } else if (message.type === "result") {
    console.log(`Done: ${message.subtype}`);
  }
}

query היא נקודת הכניסה: היא מחזירה איטרטור א-סינכרוני, ולכן משתמשים ב-async for (או for await) כדי לקבל הודעות בזרימה — הרהור של קלוד, קריאה לכלי, תוצאת כלי, או התוצאה הסופית. ה-SDK מטפל בתזמור, בהרצת הכלים, בניהול ההקשר ובניסיונות חוזרים; אתם רק צורכים את הזרם. הלולאה מסתיימת כשקלוד מסיים את המשימה או נתקל בשגיאה.

מתי Agent SDK ומתי ה-CLI

ה-CLI (claude, כולל -p) מתאים לעבודה אינטראקטיבית, למשימות חד-פעמיות ולסקריפטים פשוטים שמריצים אותו כתת-תהליך. ה-Agent SDK מתאים כשאתם בונים מוצר או אפליקציה משלכם: ממשק צ'אט ייעודי, בוט שמטפל בפניות לקוח, כלי פנימי לצוות, או כל מערכת שצריכה שליטה תכנותית מלאה על ההודעות, ההרשאות וההתקדמות של הסוכן — לא רק טקסט שמודפס לטרמינל.