מדריך קלוד קוד בעברית
לאתר הראשי כל המדריכים קלאודפלייר קלוד דסקטופ גרוק CLI גרוק בוט MCP קרסור וואטסאפ OpenClaw n8n בענן n8n בהתקנה עצמית

תיעוד 165

התחלה מהירה

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

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

מה שתעשה:

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

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

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

#הגדרה

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

צור תיקייה חדשה למדריך הזה:

mkdir my-agent
cd my-agent

בפרויקטים שלך אפשר להריץ את ה-SDK מכל תיקייה. כברירת מחדל תהיה לו גישה לקבצים בתיקייה הזו ובתת-התיקיות שלה.

2. התקן את ה-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 ברמה העליונה, ו-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 מהיר שמטפל בסביבות וירטואליות באופן אוטומטי. אחר כך אתחל פרויקט והוסף את ה-SDK:

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 עם שגיאת מדיניות הרצה, הרץ קודם את Set-ExecutionPolicy -Scope Process RemoteSigned.

הערה

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

  • אם pip מתקין את הפצת המקור של ה-SDK של Python במקום wheel של הפלטפורמה, למשל ב-Windows על ARM64, אין קובץ בינארי מובנה. התקן את Claude Code באופן מקומי. ה-SDK של Python מוצא אותו ב-PATH שלך.
  • ה-SDK של TypeScript מתקין את הקובץ הבינארי שלו דרך תלויות אופציונליות של npm, ולכן התקנה שמדלגת עליהן, למשל npm ci --omit=optional, לא מקבלת קובץ בינארי גם בפלטפורמה נתמכת. התקן מחדש בלי לדלג על תלויות אופציונליות, או התקן את Claude Code באופן מקומי והגדר את pathToClaudeCodeExecutable לנתיב שלו.

3. הגדר את מפתח ה-API

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

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.

הערה

אלא אם אושר מראש, 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()

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

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

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

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

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())
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
  }
}

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

  1. query: נקודת הכניסה הראשית שיוצרת את לולאת הסוכן. היא מחזירה איטרטור אסינכרוני, ולכן משתמשים ב-async for כדי להזרים הודעות בזמן ש-Claude עובד. ראה את ה-API המלא בתיעוד ה-SDK של Python או TypeScript.

  2. prompt: מה שאתה רוצה ש-Claude יעשה. Claude קובע באילו כלים להשתמש לפי המשימה.

  3. options: הגדרות לסוכן. הדוגמה הזו משתמשת ב-allowedTools כדי לאשר מראש את Read, Edit ו-Glob, וב-permissionMode: "acceptEdits" כדי לאשר אוטומטית שינויי קבצים. אפשרויות נוספות כוללות את systemPrompt, mcpServers ועוד. ראה את כל האפשרויות ל-Python או ל-TypeScript.

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

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

הערה

הדוגמה הזו משתמשת בהזרמה כדי להציג התקדמות בזמן אמת. אם אין צורך בפלט חי (למשל לעבודות רקע או לצינורות 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. הסוכן שלך, באופן אוטונומי:

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

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

הערה

אם מופיעה שגיאת אימות כמו Not logged in או Invalid API key, ודא שהגדרת את משתנה הסביבה ANTHROPIC_API_KEY במעטפת שבה אתה מריץ את הסוכן. ה-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"

#התאם את הסוכן

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

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

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob", "WebSearch"], permission_mode="acceptEdits"
)
const _ = {
  options: {
    allowedTools: ["Read", "Edit", "Glob", "WebSearch"],
    permissionMode: "acceptEdits"
  }
};

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

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

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

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Edit", "Glob", "Bash"], permission_mode="acceptEdits"
)
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: הרץ קוד מותאם לפני קריאות כלים או אחריהן
  • Sessions: בנה סוכנים מרובי תורות ששומרים על הקשר
  • שרתי MCP: התחבר למסדי נתונים, דפדפנים, API ומערכות חיצוניות אחרות
  • אירוח: פרוס סוכנים ל-Docker, לענן ול-CI/CD
  • סוכנים לדוגמה: ראה דוגמאות מלאות: עוזר דוא"ל, סוכן מחקר ועוד
  • פתרון בעיות: תקן שגיאות כשה-CLI לא מצליח להתחיל או יוצא, או כשמגיעה תוצאה בלי פלט מובנה