مهاجرت به Claude Agent SDK

این یک ترجمهٔ غیررسمی از مستندات Claude Code است که توسط مسیر تهیه شده. نسخهٔ مرجع و معتبر، مستندات رسمی انگلیسی است.

مرورِ کلی

Claude Code SDK به Claude Agent SDK تغییرِ نام داده و مستنداتش بازسازماندهی شده است. این تغییر بازتابِ قابلیت‌های گسترده‌ترِ SDK برای ساختنِ ایجنت‌های AI فراتر از صرفِ کارهای کدنویسی است.

چه چیزی عوض شده

جنبه	قدیم	جدید
نامِ پکیج (TS/JS)	@anthropic-ai/claude-code	@anthropic-ai/claude-agent-sdk
پکیجِ Python	claude-code-sdk	claude-agent-sdk
مکانِ مستندات	مستنداتِ Claude Code	API Guide → بخشِ Agent SDK

یادداشت

تغییراتِ مستندات: مستنداتِ Agent SDK از مستنداتِ Claude Code به API Guide زیرِ یک بخشِ اختصاصیِ Agent SDK منتقل شده است. مستنداتِ Claude Code اکنون روی ابزارِ CLI و قابلیت‌های automation تمرکز دارد.

گام‌های مهاجرت

برای پروژه‌های TypeScript/JavaScript

۱. پکیجِ قدیمی را حذف کن:

npm uninstall @anthropic-ai/claude-code

۲. پکیجِ جدید را نصب کن:

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

۳. importهایت را به‌روز کن:

همه‌ی importها را از @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";

۴. وابستگی‌های package.json را به‌روز کن:

اگر پکیج را در package.jsonِ خودت فهرست کرده‌ای، آن را به‌روز کن:

قبل:

{
  "dependencies": {
    "@anthropic-ai/claude-code": "^0.0.42"
  }
}

بعد:

{
  "dependencies": {
    "@anthropic-ai/claude-agent-sdk": "^0.2.0"
  }
}

۵. تغییراتِ ناسازگار (breaking changes) را مرور کن

هر تغییرِ کدی که برای تکمیلِ مهاجرت لازم است انجام بده.

برای پروژه‌های Python

۱. پکیجِ قدیمی را حذف کن:

pip uninstall claude-code-sdk

۲. پکیجِ جدید را نصب کن:

pip install claude-agent-sdk

۳. importهایت را به‌روز کن:

همه‌ی importها را از claude_code_sdk به claude_agent_sdk تغییر بده:

# Before
from claude_code_sdk import query, ClaudeCodeOptions

# After
from claude_agent_sdk import query, ClaudeAgentOptions

۴. نام‌های type را به‌روز کن:

مقدارِ ClaudeCodeOptions را به ClaudeAgentOptions تغییر بده:

# Before
from claude_code_sdk import query, ClaudeCodeOptions

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

# After
from claude_agent_sdk import query, ClaudeAgentOptions

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

۵. تغییراتِ ناسازگار (breaking changes) را مرور کن

هر تغییرِ کدی که برای تکمیلِ مهاجرت لازم است انجام بده.

تغییراتِ ناسازگار (Breaking changes)

احتیاط

برای بهبودِ جداسازی و پیکربندیِ صریح، Claude Agent SDK نسخه‌ی v0.1.0 تغییراتِ ناسازگاری برای کاربرانی که از Claude Code SDK مهاجرت می‌کنند معرفی می‌کند. پیش از مهاجرت این بخش را با دقت مرور کن.

Python: تغییرِ نامِ ClaudeCodeOptions به ClaudeAgentOptions

چه چیزی عوض شد: typeِ 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")

چرا این عوض شد: نامِ type اکنون با برندِ «Claude Agent SDK» جور درمی‌آید و سازگاری را در سراسرِ قراردادهای نام‌گذاریِ SDK فراهم می‌کند.

system prompt دیگر پیش‌فرض نیست

چه چیزی عوض شد: SDK دیگر به‌صورتِ پیش‌فرض از system promptِ Claude Code استفاده نمی‌کند.

مهاجرت:

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"
  }
});

# 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:
from claude_agent_sdk import query, ClaudeAgentOptions

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)

چرا این عوض شد: کنترل و جداسازیِ بهتری برای برنامه‌های SDK فراهم می‌کند. اکنون می‌توانی ایجنت‌هایی با رفتارِ سفارشی بسازی بدونِ اینکه دستورالعمل‌های CLI-محورِ Claude Code را به ارث ببری.

پیش‌فرضِ Settings sources

این پیش‌فرض به‌طورِ مختصر در v0.1.0 عوض شد و سپس بازگردانده شد، پس هیچ اقدامِ مهاجرتی لازم نیست.

رفتارِ کنونی: حذفِ settingSources روی query() تنظیماتِ فایل‌سیستمیِ user، project و local را بارگذاری می‌کند، مطابقِ CLI. این شاملِ ~/.claude/settings.json، .claude/settings.json، .claude/settings.local.json، فایل‌های CLAUDE.md و دستورهای سفارشی است.

برای اجرای جداشده از تنظیماتِ فایل‌سیستم، یک آرایه‌ی خالی پاس بده:

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

const isolatedResult = query({
  prompt: "Hello",
  options: {
    settingSources: [] // No filesystem settings loaded
  }
});

// Or load only specific sources:
const projectOnlyResult = query({
  prompt: "Hello",
  options: {
    settingSources: ["project"] // Only project settings
  }
});

from claude_agent_sdk import query, ClaudeAgentOptions

async for message in query(
    prompt="Hello",
    options=ClaudeAgentOptions(setting_sources=[]),  # No filesystem settings loaded
):
    print(message)

# Or load only specific sources:
async for message in query(
    prompt="Hello",
    options=ClaudeAgentOptions(
        setting_sources=["project"]  # Only project settings
    ),
):
    print(message)

جداسازی به‌ویژه برای pipelineهای CI/CD، برنامه‌های مستقرشده، محیط‌های آزمایش و سیستم‌های چندتننتی اهمیت دارد، جایی که سفارشی‌سازی‌های محلی نباید نشت کنند.

یادداشت

SDK نسخه‌ی v0.1.0 به‌طورِ مختصر به‌صورتِ پیش‌فرض هیچ تنظیماتی بارگذاری نمی‌کرد؛ این در انتشارهای بعدی بازگردانده شد. Python SDK نسخه‌ی 0.1.59 و پایین‌تر یک لیستِ خالی را همانندِ حذفِ گزینه برخورد می‌کردند، پس پیش از تکیه بر setting_sources=[] ارتقا بده. برای ورودی‌هایی که حتی وقتی settingSources برابرِ [] است خوانده می‌شوند، به What settingSources does not control نگاه کن.

چرا تغییرِ نام؟

Claude Code SDK ابتدا برای کارهای کدنویسی طراحی شده بود، اما به یک framework قدرتمند برای ساختنِ همه‌نوع ایجنتِ AI تکامل یافته است. نامِ جدید «Claude Agent SDK» قابلیت‌های آن را بهتر بازتاب می‌دهد:

• ساختنِ ایجنت‌های کسب‌وکار (دستیارهای حقوقی، مشاوران مالی، پشتیبانیِ مشتری)
• خلقِ ایجنت‌های کدنویسیِ تخصصی (باتِ SRE، بازبین‌های امنیتی، ایجنت‌های code review)
• توسعه‌ی ایجنت‌های سفارشی برای هر حوزه با tool use، یکپارچگیِ MCP و بیشتر

دریافتِ کمک

اگر در حینِ مهاجرت با مشکلی برخوردی:

برای TypeScript/JavaScript:

1. بررسی کن همه‌ی importها به استفاده از @anthropic-ai/claude-agent-sdk به‌روز شده‌اند
2. تأیید کن package.jsonِ تو نامِ پکیجِ جدید را دارد
3. برای اطمینان از به‌روزشدنِ وابستگی‌ها npm install را اجرا کن

برای Python:

1. بررسی کن همه‌ی importها به استفاده از claude_agent_sdk به‌روز شده‌اند
2. تأیید کن requirements.txt یا pyproject.tomlِ تو نامِ پکیجِ جدید را دارد
3. برای اطمینان از نصبِ پکیج pip install claude-agent-sdk را اجرا کن

گام‌های بعدی

• مرورِ کلیِ Agent SDK را کاوش کن تا با قابلیت‌های در دسترس آشنا شوی
• مرجعِ TypeScript SDK را برای مستنداتِ تفصیلیِ API ببین
• مرجعِ Python SDK را برای مستنداتِ مخصوصِ Python مرور کن
• درباره‌ی ابزارهای سفارشی و یکپارچگیِ MCP بیاموز