دليل مطوري Claude Code SDK: Python وTypeScript

Claude Code SDK — الذي يُسمى رسميًا الآن Claude Agent SDK — هي مكتبة بلغتي Python وTypeScript تتيح لك تشغيل Claude كعامل مستقل داخل تطبيقك الخاص. تقدم له مطالبة (prompt)، ويتولى الباقي: قراءة الملفات، تشغيل الأوامر، تحرير الكود، والتكرار حتى اكتمال المهمة. لا حاجة لكتابة حلقة أدوات (tool loop) أو إدارة تدفق البيانات (streaming plumbing).

يغطي هذا الدليل كل ما يحتاجه المطورون للبدء: التثبيت، واجهة query() الأساسية، الأدوات المدمجة، الخطافات (hooks)، الجلسات (sessions)، العوامل الفرعية (subagents)، تكامل MCP، وكيفية استخدام واجهة LLM API من Novita AI كخلفية للنموذج.

النقاط الرئيسية

• تمت إعادة تسمية Claude Code SDK إلى Claude Agent SDK (claude-agent-sdk للغة Python، و@anthropic-ai/claude-agent-sdk للغة TypeScript).
• دالة واحدة query() تحل محل حلقة تنفيذ الأدوات اليدوية التي ستحتاجها مع Anthropic Client SDK.
• تغطي الأدوات المدمجة قراءة الملفات، التحرير، تنفيذ bash، البحث على الويب، والمزيد — دون الحاجة إلى تنفيذ مخصص.
• تسمح الجلسات للعامل باستئناف العمل عبر استدعاءات متعددة مع الحفاظ على السياق الكامل.
• تتيح الخطافات التحقق من صحة استدعاءات الأدوات أو تسجيلها أو حظرها في نقاط محددة من دورة الحياة.
• تتيح نقطة النهاية المتوافقة مع Anthropic من Novita AI (https://api.novita.ai/anthropic) استخدام نماذج عالية الجودة مفتوحة الأوزان مع نفس كود SDK.

ما هو Claude Code SDK؟

Claude Code SDK هو واجهة برمجية (API) برمجية لقدرات عامل Claude Code. يعرض نفس الأدوات، حلقة الاستدلال، وإدارة السياق التي تستخدمها واجهة سطر الأوامر Claude Code بشكل تفاعلي — ولكن كمكتبة تقوم باستيرادها واستدعائها من كودك الخاص.

أعادت Anthropic تسميته إلى Claude Agent SDK بدءًا من الجيل 4.6، لكن مصطلح البحث الأصلي “claude code sdk” لا يزال يصف بدقة ما هو عليه: طبقة SDK التي تقع فوق Claude Code وتسمح لك بأتمتة مهام العامل في البرمجيات.

ما يناسبه:

• مراجعة الكود الآلي، إعادة الهيكلة، أو إنشاء الاختبارات في CI/CD
• عوامل تقرأ وتعدل الملفات، تشغل النصوص البرمجية، أو تبحث على الويب نيابة عنك
• مسارات عمل متعددة العوامل حيث يقوم المنسق بتفويض المهام الفرعية لعمال متخصصين
• أي سير عمل تريد فيه أن يتخذ Claude إجراءات مستقلة متعددة الخطوات، وليس مجرد الإجابة على مطالبة

ما لا يناسبه: إذا كنت بحاجة إلى تحكم مباشر في كل رسالة، أو إخراج مهيكل من استدعاء واحد، أو استجابات متدفقة لواجهة دردشة، فإن Anthropic Client SDK هو الأنسب.

Claude Code SDK مقابل Anthropic Client SDK: متى تستخدم أيًا منهما

كلا SDK يعتمدان على Claude، لكنهما يحلان مشكلات مختلفة.

	Claude Agent SDK	Anthropic Client SDK
تنفيذ الأدوات	يتم التعامل معها بشكل مستقل بواسطة Claude	أنت تنفذ حلقة الأدوات
الواجهة	query() ترجع مكررًا غير متزامن (async iterator)	client.messages.create() ترجع كائن استجابة
الأدوات المدمجة	قراءة، كتابة، تحرير، Bash، Grep، Glob، WebSearch، والمزيد	لا شيء — أنت تقوم بتعريف وتنفيذ جميع الأدوات
الجلسات	مدمجة — استئناف باستخدام معرف جلسة	يدوية — إدارة تاريخ المحادثة بنفسك
الأفضل لـ	مسارات عمل العوامل، CI/CD، عمليات الملفات	تطبيقات الدردشة، الإخراج المهيكل، التحكم الدقيق

إذا كنت تريد أن يكتشف Claude الملفات التي يجب قراءتها ويعدلها بشكل مستقل: استخدم Agent SDK. إذا كنت تريد أن يستجيب Claude لمطالبة محددة ويعيد قيمة تقوم بمعالجتها: استخدم Client SDK.

تثبيت Claude Agent SDK

Python (يتطلب Python 3.10 أو أحدث):

pip install claude-agent-sdk

TypeScript / Node.js:

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

حزمة TypeScript تحتوي على ثنائي Claude Code الأصلي لمنصتك كاعتماد اختياري. لست بحاجة إلى تثبيت Claude Code بشكل منفصل.

للتحقق من إصدار Python قبل التثبيت:

python3 --version  # macOS/Linux
py --version       # Windows

إذا أبلغ pip بـ No matching distribution found for claude-agent-sdk، فإن مترجم Python الخاص بك أقدم من 3.10.

الخطوة 1: تكوين المصادقة

قم بتعيين مفتاح API الخاص بـ Anthropic كمتغير بيئة:

export ANTHROPIC_API_KEY=your-api-key

يدعم SDK أيضًا Amazon Bedrock وGoogle Vertex AI وAzure AI Foundry للفرق التي توجه عبر مزودي الخدمات السحابية:

# Amazon Bedrock
export CLAUDE_CODE_USE_BEDROCK=1
# بالإضافة إلى بيانات اعتماد AWS القياسية

# Google Vertex AI
export CLAUDE_CODE_USE_VERTEX=1
# بالإضافة إلى GOOGLE_CLOUD_PROJECT وبيانات اعتماد gcloud

# Microsoft Azure AI Foundry
export CLAUDE_CODE_USE_FOUNDRY=1
# بالإضافة إلى بيانات اعتماد Azure

الخطوة 2: تشغيل أول استعلام عامل لديك

سطح SDK بالكامل مبني حول دالة واحدة: query(). تقبل مطالبة وخيارات، وترجع مكررًا غير متزامن لأحداث الرسائل.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="List all Python files in this directory",
        options=ClaudeAgentOptions(allowed_tools=["Bash", "Glob"]),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

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

for await (const message of query({
  prompt: "List all Python files in this directory",
  options: { allowedTools: ["Bash", "Glob"] }
})) {
  if ("result" in message) console.log(message.result);
}

يُنتج المكرر عدة أنواع من الرسائل. الأكثر فائدة هما:

• ResultMessage (أو رسائل تحتوي على حقل result) — الرد النهائي للعامل
• SystemMessage ذو subtype === "init" — يحمل session_id لاستئناف العمل لاحقًا

الخطوة 3: التحكم في الأذونات باستخدام allowedTools

يأتي SDK مع أدوات منفذة مسبقًا. يمكنك تحديد الأدوات التي يُسمح للعامل باستخدامها؛ ويتولى Claude التنفيذ.

الأداة	ما تفعله
Read	قراءة أي ملف في دليل العمل
Write	إنشاء ملفات جديدة
Edit	إجراء تعديلات مستهدفة على الملفات الموجودة
Bash	تشغيل أوامر الصدفة، النصوص البرمجية، عمليات git
Glob	البحث عن الملفات حسب النمط (**/*.ts، src/**/*.py)
Grep	البحث في محتويات الملفات باستخدام التعبيرات العادية
WebSearch	البحث على الويب للحصول على معلومات حالية
WebFetch	جلب وتحليل محتوى صفحة الويب
Monitor	مراقبة نص برمجي في الخلفية والتفاعل مع سطور الإخراج
AskUserQuestion	طرح أسئلة توضيحية على المستخدم أثناء المهمة
Agent	استدعاء عامل فرعي محدد

مزيج Bash + Read + Edit كافٍ لمعظم مهام الكود الآلية. أضف WebSearch أو WebFetch عندما يحتاج العامل إلى بيانات خارجية.

allowed_tools (في Python) / allowedTools (في TypeScript) يوافق مسبقًا على أدوات محددة دون مطالبة. تقييد مجموعة الأدوات يحد أيضًا مما يمكن للعامل فعله بشكل غير مقصود — وهو حاجز وقائي مفيد لمسارات العمل الآلية.

عامل مراجعة كود للقراءة فقط:

from claude_agent_sdk import query, ClaudeAgentOptions

async for message in query(
    prompt="Review this codebase for security issues and code smell",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Glob", "Grep"],
    ),
):
    if hasattr(message, "result"):
        print(message.result)

عامل تحرير كامل (يوافق مسبقًا على كتابة الملفات):

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

permission_mode="acceptEdits" يوافق تلقائيًا على تحرير الملفات دون مطالبة تفاعلية، وهو مطلوب عند التشغيل في CI.

الخطوة 4: استخدام الخطافات للتحكم في دورة الحياة

تتيح لك الخطافات تشغيل كود مخصص في نقاط محددة من تنفيذ العامل. يمكنك تسجيل الإجراءات، التحقق من صحة المدخلات، حظر العمليات الخطيرة، أو تحديث الحالة الخارجية.

أحداث الخطاف المتاحة: PreToolUse، PostToolUse، PostToolUseFailure، UserPromptSubmit، Stop، SubagentStop، SubagentStart، PreCompact، Notification، PermissionRequest

يكتب هذا المثال سجل تدقيق في كل مرة يقوم فيها العامل بتحرير أو إنشاء ملف:

import asyncio
from datetime import datetime
from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher

async def log_file_change(input_data, tool_use_id, context):
    file_path = input_data.get("tool_input", {}).get("file_path", "unknown")
    with open("./audit.log", "a") as f:
        f.write(f"{datetime.now().isoformat()}: modified {file_path}\n")
    return {}

async def main():
    async for message in query(
        prompt="Refactor auth.py to use dataclasses",
        options=ClaudeAgentOptions(
            permission_mode="acceptEdits",
            hooks={
                "PostToolUse": [
                    HookMatcher(matcher="Edit|Write", hooks=[log_file_change])
                ]
            },
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

import { query, HookCallback } from "@anthropic-ai/claude-agent-sdk";
import { appendFile } from "fs/promises";

const logFileChange: HookCallback = async (input) => {
  const filePath = (input as any).tool_input?.file_path ?? "unknown";
  await appendFile("./audit.log", `${new Date().toISOString()}: modified ${filePath}\n`);
  return {};
};

for await (const message of query({
  prompt: "Refactor auth.ts to use interfaces",
  options: {
    permissionMode: "acceptEdits",
    hooks: {
      PostToolUse: [{ matcher: "Edit|Write", hooks: [logFileChange] }]
    }
  }
})) {
  if ("result" in message) console.log(message.result);
}

خطاف PreToolUse الذي يرجع { block: true } سيمنع استدعاء الأداة تمامًا — مفيد لفرض سياسات مثل “عدم حذف الملفات أبدًا” في السياقات الآلية.

الخطوة 5: استئناف العمل باستخدام الجلسات

تحافظ الجلسات على السياق الكامل للعامل — الملفات التي قرأها، ما وجده، تاريخ المحادثة — عبر استدعاءات query() متعددة. هذا يسمح لك بتقسيم مهمة طويلة إلى خطوات أو مواصلة عمل تمت مقاطعته.

لاستئناف جلسة، التقط session_id من حدث تهيئة SystemMessage، ثم مرره إلى resume:

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

async def main():
    session_id = None

    # الاستعلام الأول: قراءة وتحليل قاعدة الكود
    async for message in query(
        prompt="Read the authentication module and identify all external dependencies",
        options=ClaudeAgentOptions(allowed_tools=["Read", "Glob", "Grep"]),
    ):
        if isinstance(message, SystemMessage) and message.subtype == "init":
            session_id = message.data["session_id"]

    # الاستعلام الثاني: متابعة مع السياق الكامل من الأول
    async for message in query(
        prompt="Now check if any of those dependencies have known vulnerabilities",
        options=ClaudeAgentOptions(
            resume=session_id,
            allowed_tools=["Read", "Bash", "WebSearch"],
        ),
    ):
        if isinstance(message, ResultMessage):
            print(message.result)

asyncio.run(main())

المطالبة الثانية تستخدم “those dependencies” — إشارة لا تكون منطقية إلا لأن الجلسة تحمل السياق من الاستدعاء الأول. بدون resume، لن يكون لدى Claude أي فكرة عما تشير إليه.

الخطوة 6: تفويض المهام إلى العوامل الفرعية

العوامل الفرعية هي عوامل متخصصة يمكن لعاملك الرئيسي استدعاؤها عبر أداة Agent. العامل الرئيسي ينسق؛ العوامل الفرعية تقوم بالعمل المركز. تتدفق النتائج مرة أخرى إلى السياق الرئيسي.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AgentDefinition

async def main():
    async for message in query(
        prompt="Review this codebase: use the security-auditor agent for auth files and the style-checker agent for everything else",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep", "Agent"],
            agents={
                "security-auditor": AgentDefinition(
                    description="Specialist in authentication and authorization security.",
                    prompt="Audit auth-related code for OWASP Top 10 vulnerabilities. Be specific about line numbers and risk severity.",
                    tools=["Read", "Glob", "Grep"],
                ),
                "style-checker": AgentDefinition(
                    description="Code style and maintainability reviewer.",
                    prompt="Check code for naming conventions, complexity, and documentation gaps.",
                    tools=["Read", "Glob"],
                ),
            },
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

قم بتضمين "Agent" في allowed_tools للموافقة المسبقة على استدعاءات العامل الفرعي. تتضمن الرسائل من العامل الفرعي حقل parent_tool_use_id حتى تتمكن من تتبع المخرجات التي جاءت من أي عامل فرعي.

الخطوة 7: ربط الأنظمة الخارجية عبر MCP

بروتوكول سياق النموذج (MCP) يتيح لك إضافة قدرات خارجية للعامل — قواعد البيانات، المتصفحات، واجهات API الداخلية — دون كتابة أدوات مخصصة. يعامل العامل أدوات MCP بنفس طريقة الأدوات المدمجة.

يضيف هذا المثال أتمتة المتصفح عبر خادم Playwright MCP:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="Open https://example.com and describe the page structure",
        options=ClaudeAgentOptions(
            mcp_servers={
                "playwright": {
                    "command": "npx",
                    "args": ["@playwright/mcp@latest"]
                }
            }
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

خيار mcp_servers يقبل أي خادم يتبع مواصفات MCP. يسجل سجل MCP المجتمعي في github.com/modelcontextprotocol/servers مئات التكاملات بما في ذلك Postgres وPuppeteer وSlack وGitHub ومتغيرات نظام الملفات.

استخدام Novita AI كخلفية للنموذج

يستخدم Claude Agent SDK افتراضيًا واجهة Anthropic API، ولكن يمكنك توجيهه إلى نقطة نهاية Novita AI المتوافقة مع Anthropic لاستخدام نماذج مفتوحة الأوزان فعالة من حيث التكلفة — دون أي تغييرات في الكود.

تعكس نقطة نهاية Novita AI تنسيق Anthropic API:

https://api.novita.ai/anthropic

قم بتعيين متغيري البيئة هذين قبل تشغيل العامل الخاص بك:

export ANTHROPIC_BASE_URL="https://api.novita.ai/anthropic"
export ANTHROPIC_API_KEY="your-novita-api-key"

تعمل استدعاءات query() الحالية دون تعديل. يقرأ SDK ANTHROPIC_BASE_URL تلقائيًا.

تستضيف Novita AI مجموعة من النماذج — بما في ذلك Kimi K2.5 وGLM 5.2 وMiniMax M2.1 وQwen 3.5 — التي يمكن الوصول إليها من خلال هذه النقطة النهائية. للفرق التي تبني مسارات عمل للعامل تشغل آلاف المهام، يمكن أن يكون فرق التكلفة لكل رمز كبيرًا. راجع Novita AI LLM API للاطلاع على كتالوج النماذج الحالي والتسعير.

إذا كنت بحاجة إلى نشر العامل الخاص بك في بنية تحتية معزولة بالصندوق الرملي (sandbox) — مفيد لتنفيذ كود العامل حيث لا تريد أن يلمس العامل نظام الملفات المضيف — يوفر Novita Agent Sandbox بيئة تنفيذ متوافقة مع E2B مصممة خصيصًا للعوامل المبنية على Claude Agent SDK.

Claude Code SDK في مسارات CI/CD

قيود permission_mode="acceptEdits" و allowed_tools في SDK تجعل من العملي تشغيل العوامل دون مراقبة في CI. نمط نموذجي لـ GitHub Actions:

- name: Run automated code review
  env:
    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
  run: |
    python review_agent.py

حيث يحتوي review_agent.py على شيء مثل:

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="Review all changed Python files in this PR for correctness and test coverage gaps. Output a JSON report.",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Glob", "Grep", "Bash"],
            permission_mode="acceptEdits",
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)

asyncio.run(main())

بالنسبة للعوامل التي تكتب مرة أخرى إلى المستودع (إعادة الهيكلة الآلية، إنشاء الوثائق)، قم بإقران ذلك بخطاف PostToolUse يتحقق من صحة التغييرات قبل وصولها إلى git.

استكشاف الأخطاء وإصلاحها

No matching distribution found for claude-agent-sdk إصدار Python الخاص بك أقل من 3.10. قم بتشغيل python3 --version وقم بالترقية إذا لزم الأمر.

ANTHROPIC_API_KEY is not set يتطلب SDK متغير البيئة. قم بتصديره في الصدفة أو ملف .env قبل التشغيل.

ينهي TypeScript agent التنفيذ قبل الاكتمال تأكد من أنك تنتظر (await) حلقة المكرر بالكامل. يحتاج SDK إلى معالجة جميع أحداث الرسائل قبل خروج عمليتك.

يستخدم العامل أدوات غير متوقعة استخدم allowed_tools لتقييد مجموعة الأدوات بشكل صريح. إذا لم تحدده، فإن العامل لديه حق الوصول إلى جميع الأدوات المدمجة.

رسائل العامل الفرعي لا تظهر في المخرجات قم بتصفية الرسائل حيث يتم تعيين parent_tool_use_id لتحديد مخرجات العامل الفرعي بشكل منفصل عن العامل الرئيسي.

الجلسة لا تستأنف بشكل صحيح التقط session_id من SystemMessage مع subtype === "init" في بداية الاستعلام الأول، وليس من رسالة نتيجة.

الأسئلة الشائعة

ما الفرق بين Claude Code SDK وAnthropic SDK؟

يمنحك Claude Agent SDK (المعروف سابقًا بـ Claude Code SDK) عاملًا مستقلاً يتولى تنفيذ الأدوات تلقائيًا. يمنحك Anthropic Client SDK وصولاً خامًا إلى API حيث تنفذ حلقة الأدوات بنفسك. استخدم Agent SDK لمسارات عمل العوامل؛ استخدم Client SDK لاستدعاءات النموذج المباشرة مع تحكم دقيق.

ما هو إصدار Python المطلوب لـ claude-agent-sdk؟

Python 3.10 أو أحدث. لن يتم تثبيت الحزمة على Python 3.9 أو أقدم.

هل أحتاج إلى تثبيت واجهة سطر أوامر Claude Code لاستخدام TypeScript SDK؟

لا. حزمة @anthropic-ai/claude-agent-sdk تحتوي على ثنائي Claude Code الأصلي الخاص بها كاعتماد اختياري.

هل يمكن لـ Claude Agent SDK استخدام نماذج غير Claude من Anthropic؟

من خلال تعيين ANTHROPIC_BASE_URL إلى نقطة نهاية متوافقة مع Anthropic مثل https://api.novita.ai/anthropic، يمكنك استخدام أي نموذج يستضيفه هذا المزود — بما في ذلك نماذج مفتوحة الأوزان من Kimi أو GLM أو MiniMax أو Qwen.

كيف يختلف Agent SDK عن Claude Managed Agents؟

Managed Agents هي REST API مستضافة حيث يقوم Anthropic بتشغيل العامل في بنيته التحتية. Agent SDK هي مكتبة تقوم بتشغيل حلقة العامل في عمليتك الخاصة، على نظام الملفات الخاص بك. Agent SDK أفضل للتطوير المحلي والعوامل التي تحتاج إلى الوصول إلى ملفاتك أو خدماتك الخاصة.

هل يدعم Claude Agent SDK الإخراج المتدفق؟

ترجع دالة query() مكررًا غير متزامن يُنتج رسائل أثناء عمل العامل. هذا يمنحك سلوكًا يشبه التدفق — ترى النتائج الوسيطة قبل الإجابة النهائية.

هل يمكنني استخدام Agent SDK مع Amazon Bedrock أو Vertex AI؟

نعم. قم بتعيين CLAUDE_CODE_USE_BEDROCK=1 بالإضافة إلى بيانات اعتماد AWS لـ Bedrock، أو CLAUDE_CODE_USE_VERTEX=1 بالإضافة إلى بيانات اعتماد Google Cloud لـ Vertex AI.

ما هي وثائق anthropic claude agent sdk التي يجب أن أقرأها أولاً؟

الوثائق الرسمية موجودة في code.claude.com/docs/en/agent-sdk/overview. ابدأ بالبداية السريعة، ثم اقرأ أدلة الجلسات والخطافات بمجرد حصولك على عامل يعمل.

مقالات موصى بها

• وثائق Claude Code CLI: الإعداد، أوامر الشرطة المائلة، وتكامل LLM API
• Vercel AI SDK: دليل المطور الكامل لبناء تطبيقات الذكاء الاصطناعي
• كيفية نشر واستضافة Claude Agent SDK مع Novita Sandbox

---

تم التحقق من المصادر في 3 يوليو 2026: وثائق Claude Agent SDK، Novita AI LLM API