בניית סוכן AI ראשון עם Claude Agent SDK: מדריך מעשי בעברית

מה זה סוכן AI ובמה הוא שונה מצ׳אטבוט?

בניית סוכן AI ראשון עם Claude Agent SDK נעשית ב־4 צעדים: מתקינים את החבילה, מגדירים מפתח API, בוחרים כלים והרשאות, ומריצים משימה עם query. כאן נבנה סוכן על Claude Opus 5.5 שקורא קובצי CSV וכותב דוח מכירות. סוכן הוא תוכנה שמקבלת משימה, מתכננת בעצמה את הצעדים וקוראת לכלים: קריאת קבצים, הרצת פקודות או עריכת מסמכים. כך מגדירה אותו סקירת ה־Agent SDK של Anthropic (נפתח בחלון חדש).

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

המדריך נכתב בהשראת המאמר של Khairallah AL-Awady ב־X (How to Actually Build Your First AI Agent Using Claude Opus 5.5 (נפתח בחלון חדש), 4 באוקטובר 2026). הקוד, המספרים וההמלצות כאן נבדקו מול התיעוד הרשמי של Anthropic, והדוגמאות נכתבו מחדש למקרה עסקי ישראלי.

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

איזו דרך לבנות מתאימה לסוכן ראשון?

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

לסוכן ראשון שמשולב בקוד שלכם, Agent SDK הוא נקודת הפתיחה הנוחה. הוא מביא את אותה לולאה, את אותם כלים מובנים ואת אותו ניהול ההקשר, ששלושתם מפעילים את Claude Code. הקוד שלכם ב־Python או TypeScript מפעיל את Claude Code בתהליך משנה ומקבל ממנו את זרם ההודעות Agent SDK overview (נפתח בחלון חדש).

איזו משימה כדאי לתת לסוכן הראשון?

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

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

1. כתבו את המשימה במשפט אחד, עם קלט ופלט ברורים.
2. כתבו מה נחשב ״גמור״: קובץ שקיים, מספרים שתואמים, רשימה שנסגרה.
3. ודאו שהקלט הוא עותק, לא הקבצים המקוריים של העסק.
4. החליטו מראש כמה זמן וכסף ההרצה הראשונה שווה לכם.

איך מתקינים את Claude Agent SDK ומחברים מפתח API?

צריך Python 3.10 ומעלה (או Node.js 18 ומעלה ל־TypeScript) ומפתח API מ־Claude Console Agent SDK quickstart (נפתח בחלון חדש). החבילה ל־Python נקראת claude-agent-sdk, וב־TypeScript @anthropic-ai/claude-agent-sdk.

ה־SDK קורא את המפתח ממשתנה הסביבה ANTHROPIC_API_KEY של התהליך שמריץ את הסוכן. הוא לא טוען קובץ .env בעצמו, ולכן הודעת Invalid API key אחרי התקנה תקינה נובעת בדרך כלל מטרמינל אחר שבו המשתנה לא הוגדר. אל תשמרו את המפתח בקוד ואל תעלו אותו ל־Git.

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

mkdir first-agent && cd first-agent
python3 -m venv .venv
source .venv/bin/activate
pip install claude-agent-sdk==0.2.163

# API key from the Claude Console, set in the same shell that runs the agent
export ANTHROPIC_API_KEY="paste-your-key-here"

הסוכן הראשון: סיכום תיקיית CSV לדוח מכירות

הפונקציה query פותחת את לולאת הסוכן ומחזירה זרם הודעות: מחשבות, קריאות לכלים, תוצאות, ובסוף ResultMessage עם סטטוס ועלות. אתם לא כותבים את הכלים Read או Write בעצמכם; ה־SDK מריץ אותם.

צרו תיקייה exports עם 2 או 3 קובצי CSV לדוגמה והריצו python agent.py. השדה subtype בסוף יהיה success כשהלולאה הגיעה לסיום, או למשל error_max_turns כשההרצה נעצרה על מגבלה. גם עם success בדקו את is_error, שמסמן כשל בבקשת המודל האחרונה. ונכונות הדוח עצמו נבדקת תמיד מול הנתונים. כבר בדוגמה הראשונה מוגדרים תקציב, מגבלת סבבים והפרדה מהגדרות מקומיות. הפלט נכתב לתיקיית agent-output-* חדשה לצד agent.py, ששמה מודפס בתחילת ההרצה. ה-hook מתיר כתיבה רק לקובצי הפלט של אותה הרצה.

import asyncio
from pathlib import Path
from tempfile import mkdtemp
from typing import Any
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage, HookMatcher, HookContext

WORKSPACE = Path(__file__).resolve().parent
OUTPUT_DIR = Path(mkdtemp(prefix="agent-output-", dir=WORKSPACE))
REPORT = OUTPUT_DIR / "report.md"
CHECKLIST = OUTPUT_DIR / "checklist.md"

TASK = (
    f"Read every CSV file in ./exports and write {REPORT} with total sales "
    "per month and the 3 largest customers by revenue."
)


async def guard_output_paths(
    input_data: dict[str, Any], tool_use_id: str | None, context: HookContext
) -> dict[str, Any]:
    if input_data["tool_name"] not in ("Write", "Edit"):
        return {}
    raw = input_data["tool_input"].get("file_path") or ""
    path = Path(raw)
    if not path.is_absolute():
        path = WORKSPACE / path
    allowed = {REPORT, CHECKLIST}
    if not raw or path.is_symlink() or path.resolve() not in allowed:
        return {
            "hookSpecificOutput": {
                "hookEventName": "PreToolUse",
                "permissionDecision": "deny",
                "permissionDecisionReason": "Write only this run's report.md or checklist.md",
            }
        }
    return {}

options = ClaudeAgentOptions(
    model="claude-opus-5-5",
    cwd=str(WORKSPACE),
    max_turns=40,
    max_budget_usd=3.0,
    setting_sources=[],
    strict_mcp_config=True,
    hooks={"PreToolUse": [HookMatcher(matcher="Write|Edit", hooks=[guard_output_paths])]},
    tools=["Read", "Glob", "Grep", "Write"],  # the only built-in tools the agent sees
    allowed_tools=["Read", "Glob", "Grep", "Write"],  # these run without a prompt
    permission_mode="acceptEdits",  # file edits are approved automatically
)


async def main():
    print(f"Output directory: {OUTPUT_DIR}")
    async for message in query(prompt=TASK, options=options):
        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}, error: {message.is_error}, cost USD: {message.total_cost_usd}")


asyncio.run(main())

כלים והרשאות: מה מותר לסוכן לעשות לבד?

allowed_tools מאשר מראש כלים, כך שהם רצים בלי לעצור לאישור. הוא לא מגביל את הסוכן רק אליהם: כלי שלא ברשימה עובר למצב ההרשאות. כדי לחסום כלי משתמשים ב־disallowed_tools, שמוציא אותו מההקשר של המודל לגמרי Python SDK reference (נפתח בחלון חדש). האפשרות tools עובדת מהכיוון ההפוך: היא קובעת אילו כלים מובנים המודל רואה בכלל, וכל כלי מובנה אחר לא קיים מבחינתו. כלים מותאמים דרך MCP לא מושפעים ממנה.

permission_mode קובע כמה פיקוח אנושי נשאר. התחילו בצירוף הצר ביותר שמאפשר לבצע את המשימה, והרחיבו רק אחרי שראיתם הרצות תקינות.

כותבים לסוכן תדריך, לא בקשה

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

שימו לב לשורה שמחייבת רשימת משימות ב־checklist.md. הקוד בהמשך קורא אותה כדי להחליט אם להמשיך. שימו לב: הרשימה היא דיווח של הסוכן עצמו, ולכן את הדוח הסופי עדיין צריך לבדוק מול נתוני הקלט. את התדריך כדאי לכתוב באנגלית, כמו בדוגמה, או בעברית מלאה; העיקר שהגדרת הסיום תהיה מדידה. שמרו את WORKSPACE, OUTPUT_DIR, REPORT, CHECKLIST ואת guard_output_paths מהדוגמה הראשונה; התדריך משתמש באותם נתיבים. שמירת הקבצים בתיקייה חדשה מונעת מדוח ישן להיחשב לתוצאה של הרצה חדשה.

BRIEF = f"""You prepare a monthly sales report for a small business.

Goal: create {REPORT} from the CSV files in ./exports.

Done means:
- {REPORT} exists and has one row per month found in the data.
- Every monthly total equals the sum of the matching CSV rows.
- {CHECKLIST} has no unchecked items.

Rules:
- Read inputs only inside ./exports; you may also read {REPORT} and {CHECKLIST}. Never delete, move or rename files.
- If a file cannot be parsed, skip it and list it under "Skipped files".
- Keep {CHECKLIST} updated: one "- [ ]" line per part of the task.
- If you are blocked, add a line "BLOCKED: <reason>" to {CHECKLIST}.
- Do not end a turn with a plan for the next step. Take the step.
- Stop and ask only when you cannot continue without the user."""


options = ClaudeAgentOptions(
    model="claude-opus-5-5",
    cwd=str(WORKSPACE),
    max_turns=40,
    max_budget_usd=3.0,
    setting_sources=[],
    strict_mcp_config=True,
    hooks={"PreToolUse": [HookMatcher(matcher="Write|Edit", hooks=[guard_output_paths])]},
    system_prompt=BRIEF,
    tools=["Read", "Glob", "Grep", "Write", "Edit"],
    allowed_tools=["Read", "Glob", "Grep", "Write", "Edit"],
    permission_mode="acceptEdits",
)

מוסיפים כלי משלכם: חיבור ל־CRM

כלי מותאם מוגדר בדקורטור @tool עם 4 רכיבים: שם, תיאור, סכמת קלט ופונקציה אסינכרונית. עוטפים אותו בשרת MCP שרץ בתוך התהליך עם create_sdk_mcp_server, ומעבירים את השרת ב־mcp_servers Custom tools (נפתח בחלון חדש).

שם הכלי מול המודל בנוי מהתבנית mcp__<server>__<tool>, ולכן ברשימת ההרשאות הוא מופיע כ־mcp__crm__lookup_customer. כשהכלי נכשל, החזירו "is_error": True עם הודעה ברורה. כך המודל מבין שהקריאה נכשלה ויכול לנסות דרך אחרת, במקום לקבל חריגה גולמית.

from typing import Any
from claude_agent_sdk import tool, create_sdk_mcp_server, ClaudeAgentOptions

# Stand-in for your CRM export; replace with a real lookup
CUSTOMERS = {"C-1001": "Cohen Ltd", "C-1002": "Levi Bakery"}


@tool(
    "lookup_customer",
    "Return the customer name for a customer ID from the CRM",
    {"customer_id": str},
)
async def lookup_customer(args: dict[str, Any]) -> dict[str, Any]:
    name = CUSTOMERS.get(args["customer_id"])
    if name is None:
        # is_error tells the model the call failed, so it can react
        return {
            "content": [{"type": "text", "text": f"Unknown ID {args['customer_id']}"}],
            "is_error": True,
        }
    return {"content": [{"type": "text", "text": name}]}


crm = create_sdk_mcp_server(name="crm", version="1.0.0", tools=[lookup_customer])

options = ClaudeAgentOptions(
    model="claude-opus-5-5",
    cwd=str(WORKSPACE),
    max_turns=40,
    max_budget_usd=3.0,
    setting_sources=[],
    strict_mcp_config=True,
    hooks={"PreToolUse": [HookMatcher(matcher="Write|Edit", hooks=[guard_output_paths])]},
    system_prompt=BRIEF,
    mcp_servers={"crm": crm},
    tools=["Read", "Glob", "Grep", "Write", "Edit"],
    allowed_tools=["Read", "Glob", "Grep", "Write", "Edit", "mcp__crm__lookup_customer"],
    permission_mode="acceptEdits",
)

למה הסוכן עוצר באמצע ומודיע מה יעשה בהמשך?

זו התופעה שהכי מבלבלת בסוכן הראשון. לפי מדריך הפרומפטים של Anthropic ל־Opus 5.5 (נפתח בחלון חדש), במשימות ארוכות המודל מעדכן את המשתמש תוך כדי עבודה, וחלק מהעדכונים מסיימים את התור בטקסט במקום בקריאה לכלי (stop_reason: "end_turn"). לולאה שמתייחסת לתור כזה כסוף המשימה פשוט נעצרת.

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

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

בדיקת הסיום קוראת רק את קובצי ההרצה הנוכחית, ודורשת report.md שהוא קובץ רגיל ולא ריק. דוח ישן, תיקייה בשם report.md או קובץ ריק לא נחשבים לפלט. אם לא מתקבל ResultMessage תקין, או שהתור נקטע, עוצרים לבדיקה אנושית בלי תזכורת נוספת. הבדיקה הזאת אינה מאמתת את הסכומים; אותם בודקים מול ה-CSV.

import asyncio
from claude_agent_sdk import ClaudeSDKClient, ResultMessage

MAX_NUDGES = 2  # Anthropic suggests stopping after 2 or 3 automatic continuations


def open_items() -> list[str]:
    path = CHECKLIST
    if path.is_symlink() or not path.is_file():
        return ["This run has no regular checklist.md file"]
    lines = path.read_text(encoding="utf-8").splitlines()
    if not any(line.startswith(("- [ ] ", "- [x] ")) for line in lines):
        return ["checklist.md has no task lines"]
    items = [line[6:] for line in lines if line.startswith("- [ ] ")]
    if REPORT.is_symlink() or not REPORT.is_file() or not REPORT.read_text(encoding="utf-8").strip():
        items.append("This run has no nonempty regular report.md file")
    return items


def blockers() -> list[str]:
    path = CHECKLIST
    lines = path.read_text(encoding="utf-8").splitlines() if path.is_file() and not path.is_symlink() else []
    return [line for line in lines if line.startswith("BLOCKED:")]


async def main():
    print(f"Output directory for this run: {OUTPUT_DIR}")
    print(f"Limits: max_turns={options.max_turns}, max_budget_usd={options.max_budget_usd}")
    async with ClaudeSDKClient(options=options) as client:
        await client.query(TASK)
        for attempt in range(MAX_NUDGES + 1):
            final = None
            async for message in client.receive_response():
                if isinstance(message, ResultMessage):
                    print(f"Turn ended: {message.subtype}, error: {message.is_error}, cost USD: {message.total_cost_usd}")
                    print(message.result or "")  # the agent's own report
                    final = message
            failed = (final is None or final.is_error or final.subtype != "success"
                      or getattr(final, "terminal_reason", None) not in (None, "completed")
                      or getattr(final, "stop_reason", None) == "refusal")
            if failed:
                print("Stopped for human review: missing, failed or interrupted result")
            remaining = open_items()
            if failed or blockers() or not remaining or attempt == MAX_NUDGES:
                break  # an error or a stated blocker goes to a human
            await client.query(
                "Your checklist still has open items: " + "; ".join(remaining)
                + ". Continue with them. If one is blocked, say what is blocking it."
            )
        print("Open items left:", open_items() or "none")
        print("Blockers:", blockers() or "none")
        print("Review the report totals against the CSV data before using it.")

asyncio.run(main())

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

3 הגדרות ב־ClaudeAgentOptions עוצרות הרצה שיצאה משליטה. max_turns מגביל את מספר סבבי הכלים לכל הודעת משתמש. כל תזכורת מתחילה מונה סבבים חדש, ולכן 40 אינו גבול לכל הסקריפט. מספר ההמשכים מוגבל בנפרד, והתקציב מצטבר באותו ClaudeSDKClient. סבבים ותקציב (נפתח בחלון חדש). max_budget_usd עוצר כשהערכת העלות בצד הלקוח מגיעה לסכום שקבעתם. disallowed_tools מוציא כלים מסוכנים מההקשר Python SDK reference (נפתח בחלון חדש).

שכבה רביעית היא hook מסוג PreToolUse, שרץ לפני כל קריאה לכלי ויכול לדחות אותה עם סיבה. הוא רץ גם על כלים שאושרו מראש. בדוגמה הוא מגביל Write ו-Edit לנתיבים המדויקים REPORT ו-CHECKLIST של ההרצה הנוכחית, אחרי פתרון הנתיב, ודוחה קישור סמלי. סיומת .md לבדה אינה מגבלה מספקת, כי גם ../../unrelated.md עומד בה. ה-hook אינו sandbox ואינו מגביל קריאה או כלי MCP מותאמים; מריצים על עותקי נתונים בתיקייה מבודדת וללא מידע רגיש. setting_sources=[] מבטל טעינת הגדרות משתמש, פרויקט ומחשב מקומיות, אך אינו מבטל מדיניות ארגונית מנוהלת. תיעוד SDK (נפתח בחלון חדש).

להרצת הדוגמה המלאה השתמשו בקובץ להורדה: הוא כולל את הנתיבים הייחודיים, TASK, התדריך, כלי ה-CRM, ה-hook, options וה-main עם קריאה אחת ל-asyncio.run(main()). קטעי options בהמשך המדריך מחליפים את הקודמים, ושומרים על המגבלות מהדוגמה הראשונה. אין לחבר שתי פונקציות main או שתי קריאות הרצה.

הרצנו את הגרסה המקורית של הקובץ המלא ב־5 באוקטובר 2026 עם claude-agent-sdk 0.2.163 על 2 קובצי CSV לדוגמה (7 שורות מכירה). הסוכן סיים בתור אחד בלי תזכורת, הסכומים החודשיים תאמו את הנתונים, הוא זיהה נכון תיקו בין 2 לקוחות, והעלות המדווחת הייתה כ־0.06 דולר. בבדיקה נפרדת ה־hook חסם ניסיון לכתוב notes.txt, והכלי החזיר למודל שגיאה על מזהה לקוח שלא קיים. תיקוני הנתיבים, בדיקת הסיום והמגבלות בדוגמאות הביניים נבדקו ברגרסיה מקומית עם תגובות מדומות, ללא קריאות API חדשות. העלות המתועדת מתייחסת להרצה המקורית בלבד.

בהרצה הראשונה, לפני שהוספנו setting_sources=[], הסוכן ירש עשרות כלים מהתקנת Claude Code במחשב, וההקשר המנופח הוציא את כל התקציב לפני שהתחילה עבודה. התוצאה עצרה על error_max_budget_usd, כלומר התקרה עשתה את שלה.

max_budget_usd נשען על אומדן מקומי, לא על תקרת חיוב מובטחת. לאורך המשכי ClaudeSDKClient באותו תהליך קוראים את total_cost_usd האחרון כעלות מצטברת, ולא מחברים אותו לתוצאות הקודמות. את החיוב בפועל בודקים ב-Console. מעקב עלויות (נפתח בחלון חדש).

הפרדת הגדרות אינה בידוד מלא: setting_sources=[] לא מבטל את כל מקורות ההקשר, כגון זיכרון אוטומטי והגדרות גלובליות ב-~/.claude.json. לכן מוסיפים strict_mcp_config=True כדי לטעון רק את שרתי ה-MCP שמוגדרים בקוד. להגבלת קבצים ורשת משתמשים בסביבה מבודדת, לא באפשרות הזאת. מה setting_sources אינו שולט בו (נפתח בחלון חדש).

• הסוכן רץ על עותק של הנתונים, לא על המקור.
• יש תקרת סבבים ותקרת עלות. ההרצה מדפיסה אותן בהתחלה, ואם אחת נפרצת ה־subtype הוא error_max_turns או error_max_budget_usd.
• Bash ו־WebFetch חסומים עד שיש להם סיבה עסקית.
• כל פעולה שאי אפשר לבטל דורשת אישור אנושי, גם כשההוראה שמונעת עצירות פעילה.

from typing import Any
from claude_agent_sdk import ClaudeAgentOptions, HookMatcher, HookContext

async def guard_output_paths(
    input_data: dict[str, Any], tool_use_id: str | None, context: HookContext
) -> dict[str, Any]:
    if input_data["tool_name"] not in ("Write", "Edit"):
        return {}
    raw = input_data["tool_input"].get("file_path") or ""
    path = Path(raw)
    if not path.is_absolute():
        path = WORKSPACE / path
    allowed = {REPORT, CHECKLIST}
    if not raw or path.is_symlink() or path.resolve() not in allowed:
        return {
            "hookSpecificOutput": {
                "hookEventName": "PreToolUse",
                "permissionDecision": "deny",
                "permissionDecisionReason": "Write only this run's report.md or checklist.md",
            }
        }
    return {}

options = ClaudeAgentOptions(
    model="claude-opus-5-5",
    cwd=str(WORKSPACE),
    system_prompt=BRIEF,
    mcp_servers={"crm": crm},  # the custom tool from the previous section
    tools=["Read", "Glob", "Grep", "Write", "Edit"],  # the only built-ins the agent sees
    allowed_tools=["Read", "Glob", "Grep", "Write", "Edit", "mcp__crm__lookup_customer"],
    disallowed_tools=["Bash", "WebFetch"],  # removed from the agent's context
    permission_mode="acceptEdits",
    max_turns=40,  # tool-use round trips per user message, including each nudge
    max_budget_usd=3.0,  # cumulative estimated spend across this client run
    effort="medium",  # the default on Opus 5.5, set explicitly so it is visible
    setting_sources=[],  # skip user/project/local filesystem settings
    strict_mcp_config=True,  # only the explicitly configured MCP servers
    hooks={"PreToolUse": [HookMatcher(matcher="Write|Edit", hooks=[guard_output_paths])]},
)

כמה עולה להריץ סוכן על Claude Opus 5.5?

Claude Opus 5.5 מתומחר ב־4 דולר למיליון טוקני קלט וב־20 דולר למיליון טוקני פלט, לעומת 5 ו־25 דולר ב־Opus 5. קריאה מהמטמון עולה 0.20 דולר למיליון טוקנים, ועיבוד באצווה בחצי מחיר What's new in Claude Opus 5.5 (נפתח בחלון חדש).

לפי Anthropic, בהגדרות ברירת המחדל המודל עולה כ־40% פחות מ־Opus 5 בעומסי עבודה טיפוסיים ומייצר פלט מהר יותר מ־Opus 5, בפער של יותר מ־30% Introducing Claude Opus 5.5 (נפתח בחלון חדש). בטבלת ההכרזה הוא קיבל 66.4% ב־Terminal-Bench 4.0 (ברמת effort מסוג xhigh) ו־81.8% בציון החלקי (partial) של OSWorld 2.1. עם זאת, Anthropic עצמה מציינת שבפועל הפער בינו לבין Claude Fable 5.1 צר יותר ממה שהמספרים מרמזים.

רמת ה־effort המוגדרת כברירת מחדל ב־Opus 5.5 היא medium, ובאותה רמה המודל נוטה לחשוב יותר בכל תור מ־Opus 5. אל תעתיקו הגדרה ממודל קודם: הריצו את אותה משימה ב־2 רמות והשוו עלות ותוצאה.

טעויות נפוצות בסוכן הראשון

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

• הנחה ש־allowed_tools חוסם כלים אחרים. הוא רק מאשר מראש; חסימה נעשית ב־disallowed_tools.
• קריאת התוכן לפי מיקום. ב־Opus 5.5 תשובה יכולה להתחיל בבלוק thinking, לכן בודקים את סוג הבלוק.
• הגדרת thinking כ־disabled. ב־Opus 5.5 זה מחזיר שגיאת 400; שולטים בעומק דרך effort.
• שימוש ב־tool_choice מסוג any או tool כדי לכפות קריאה לכלי. ב־Opus 5.5 זה לא נתמך; כותבים בפרומפט מתי הכלי רלוונטי.
• שינוי התדריך באמצע סשן. זה מבטל את בלוקי החשיבה הקודמים; עדיף להוסיף הודעות ולא לשנות את מה שכבר נשלח, או להתחיל סשן חדש.
• הנחה ש-setting_sources=[] מבודד את כל סביבת Claude Code. הוא מבטל מקורות הגדרות מסוימים בלבד. strict_mcp_config=True מצמצם MCP לשרתים המוגדרים בקוד, וסביבה מבודדת מגבילה גישה לקבצים ולרשת.

שאלות נפוצות

בשורה התחתונה

אלה הנקודות שכדאי לקחת מהמדריך לסוכן הראשון שלכם:

• סוכן הוא לולאה: מודל, כלים, תוצאות, החלטה. האמינות נקבעת בלולאה, לא רק במודל.
• משימה ראשונה צריכה להיות מייגעת, הפיכה וניתנת לבדיקה.
• תדריך עם הגדרת ״גמור״ מדידה ורשימת משימות יכול לצמצם עצירות מוקדמות.
• סיום תור בטקסט הוא דיווח. בדקו את הרשימה ושלחו עד 2 או 3 תזכורות.
• max_turns, max_budget_usd, tools, setting_sources ו־hook לפני כל עבודה אמיתית.