Claude Code SDK (Claude Agent SDK): دليل Python و TypeScript

Claude Code SDK، الذي تمت إعادة تسميته إلى Claude Agent SDK في إصدار وكيل SDK من Anthropic، هو مكتبة Python و TypeScript لتشغيل وكلاء برمجة مستقلين داخل تطبيقك. يتعامل مع قراءة الملفات والأوامر وتعديلات الكود واستدعاءات الأدوات والتكرار متعدد الخطوات دون حلقة أدوات مبنية يدويًا. باستخدام نقطة نهاية Novita AI المتوافقة مع Anthropic، يمكن لنفس SDK أيضًا تشغيل النماذج مفتوحة الوزن المدعومة، مما يمنح الفرق مسارًا لاختيار النموذج والتحكم في التكلفة يتجاوز الواجهة الخلفية الافتراضية لـ Anthropic.

يغطي هذا الدليل كل ما يحتاجه المطورون للبدء: التثبيت، واجهة برمجة التطبيقات الأساسية query()، الأدوات المضمنة، الخطافات، الجلسات، الوكلاء الفرعيون، تكامل 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 والبحث على الويب والمزيد — بدون الحاجة إلى تنفيذ.
• تسمح الجلسات للوكلاء باستئناف العمل عبر استدعاءات متعددة مع سياق كامل سليم.
• تسمح لك الخطافات بالتحقق من صحة أو تسجيل أو حظر استدعاءات الأدوات في نقاط محددة من دورة الحياة.
• نقطة نهاية Novita AI المتوافقة مع Anthropic (https://api.novita.ai/anthropic) تتيح لك استخدام نماذج عالية الجودة مفتوحة الوزن مع نفس كود SDK.

ما هو Claude Code SDK؟

Claude Code SDK هو واجهة برمجية لإمكانيات وكيل 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: متى تستخدم كل منهما

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

	Claude Agent SDK	Anthropic Client SDK
تنفيذ الأدوات	يتم التعامل معه بشكل مستقل بواسطة Claude	تقوم أنت بتنفيذ حلقة الأدوات
الواجهة	query() تُرجع مكررًا غير متزامن	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	البحث في محتويات الملفات باستخدام regex
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 init، ثم مرره إلى 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

Model Context Protocol (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 يستخدم افتراضيًا API الخاص بـ Anthropic، لكن يمكنك توجيهه إلى نقطة نهاية Novita AI المتوافقة مع Anthropic لاستخدام نماذج مفتوحة الوزن فعالة من حيث التكلفة — بدون أي تغييرات في الكود.

نقطة نهاية Novita AI تعكس تنسيق API الخاص بـ Anthropic:

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: تشغيل مراجعة الكود الآلية
  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 يخرج قبل الإكمال تأكد من أنك 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 CLI لاستخدام 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: الإعداد، أوامر الشرطة المائلة، وتكامل LLM API
• Vercel AI SDK: دليل المطور الكامل لبناء تطبيقات الذكاء الاصطناعي
• كيفية نشر واستضافة Claude Agent SDK مع Novita Sandbox

---

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