תיעוד 124

התחלה מהירה

התחל לעבוד עם ה-Agent SDK ב-Python או TypeScript כדי לבנות סוכני AI שפועלים באופן עצמאי

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

מה שתעשה:

הגדרת פרויקט עם ה-Agent SDK
יצירת קובץ עם קוד שמכיל באגים
הרצת סוכן שמוצא ומתקן את הבאגים באופן אוטומטי

#דרישות מוקדמות

Node.js 18+ או Python 3.10+
חשבון Anthropic. אם אין לך חשבון, הירשם כאן.

#הגדרה

צור תיקיית פרויקט

צור ספרייה חדשה עבור מדריך התחלה מהירה זה:
```
mkdir my-agent
cd my-agent
```
עבור הפרויקטים שלך, תוכל להריץ את ה-SDK מכל תיקייה, כברירת מחדל תהיה לו גישה לקבצים בספרייה זו ובספריות המשנה שלה.
התקן את ה-SDK

התקן את חבילת ה-Agent SDK עבור שפת הפיתוח שלך:

TypeScript (פרויקט חדש)
```
npm init -y
npm pkg set type=module
npm install @anthropic-ai/claude-agent-sdk
npm install --save-dev tsx
```
הגדרת "type": "module" ב-package.json מאפשרת לסקריפט הסוכן שלך להשתמש ב-await ברמה העליונה (top-level await), ו-tsx מריץ קובצי TypeScript ישירות. npm מדפיס added N packages כאשר ההתקנה מצליחה.

TypeScript (פרויקט קיים)
```
npm install @anthropic-ai/claude-agent-sdk
npm install --save-dev tsx
```
tsx מריץ קובצי TypeScript ישירות. אם הפרויקט שלך משתמש ב-CommonJS, תן לסקריפט הסוכן שלך את השם agent.mts במקום agent.ts. הסיומת .mts גורמת ל-tsx להתייחס לקובץ כאל מודול ES, כך ש-await ברמה העליונה עובד מבלי להמיר את הפרויקט כולו למודולי ES. השתמש ב-agent.mts במקום ב-agent.ts בשלבי היצירה וההרצה בהמשך מדריך התחלה מהירה זה.

Python (uv)

uv הוא מנהל חבילות מהיר ל-Python שמטפל בסביבות וירטואליות באופן אוטומטי:
```
uv init
uv add claude-agent-sdk
```
Python (pip)

צור והפעל סביבה וירטואלית, ולאחר מכן התקן את החבילה.

ב-macOS או Linux:
```
python3 -m venv .venv
source .venv/bin/activate
pip install claude-agent-sdk
```
ב-Windows:
```
py -m venv .venv
.venv\Scripts\Activate.ps1
pip install claude-agent-sdk
```
אם PowerShell חוסם את Activate.ps1 עם שגיאת מדיניות ביצוע (execution policy), הרץ תחילה Set-ExecutionPolicy -Scope Process RemoteSigned.
[!NOTE] שני ה-SDKs של TypeScript ו-Python כוללים קובץ בינארי מקורי של Claude Code, כך שרוב ההתקנות אינן דורשות התקנה נפרדת של Claude Code. בחלק מההתקנות אין קובץ בינארי כלול:
- אם pip מתקין את הפצת המקור (source distribution) של ה-Python SDK במקום wheel של הפלטפורמה, לדוגמה ב-ARM64 Windows, שום קובץ בינארי אינו כלול. התקן את Claude Code באופן מקורי. ה-Python SDK מוצא אותו ב-PATH שלך.
- ה-TypeScript SDK מתקין את הקובץ הבינארי שלו דרך תלויות אופציונליות של npm, ולכן התקנה שמדלגת עליהן, לדוגמה npm ci --omit=optional, אינה מקבלת קובץ בינארי גם בפלטפורמה נתמכת. התקן מחדש מבלי לדלג על תלויות אופציונליות, או התקן את Claude Code באופן מקורי והגדר את pathToClaudeCodeExecutable לנתיב שלו.
הגדר את מפתח ה-API שלך

השג מפתח API מ-Claude Console, ולאחר מכן הגדר אותו כמשתנה סביבה ב-shell שבו תריץ את הסוכן שלך:

macOS / Linux
```
export ANTHROPIC_API_KEY=your-api-key
```
Windows (PowerShell)
```
$env:ANTHROPIC_API_KEY = "your-api-key"
```
ה-SDK קורא את המפתח מהסביבה של התהליך שמריץ את הסוכן שלך, הוא אינו טוען קובצי .env באופן אוטומטי. אם אתה שומר את המפתח בקובץ .env, טען אותו בעצמך, לדוגמה באמצעות חבילת dotenv, לפני הקריאה ל-SDK.

ה-SDK תומך גם באימות באמצעות ספקי API של צד שלישי:
- Amazon Bedrock: הגדר את משתנה הסביבה CLAUDE_CODE_USE_BEDROCK=1 והגדר אישורי AWS
- Claude Platform on AWS: הגדר את CLAUDE_CODE_USE_ANTHROPIC_AWS=1 ואת ANTHROPIC_AWS_WORKSPACE_ID, ולאחר מכן הגדר אישורי AWS
- Google Cloud's Agent Platform: הגדר את משתנה הסביבה CLAUDE_CODE_USE_VERTEX=1 והגדר אישורי Google Cloud
- Microsoft Foundry: הגדר את משתנה הסביבה CLAUDE_CODE_USE_FOUNDRY=1 והגדר אישורי Azure
עיין במדריכי ההגדרה עבור Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform, או Microsoft Foundry לפרטים נוספים.

[!NOTE] אלא אם אושר מראש, Anthropic אינה מתירה למפתחי צד שלישי להציע התחברות דרך claude.ai או מגבלות קצב עבור המוצרים שלהם, כולל סוכנים שנבנו על גבי ה-Claude Agent SDK. אנא השתמש בשיטות אימות מפתח API המתוארות במסמך זה במקום זאת.

#צור קובץ עם באגים

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

def calculate_average(numbers):
    total = 0
    for num in numbers:
        total += num
    return total / len(numbers)


def get_user_name(user):
    return user["name"].upper()

לקוד זה יש שני באגים:

calculate_average([]) קורס עם חלוקה באפס
get_user_name(None) קורס עם TypeError

#בנה סוכן שמוצא ומתקן באגים

צור את agent.py אם אתה משתמש ב-Python SDK, או את agent.ts עבור TypeScript. השתמש ב-agent.mts במקום זאת אם הפרויקט הקיים שלך משתמש ב-CommonJS:

Python

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


async def main():
    
# Agentic loop: streams messages as Claude works
    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"],  
# Auto-approve these tools
            permission_mode="acceptEdits",  
# Auto-approve file edits
        ),
    ):
        
# Print human-readable output
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)  
# Claude's reasoning
                elif hasattr(block, "name"):
                    print(f"Tool: {block.name}")  
# Tool being called
        elif isinstance(message, ResultMessage):
            print(f"Done: {message.subtype}")  
# Final result


asyncio.run(main())

TypeScript

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

// Agentic loop: streams messages as Claude works
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"], // Auto-approve these tools
    permissionMode: "acceptEdits" // Auto-approve file edits
  }
})) {
  // Print human-readable output
  if (message.type === "assistant" && message.message?.content) {
    for (const block of message.message.content) {
      if ("text" in block) {
        console.log(block.text); // Claude's reasoning
      } else if ("name" in block) {
        console.log(`Tool: ${block.name}`); // Tool being called
      }
    }
  } else if (message.type === "result") {
    console.log(`Done: ${message.subtype}`); // Final result
  }
}

לקוד זה יש שלושה חלקים עיקריים:

query: נקודת הכניסה הראשית שיוצרת את הלולאה הסוכנתית. היא מחזירה איטרטור אסינכרוני, כך שאתה משתמש ב-async for כדי להזרים הודעות בזמן ש-Claude עובד. ראה את ה-API המלא בתיעוד ה-SDK של Python או TypeScript.
prompt: מה שאתה רוצה ש-Claude יעשה. Claude מבין באילו כלים להשתמש בהתבסס על המשימה.
options: הגדרות תצורה עבור הסוכן. דוגמה זו משתמשת ב-allowedTools כדי לאשר מראש את Read, Edit ו-Glob, וב-permissionMode: "acceptEdits" כדי לאשר שינויים בקבצים באופן אוטומטי. אפשרויות אחרות כוללות את systemPrompt, mcpServers ועוד. ראה את כל האפשרויות עבור Python או TypeScript.

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

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

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

#הרץ את הסוכן שלך

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

TypeScript

npx tsx agent.ts

אם קראת לסקריפט שלך agent.mts, הרץ npx tsx agent.mts במקום זאת.

Python (uv)

uv run agent.py

Python (pip)

כאשר הסביבה הווירטואלית שלך עדיין מופעלת:

python agent.py

תוך כדי עבודתו, הסוכן מדפיס את תהליך החשיבה שלו ואת כל כלי שהוא מפעיל, ומסיים ב-Done: success. לאחר ההרצה, בדוק את utils.py. תראה קוד הגנתי המטפל ברשימות ריקות ובמשתמשי null. הסוכן שלך ביצע באופן עצמאי:

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

זה מה שמייחד את ה-Agent SDK: Claude מפעיל כלים ישירות במקום לבקש ממך לממש אותם.

[!NOTE] אם אתה רואה שגיאת אימות כגון Not logged in או Invalid API key, ודא שהגדרת את משתנה הסביבה ANTHROPIC_API_KEY ב-shell שבו אתה מריץ את הסוכן שלך. ה-SDK אינו טוען קובצי .env באופן אוטומטי. עיין ב-מדריך פתרון הבעיות המלא לעזרה נוספת.

#נסה הנחיות אחרות

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

"Add docstrings to all functions in utils.py"
"Add type hints to all functions in utils.py"
"Create a README.md documenting the functions in utils.py"

#התאם אישית את הסוכן שלך

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

הוסף יכולת חיפוש באינטרנט:

Python

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob", "WebSearch"], permission_mode="acceptEdits"
)

TypeScript

const _ = {
  options: {
    allowedTools: ["Read", "Edit", "Glob", "WebSearch"],
    permissionMode: "acceptEdits"
  }
};

תן ל-Claude הנחיית מערכת מותאמת אישית:

Python

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob"],
    permission_mode="acceptEdits",
    system_prompt="You are a senior Python developer. Always follow PEP 8 style guidelines.",
)

TypeScript

const _ = {
  options: {
    allowedTools: ["Read", "Edit", "Glob"],
    permissionMode: "acceptEdits",
    systemPrompt: "You are a senior Python developer. Always follow PEP 8 style guidelines."
  }
};

הרץ פקודות בטרמינל:

Python

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob", "Bash"], permission_mode="acceptEdits"
)

TypeScript

const _ = {
  options: {
    allowedTools: ["Read", "Edit", "Glob", "Bash"],
    permissionMode: "acceptEdits"
  }
};

כאשר Bash מופעל, נסה: "Write unit tests for utils.py, run them, and fix any failures"

#מושגי מפתח

כלים קובעים מה הסוכן שלך יכול לעשות:

כלים	מה הסוכן יכול לעשות
`Read`, `Glob`, `Grep`	ניתוח לקריאה בלבד
`Read`, `Edit`, `Glob`	ניתוח ושינוי קוד
`Read`, `Edit`, `Bash`, `Glob`, `Grep`	אוטומציה מלאה

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

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

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

הרשאות: שלוט במה שהסוכן שלך יכול לעשות ומתי הוא זקוק לאישור
Hooks: הרץ קוד מותאם אישית לפני או אחרי קריאות לכלים
הפעלות: בנה סוכנים מרובי פניות (multi-turn) ששומרים על הקשר
שרתי MCP: התחבר למסדי נתונים, דפדפנים, ממשקי API ומערכות חיצוניות אחרות
אירוח: פרוס סוכנים ב-Docker, בענן וב-CI/CD
סוכנים לדוגמה: ראה דוגמאות מלאות: עוזר דוא"ל, סוכן מחקר ועוד
פתרון בעיות: תקן שגיאות של Agent SDK לפי ההודעה המדויקת שמופיעה