📘 תיעוד 125

מעבר אל Claude Agent SDK

מדריך למעבר מ-SDK של Claude Code ב-TypeScript וב-Python אל Claude Agent SDK

#סקירה כללית

השם של Claude Code SDK שונה ל-Claude Agent SDK והתיעוד שלו אורגן מחדש. שינוי זה משקף את היכולות הרחבות יותר של ה-SDK לבניית סוכני AI מעבר למשימות תכנות בלבד.

עוברים במקום זאת מ-OpenAI Agents SDK? מתכון המעבר מ-OpenAI Agents SDK ממפה כל רכיב יסוד אל Claude Agent SDK באמצעות דוגמה מעשית אחת.

#מה השתנה

#שלבי המעבר

#עבור פרויקטים ב-TypeScript/JavaScript

1. הסרת החבילה הישנה:

npm uninstall @anthropic-ai/claude-code

2. התקנת החבילה החדשה:

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

3. עדכון ה-imports שלך:

שנה את כל ה-imports מ-@anthropic-ai/claude-code ל-@anthropic-ai/claude-agent-sdk:

// Before
import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-code";

// After
import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";

4. עדכון package.json:

אם @anthropic-ai/claude-code עדיין מופיע ב-package.json שלך, החלף אותו ב-@anthropic-ai/claude-agent-sdk ועדכן גם את טווח הגרסה, למשל מ-"^0.0.42" ל-"^0.3.0".

5. סקירת שינויים שוברים

בצע את כל שינויי הקוד הנדרשים כדי להשלים את המעבר.

#עבור פרויקטים ב-Python

1. הסרת החבילה הישנה:

pip uninstall -y claude-code-sdk

אם החבילה הישנה אינה מותקנת, pip מדפיס WARNING: Skipping claude-code-sdk as it is not installed. זה צפוי ואפשר להמשיך לשלב הבא.

2. התקנת החבילה החדשה:

pip install claude-agent-sdk

אם claude-code-sdk מופיע ב-requirements.txt או ב-pyproject.toml שלך, החלף אותו ב-claude-agent-sdk.

3. עדכון ה-imports שלך:

שנה את כל ה-imports מ-claude_code_sdk ל-claude_agent_sdk:

# Before
from claude_code_sdk import query, ClaudeCodeOptions

# After
from claude_agent_sdk import query, ClaudeAgentOptions

4. סקירת שינויים שוברים

בצע את כל שינויי הקוד הנדרשים כדי להשלים את המעבר.

#שינויים שוברים

אזהרה: כדי לשפר את הבידוד ואת ההגדרה המפורשת, Claude Agent SDK גרסה v0.1.0 מציגה שינויים שוברים עבור משתמשים שעוברים מ-Claude Code SDK.

#Python: שינוי השם של ClaudeCodeOptions ל-ClaudeAgentOptions

מה השתנה: הטיפוס ClaudeCodeOptions ב-Python SDK שונה לשם ClaudeAgentOptions.

מעבר:

# BEFORE (claude-code-sdk)
from claude_code_sdk import query, ClaudeCodeOptions

options = ClaudeCodeOptions(model="claude-opus-4-7", permission_mode="acceptEdits")

# AFTER (claude-agent-sdk)
from claude_agent_sdk import query, ClaudeAgentOptions

options = ClaudeAgentOptions(model="claude-opus-4-7", permission_mode="acceptEdits")

#שורת הוראות מערכת (system prompt) אינה ברירת מחדל יותר

מה השתנה: ה-SDK אינו משתמש עוד ב-system prompt של Claude Code כברירת מחדל.

מעבר:

#TypeScript

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

// BEFORE (v0.0.x) - Used Claude Code's system prompt by default
const before = query({ prompt: "Hello" });

// AFTER (v0.1.0) - Uses minimal system prompt by default
// To get the old behavior, explicitly request Claude Code's preset:
const presetResult = query({
  prompt: "Hello",
  options: {
    systemPrompt: { type: "preset", preset: "claude_code" }
  }
});

// Or use a custom system prompt:
const customResult = query({
  prompt: "Hello",
  options: {
    systemPrompt: "You are a helpful coding assistant"
  }
});

#Python

from claude_agent_sdk import query, ClaudeAgentOptions
import asyncio


async def main():
    
# BEFORE (v0.0.x) - Used Claude Code's system prompt by default
    async for message in query(prompt="Hello"):
        print(message)

    
# AFTER (v0.1.0) - Uses minimal system prompt by default
    
# To get the old behavior, explicitly request Claude Code's preset:
    async for message in query(
        prompt="Hello",
        options=ClaudeAgentOptions(
            system_prompt={"type": "preset", "preset": "claude_code"}  
# Use the preset
        ),
    ):
        print(message)

    
# Or use a custom system prompt:
    async for message in query(
        prompt="Hello",
        options=ClaudeAgentOptions(system_prompt="You are a helpful coding assistant"),
    ):
        print(message)


asyncio.run(main())

#ברירת מחדל של מקורות הגדרות (settingSources)

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

התנהגות נוכחית: השמטת settingSources ב-query() טוענת את הגדרות המשתמש, הפרויקט ומערכת הקבצים המקומית, בהתאמה להתנהגות ה-CLI. זה כולל את ~/.claude/settings.json, .claude/settings.json, .claude/settings.local.json, קובצי CLAUDE.md ופקודות מותאמות אישית.

כדי להריץ במצב מבודד מהגדרות מערכת הקבצים, העבר settingSources: [], או ב-Python העבר setting_sources=[]. ראה שליטה בהגדרות מערכת הקבצים באמצעות settingSources לפירוט מה שכל מקור טוען.

בידוד חשוב במיוחד עבור תהליכי CI/CD, יישומים בסביבת ייצור, סביבות בדיקה ומערכות מרובות דיירים (multi-tenant) שבהן התאמות אישיות מקומיות לא צריכות לזלוג.

הערה: Python SDK בגרסה 0.1.59 ומטה התייחס לרשימה ריקה באותו אופן כמו השמטת האפשרות, לכן שדרג לפני שתסתמך על setting_sources=[]. ראה על מה settingSources אינו שולט עבור קלטים שנקראים גם כאשר הערך של settingSources הוא [].

#השלבים הבאים

• עיין ב-סקירת Agent SDK כדי ללמוד על התכונות הזמינות.
• בדוק את מדריך ה-API של TypeScript SDK לקבלת תיעוד מפורט של ה-API.
• עיין ב-מדריך ה-API של Python SDK לקבלת תיעוד ספציפי ל-Python.
• למד על כלים מותאמים אישית (Custom Tools) ועל שילוב MCP.