7.3 Agent SDK הרצאה

בהרצאה הקודמת בנינו לולאת tools בעצמנו: המודל ביקש קריאה, אנחנו הרצנו, החזרנו תוצאה, וחזרנו על זה עד שהמודל סיים. זה עבד, אבל שמנו לב לכמה דברים - היינו צריכים לכתוב את הלולאה, לנהל את היסטוריית ההודעות, לממש כל tool בעצמנו (קריאת קבצים, הרצת פקודות, חיפוש). מה אם כל זה כבר היה מוכן? זו בדיוק המטרה של ה-Agent SDK של Claude: הוא נותן לנו את אותו מנוע שמפעיל את Claude Code - אותם tools מובנים, אותה לולאת agent, אותו ניהול הcontext - כספרייה שאפשר להפעיל מקוד פייתון או TypeScript.

בהרצאה הזו נבין מה ה-Agent SDK נותן מעל קריאות API רגילות, נכיר את הפונקציה המרכזית שלו, ונבנה agent מינימלי שקורא קבצים, מריץ פקודות ופותר משימה בעצמו.

מהו ה-Agent SDK - the Agent SDK¶

חשוב להבחין בין שני דברים שנשמעים דומים:

ה-Client SDK (anthropic / @anthropic-ai/sdk) - זה מה שהשתמשנו בו עד עכשיו. הוא נותן גישה ישירה ל-API. אנחנו כותבים את לולאת הtools ומממשים כל tool.
ה-Agent SDK (claude-agent-sdk / @anthropic-ai/claude-agent-sdk) - זה Claude Code ארוז כספרייה. הוא מגיע עם tools מובנים, עם לולאת הagent המלאה, עם ניהול context, hooks, sub-agents, הרשאות וסשנים. אנחנו רק קוראים ל-query(prompt, options) והוא מנהל הכל.

ההבדל במשפט אחד: עם ה-Client SDK אתה כותב את לולאת הtools; עם ה-Agent SDK Claude מנהל אותה בעצמו, עם tools שכבר קיימים.

# Client SDK: you implement the tool loop
response = client.messages.create(...)
while response.stop_reason == "tool_use":
    result = your_tool_executor(response.content)
    response = client.messages.create(...)

# Agent SDK: Claude manages the tools autonomously
async for message in query(prompt="תקן את הבאג ב-auth.py"):
    print(message)

התקנה והגדרה - installation¶

מתקינים את ה-SDK. בפייתון (דורש Python 3.10 ומעלה):

pip install claude-agent-sdk

וב-TypeScript:

npm install @anthropic-ai/claude-agent-sdk

ההזדהות זהה למה שראינו - משתנה סביבה עם מפתח API:

export ANTHROPIC_API_KEY="sk-ant-..."

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

הagent הראשון - the first agent¶

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

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
    async for message in query(
        prompt="אילו קבצים יש בתיקייה הזאת?",
        options=ClaudeAgentOptions(allowed_tools=["Bash", "Glob"]),
    ):
        if hasattr(message, "result"):
            print(message.result)


asyncio.run(main())

מה קרה כאן? נתנו ל-query prompt במחרוזת, ורשימת הtools שהagent רשאי להשתמש בהם דרך allowed_tools. הagent קיבל את המשימה, החליט בעצמו להשתמש ב-Glob וב-Bash, סרק את התיקייה, וחזר עם תשובה - בלי שכתבנו לולאת tools ובלי שמימשנו את הtools. הפונקציה query היא אסינכרונית ומחזירה זרם הודעות (async iterator), ולכן היא רצה בתוך async def ועם asyncio.run.

אותו agent ב-TypeScript:

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

for await (const message of query({
  prompt: "אילו קבצים יש בתיקייה הזאת?",
  options: { allowedTools: ["Bash", "Glob"] },
})) {
  if ("result" in message) console.log(message.result);
}

שימו לב שב-TypeScript שם השדה הוא allowedTools (camelCase), בעוד שבפייתון הוא allowed_tools (snake_case) - זה ההבדל המוסכם בין השפות.

הtools המובנים - built-in tools¶

הכוח האמיתי של ה-Agent SDK הוא סט הtools שמגיע מובנה. אלה בדיוק הtools שמפעילים את Claude Code:

tool	מה הוא עושה
`Read`	קריאת קובץ מהתיקייה
`Write`	יצירת קובץ חדש
`Edit`	עריכה מדויקת של קובץ קיים
`Bash`	הרצת פקודות מעטפת, סקריפטים, git
`Glob`	מציאת קבצים לפי תבנית (`*/.py`)
`Grep`	חיפוש בתוכן קבצים עם regex
`WebSearch`	חיפוש באינטרנט למידע עדכני
`WebFetch`	הבאת תוכן של דף אינטרנט וניתוחו

בזכות הtools האלה, הagent יכול לקרוא קוד, לערוך אותו, להריץ בדיקות ולחפש מידע - מיד, בלי שנממש כלום. הנה agent שמחפש הערות TODO בקוד ומסכם אותן:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
    async for message in query(
        prompt="מצא את כל הערות ה-TODO בקוד וצור סיכום",
        options=ClaudeAgentOptions(allowed_tools=["Read", "Glob", "Grep"]),
    ):
        if hasattr(message, "result"):
            print(message.result)


asyncio.run(main())

שליטה בהרשאות - permissions¶

השדה allowed_tools הוא גם מנגנון האבטחה שלנו. הוא קובע אילו tools מאושרים מראש. אם נבנה agent שרק מנתח קוד ולא משנה אותו, ניתן לו רק tools לקריאה:

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Glob", "Grep"],   # read-only - no Write/Edit/Bash
)

כך אנחנו שולטים בדיוק במה שהagent יכול לעשות. יש גם permission_mode שקובע כמה הagent צריך לבקש אישור - למשל "acceptEdits" כדי לאשר אוטומטית עריכות קבצים. עבור פעולות רגישות, ה-SDK יכול לעצור ולבקש אישור אנושי לפני הביצוע.

יכולות מתקדמות - advanced capabilities¶

מעבר לtools המובנים, ה-Agent SDK מביא כמה יכולות חזקות שהיינו צריכים לבנות בעצמנו:

חיבור לשרתי MCP - אפשר לחבר את הagent למערכות חיצוניות (בסיסי נתונים, דפדפנים, API) דרך פרוטוקול MCP (נלמד עליו בהרצאה הבאה):

options = ClaudeAgentOptions(
    mcp_servers={
        "playwright": {"command": "npx", "args": ["@playwright/mcp@latest"]}
    }
)

sub-agents - הagent הראשי יכול להאציל משימות ממוקדות לsub-agents מיוחדים, שמדווחים בחזרה עם תוצאות. שימושי לפירוק עבודה מקבילית.

סשנים - שמירת context בין קריאות. הagent זוכר קבצים שקרא וניתוח שביצע. אפשר לתפוס את מזהה הסשן מהקריאה הראשונה ולהמשיך אותו מאוחר יותר:

options = ClaudeAgentOptions(resume=session_id)

hooks - הרצת קוד מותאם בנקודות מפתח במחזור החיים של הagent, למשל רישום כל שינוי בקובץ ל-audit log דרך ה-hook בשם PostToolUse.

מתי להשתמש במה - when to use what¶

יש כמה דרכים לבנות עם Claude, וכדאי לדעת מתי כל אחת מתאימה:

אתה רוצה...	השתמש ב...
שליחת בקשה בודדת, סיווג, סיכום	Client SDK (קריאת API)
לולאת tools עם tools משלך, בשליטה מלאה	Client SDK + מריץ הtools
הagent שעובד על קבצים ופקודות בתשתית שלך	Agent SDK
הagent מנוהל שאנתרופיק מריצה בתשתית שלה	Managed Agents (שירות מנוהל)

ה-Agent SDK מבריק כשאתה רוצה agent קוד/מערכת-קבצים "עם סוללות כלולות" שרץ בתהליך ובתשתית שלך. אם אתה רק צריך קריאת API אחת - ה-Client SDK פשוט יותר. אם אתה לא רוצה לתחזק את התשתית בכלל - Managed Agents. דרך נפוצה היא לאב-טיפוס עם ה-Agent SDK מקומית, ואז לעבור ל-Managed Agents לייצור.

דוגמה מלאה - a bug-fixing agent¶

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

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
    async for message in query(
        prompt="מצא ותקן את הבאג ב-calculator.py, ואז הרץ את הבדיקות כדי לוודא.",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Bash", "Glob", "Grep"],
        ),
    ):
        # print every message to watch the agent think and act
        print(message)


asyncio.run(main())

בהרצה, נראה את הagent קורא את הקובץ, מזהה את השורה הבעייתית, עורך אותה, מריץ את הבדיקות, ואם משהו נכשל - מנסה שוב. כל הלולאה הזו, שבנינו ידנית בהרצאה הקודמת, מנוהלת עכשיו לגמרי על ידי ה-SDK.

סוגי ההודעות - message types¶

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

הודעת אתחול (init) - נשלחת בתחילת הסשן ומכילה מטא-נתונים, כמו session_id.
הודעות ביניים - טקסט שהמודל מייצר, קריאות לtools ותוצאותיהן.
הודעת תוצאה (result) - התוצאה הסופית של המשימה.

אפשר לסנן לפי הסוג. למשל, לתפוס את מזהה הסשן מהודעת האתחול, כדי להמשיך אותו אחר כך:

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


async def main():
    session_id = None

    # first query - capture the session id
    async for message in query(
        prompt="קרא את מודול האימות",
        options=ClaudeAgentOptions(allowed_tools=["Read", "Glob"]),
    ):
        if isinstance(message, SystemMessage) and message.subtype == "init":
            session_id = message.data["session_id"]

    # continue with the full context of the first query
    async for message in query(
        prompt="עכשיו מצא את כל המקומות שקוראים לו",
        options=ClaudeAgentOptions(resume=session_id),
    ):
        if isinstance(message, ResultMessage):
            print(message.result)


asyncio.run(main())

בשאילתה השנייה, המילה "לו" מתייחסת למודול האימות מהשאילתה הראשונה - כי המשכנו את אותו סשן דרך resume. הagent זוכר מה קרא ומה ניתח.

Sub-agents¶

יכולת חזקה נוספת היא sub-agents: הagent הראשי מאציל משימות ממוקדות לagents מיוחדים, שמדווחים בחזרה. מגדירים אותם דרך agents, ומוסיפים Agent ל-allowed_tools כדי לאשר את ההפעלה:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition


async def main():
    async for message in query(
        prompt="השתמש בסוכן code-reviewer כדי לבקר את הקוד",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep", "Agent"],
            agents={
                "code-reviewer": AgentDefinition(
                    description="Expert code reviewer for quality and security.",
                    prompt="נתח איכות קוד והצע שיפורים.",
                    tools=["Read", "Glob", "Grep"],
                )
            },
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)


asyncio.run(main())

לכל sub-agent יש context משלו, tools משלו וprompts משלו. זה שימושי לפירוק עבודה מקבילית - למשל, agent אחד סורק קבצים וsub-agent אחר מבקר אותם - וגם לחיסכון בcontext, כי כל sub-agent מתמקד במשימה שלו.

הגדרות מבוססות קבצים - filesystem config¶

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

יכולת	תיאור	מיקום
Skills	יכולות מיוחדות שהמודל טוען לפי הצורך	`.claude/skills/*/SKILL.md`
זיכרון - memory	context וprompts לפרויקט	`CLAUDE.md`
תוספים - plugins	הרחבות עם tools, agents ו-hooks	דרך אפשרות `plugins`

זה אומר שאותן skills וprompts שמגדירים ל-Claude Code זמינות אוטומטית גם לagent שבונים ב-SDK. אם רוצים להגביל אילו מקורות נטענים, מגדירים setting_sources באפשרויות.

סיכום¶

בהרצאה הזו הכרנו את ה-Agent SDK - הדרך לבנות agent שלם בלי לכתוב את הלולאה בעצמנו:

ה-Agent SDK (claude-agent-sdk בפייתון, @anthropic-ai/claude-agent-sdk ב-npm) הוא Claude Code ארוז כספרייה: tools מובנים, לולאת agent, ניהול context, הרשאות וסשנים.
ההבדל מה-Client SDK: שם אנחנו כותבים את לולאת הtools ומממשים tools; כאן Claude מנהל את הלולאה עם tools מוכנים.
הפונקציה המרכזית היא query(prompt, options), וההגדרות עוברות דרך ClaudeAgentOptions (פייתון) או אובייקט options (TypeScript). היא אסינכרונית ומחזירה זרם הודעות.
הtools המובנים - Read, Write, Edit, Bash, Glob, Grep, WebSearch, WebFetch - נותנים לagent יכולת לפעול מיד, בלי מימוש.
הרשאות נשלטות דרך allowed_tools: נותנים רק את הtools הדרושים, ומשתמשים ב-permission_mode לאישורים.
יכולות מתקדמות: חיבור לשרתי MCP, sub-agents, סשנים ו-hooks.
בחירה נכונה: קריאת API בודדת - Client SDK; agent על תשתית שלך - Agent SDK; agent מנוהל - Managed Agents.

בהרצאה הבאה נסגור את המעגל - נלמד לבנות שרת MCP משלנו, שחושף tool מותאם אישית שאפשר לחבר גם ל-Agent SDK, גם ל-Claude Code, וגם לכל מארח MCP אחר.