Claude Agent SDK (المعروف سابقًا باسم Claude Code SDK): دليل بايثون وتايب سكريبت

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

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

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

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

ما هو Claude Code SDK؟

Claude Code SDK هو واجهة برمجية للتفاعل مع قدرات وكيل Claude Code. فهو يعرض نفس الأدوات وحلقة التفكير وإدارة السياق التي يستخدمها Claude Code CLI بشكل تفاعلي - ولكن كمكتبة تقوم باستيرادها واستدعائها من كودك الخاص. للاطلاع على قواعد المشروع ونطاقه، راجع Claude Code rules and CLAUDE.md.

أعادت 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() تعيد مكررًا غي متزامن | client.messages.create() تعيد كائن استجابة | | الأدوات المضمنة | Read, Write, Edit, Bash, Grep, Glob, WebSearch, وغيرها | لا يوجد - عليك تحديد وتنفيذ جميع الأدوات | | الجلسات | مضمنة - استأنف باستعمال معرف جلسة | يدوية - قم بإدارة تاريخ المحادثة بنفسك | | الأفضل لـ | خطوط أنابيب الوكلاء، CI/CD، عمليات الملفات | تطبيقات الدردشة، المخرجات المنظمة، التحكم الدقيق |

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

تثبيت Claude Agent SDK

بايثون (يتطلب بايثون 3.10+):

pip install claude-agent-sdk

تايب سكريبت / 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: تيكيل المصادقة

قم بتعيي مفتاح Anthropic API كمتغير بيئة:

export ANTHROPIC_API_KEY=your-api-key

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

# Amazon Bedrock
export CLAUDE_CODE_USE_BEDROCK=1
# plus standard AWS credentials

# Google Vertex AI
export CLAUDE_CODE_USE_VERTEX=1
# plus GOOGLE_CLOUD_PROJECT and gcloud credentials

# Microsoft Azure AI Foundry
export CLAUDE_CODE_USE_FOUNRY=1
# plus Azure credentials

الخطوة 2: تشغيل اول استفسار وكيل

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

import asyncio
from claud_e_agent_sdk import query, ClaudeAgentOptins

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	مراقبة سكريبت في الخلفية والت فاعل مع سطور المخرجات
AskUserQestion	طر سؤال توضيحي للمستخدم في منتصف المهمة
Agent	استدعاء وكيل فرعي محدد

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

allowed_tools (بايثون) / allowedTools (تايب سكريبت) يعتمد الموافقة المس بقة على أدوات محددة دون طلب. يُقيّد تقييد مجموعة الأدوات أيضًا ما يمكن للوكيل فعله عن غير قصد — حارس أمان مفيد لخطوط الأنابيب الآلية.

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

from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    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_chnge(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

    # First query: read and analyze the codebase
    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"]

    # Second query: continue with full context from the first
    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())

المطالبة الثانية تستخدم “تلك التبعيات” — إشارة منطقية فقط لأن الجلسة تحمل السياق من الاستدعاء الأول. بدون 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) يتيح لك إضافة قدرات خارجية إلى الوكيل — قواعد البيانات، المتصفحات، واجهات برمجة التطبيقات الداخلية — دون كتابة أدوات مخصصة. يتعامل الوكيل مع أدوات 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، لكن يمكنك توجيهه إلى نقطة نهاية Novita AI المتوافقة مع Anthropic لاستخدام نماذج مفتوحة الوزن فعالة من حيث التكلفة — دون أي تغييرات في الكود.

نقطة نهاية Novita AI تعكس تنسيق واجهة برمجة تطبيقات 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: 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 يخرج قبل الاكتمال تأكد من أنك 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 وصولاً خامًا لواجهة برمجة التطبيقات حيث تقوم بتنفيذ حلقة الأدوات بنفسك. استخدم Agent SDK لخطوط أنابيب الوكلاء؛ استخدم Client SDK لاستدعاءات النموذج المباشرة مع تحكم دقيق.

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

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

هل أحتاج إلى تثبيت Claude Code CLI لاستخدام SDK الخاص بـ TypeScript؟

لا. حزمة @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.

ما هي وثائق Claude Agent SDK التي يجب أن أقرأها أولاً؟

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

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

• How to Use Claude Code Agents: Setup, Tools, Permissions, and Sandbox Workflow
• Claude Code Plugins: How MCP Tools Extend Claude Code with External Capabilities
• Claude Code Rules: How to Write CLAUDE.md and Manage Agentic Coding Context
• Claude Code CLI Documentation: Setup, Slash Commands, and LLM API Integration
• Vercel AI SDK: Complete Developer Guide for Building AI Applications
• How to Deploy and Host Claude Agent SDK with Novita Sandbox

---

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