بناء وكلاء ذاتيين باستخدام Claude Code SDK: دليل عملي للمطورين

بناء وكلاء ذاتيين باستخدام Claude Code SDK: دليل عملي للمطورين

يُعتبر Claude Code SDK — المسمّى رسميًا Agent SDK — مكتبة بلغتي Python وTypeScript تتيح لك تشغيل محرك Claude Code الوكيلي الكامل برمجيًا: دون الحاجة إلى طرفية (terminal)، ودون وجود إنسان أمام لوحة المفاتيح، فقط تطبيقك يستدعي دالة غير متزامنة query() ويستقبل تدفقًا (stream) لكل خطوة من عمل الوكيل. إن كنت قد استخدمت Claude Code بشكل تفاعلي، فإن SDK يمنحك نفس حلقة قراءة الملفات / تعديل الكود / تشغيل الأوامر كمكتبة قابلة للتركيب يمكنك تضمينها في خطوط CI، أو روبوتات مراجعة الكود، أو منظّمات الوكلاء المتعددين، أو أي خدمة خلفية (backend).

ما هو Agent SDK — ولماذا تم إنشاؤه

يُعرف Claude Code جيدًا كأداة طرفية (terminal). تكتب موجّهًا (prompt)، ويقوم الوكيل بالاستدلال على قاعدة الكود الخاصة بك، ويستدعي أدوات مدمجة (Read، Edit، Bash، Grep، وغيرها)، ويكتب النتائج مرة أخرى لك. لكن في اللحظة التي تريد أتمتة تلك الحلقة — تشغيل مراجعة عند كل طلب سحب (pull request)، أو توزيع العمل على عدة وكلاء فرعيين متخصصين، أو بناء منتج مبني عليها — تصبح واجهة سطر الأوامر التفاعلية (CLI) هي التجريد الخاطئ. أنت تحتاج إلى مكتبة.

يسدّ Agent SDK هذه الفجوة. وفقًا لـالوثائق الرسمية من Anthropic، فإنه يوفّر "نفس الأدوات، وحلقة الوكيل، وإدارة السياق التي تشغّل Claude Code، قابلة للبرمجة بلغتي Python وTypeScript." وهذا ليس مجرد كلام تسويقي — بل هو البنية الحرفية. يقوم SDK بتشغيل الملف الثنائي (binary) لـ Claude Code CLI كعملية فرعية (subprocess) مُدارة، ويتواصل معها عبر stdio، ويعرض كل شيء كتدفق غير متزامن من كائنات رسائل مُصنّفة (typed) يمكن لكودك استهلاكها والتفاعل معها.

هذا التمييز مهم لعدة أسباب:

المحرك نفسه، واجهة مختلفة. عندما تنتقل من CLI إلى SDK، لا تنتقل إلى أداة أقل أو أبسط. يرث SDK كل قدرة موجودة في CLI — الاتصال بخوادم MCP، ودورة حياة hooks، وملفات skill، وذاكرة CLAUDE.md، وتفويض الوكلاء الفرعيين، وكامل قائمة الأدوات.

يقوم SDK بتنفيذ الأدوات بدلًا منك. إذا استخدمت Anthropic Client SDK (حزمة anthropic منخفضة المستوى بلغة Python/JS) وأردت أن يستدعي Claude الأدوات، فعليك تنفيذ حلقة الأدوات بنفسك: استدعاء الـ API، اكتشاف استجابة استخدام أداة، تنفيذ الأداة، إعادة تغذية النتيجة، والتكرار حتى يتوقف Claude. يُلخّص Agent SDK هذه الحلقة الكاملة في async for message in query(...) واحدة — يتولى Claude تحديد الأدوات التي يستدعيها، وينفّذها داخل عمليته الفرعية، ويستمر في التكرار حتى تنتهي المهمة. أنت فقط تستهلك التدفق.

بلا واجهة تفاعلية (Headless) بالتصميم. طلبات الإذن في CLI — "هل تسمح بتشغيل أمر bash هذا؟" — تحظر (block) في انتظار إدخال بشري. يستبدلها SDK بخيار permissionMode ومجموعة من أنماط الأذونات — مثلًا acceptEdits للموافقة التلقائية على تعديلات الملفات وbypassPermissions لتشغيل كل شيء دون طلب في بيئة CI محمية (sandboxed) — بالإضافة إلى دالة موافقة برمجية (callback) لتدفقات مخصصة. أسماء الأنماط الدقيقة وسلوكياتها موثّقة في مرجع Anthropic لـ SDK (راجعه للحصول على القائمة الحالية)، لكن التأثير واحد: أتمتتك لن تتعلق أبدًا في انتظار ضغطة مفتاح.

نفس محرك Claude Code، واجهتان: CLI التفاعلي للعمل الذي يتضمن إنسانًا في الحلقة، وAgent SDK للأتمتة البرمجية بلا واجهة تفاعلية حيث يتحكم تطبيقك في الموجّه ويحل نمط الأذونات محل نافذة الموافقة.

تثبيت SDK

تنشر Anthropic حزمتين:

• TypeScript: @anthropic-ai/claude-agent-sdk (npm)
• Python: claude-agent-sdk (pip؛ يتطلب Python 3.10 أو أحدث)

تحتوي حزمة TypeScript على ملف ثنائي أصلي (native) لـ Claude Code مخصص لمنصتك، لذا لا حاجة لتثبيت CLI بشكل منفصل. تتم المصادقة عبر متغير البيئة ANTHROPIC_API_KEY الذي يتم الحصول عليه من Anthropic Console. يدعم SDK أيضًا Amazon Bedrock وGoogle Vertex AI وMicrosoft Azure AI Foundry — راجع وثائق Anthropic للحصول على أنماط متغيرات البيئة ذات الصلة.

المفاهيم الأساسية

فهم أربعة مفاهيم يغطي الغالبية العظمى من استخدامات SDK في العالم الحقيقي.

1. دالة query() وتدفق الرسائل غير المتزامن

يبدأ كل تفاعل مع SDK باستدعاء query(). تمرّر سلسلة نصية prompt وكائن options؛ وفي المقابل تحصل على مُكرِّر (iterator) غير متزامن يُنتج كائنات رسائل مُصنّفة بينما يعمل الوكيل. تنتهي الحلقة عند انتهاء الوكيل أو عند مواجهة خطأ.

تشمل الرسائل التي تستقبلها:

• AssistantMessage — نص استدلال Claude ووصف استدعاءات الأدوات
• ToolResultMessage — مخرجات كل تنفيذ لأداة
• ResultMessage — النتيجة النهائية، مع حقل subtype يشير إلى النجاح أو الفشل
• SystemMessage — أحداث دورة حياة الجلسة (النمط الفرعي init يحمل session_id)

في معظم الكود الإنتاجي، تُصفّي بحثًا عن ResultMessage لاستخراج المخرج النهائي، وبشكل اختياري تسجّل كتل AssistantMessage لتتبّع ما قام به الوكيل.

2. الأدوات و allowedTools

تتطابق قائمة الأدوات المدمجة في SDK مباشرة مع قدرات Claude Code:

يوافق خيار allowedTools مسبقًا على مجموعة فرعية من هذه الأدوات، ما يمنح الوكيل بشكل فعّال إذنًا لاستدعائها دون أي بوابة إضافية. قد يُدرج وكيل مراجعة للقراءة فقط ["Read", "Glob", "Grep"] فقط؛ أما الأتمتة الكاملة فقد تشمل ["Read", "Edit", "Bash", "Glob", "Grep"].

3. أنماط الأذونات

تتحكم أنماط الأذونات في ما يحدث عندما يريد الوكيل استخدام أداة غير موافق عليها مسبقًا في allowedTools:

• acceptEdits — يوافق تلقائيًا على تعديلات الملفات وعمليات نظام الملفات الشائعة؛ ويطلب الإذن لأي شيء آخر. الأفضل لتدفقات العمل التطويرية الموثوقة.
• dontAsk — يرفض بصمت أي شيء غير موجود في allowedTools. الأفضل للوكلاء بلا واجهة تفاعلية والمُقيّدين تمامًا.
• bypassPermissions — يشغّل كل أداة دون بوابة. استخدمه فقط داخل بيئة محمية (sandboxed).

يوفّر SDK أيضًا دالة موافقة برمجية (callback) بحيث يمكنك تنفيذ منطق موافقة مخصص بالكامل، وقد تتوسع أسماء الأنماط المتاحة بمرور الوقت — راجع مرجع Anthropic لـ SDK للحصول على القائمة الرسمية الحالية والسلوك الدقيق لكل نمط. في CI، ستستخدم دائمًا تقريبًا تكوينًا محدودًا بدقة ورافضًا افتراضيًا (deny-by-default)، أو bypassPermissions داخل بيئة حاوية (container sandbox) تتحكم بها.

4. الجلسات، الاستكمال، والسياق

كل استدعاء لـ query() يُنشئ (أو يستكمل) جلسة. يصل session_id الخاص بالجلسة في أول SystemMessage مع subtype === "init". يمكنك التقاطه وتمريره كـ resume: sessionId في استدعاء لاحق لاستكمال المحادثة من حيث تُركت تمامًا — نفس قراءات الملفات، ونفس تاريخ الاستدلال، ونفس نافذة السياق.

هذه هي طريقة بناء الوكلاء متعددي الأدوار: استدعاء query() واحد يحلل وحدة (module)، ويلتقط session_id، واستدعاء query() ثاني (مع resume) يشير إلى "الوحدة" أو "الملف الذي قرأته للتو" دون إعادة الشرح. تُكتب نصوص الجلسة (transcripts) على القرص المحلي بشكل افتراضي؛ وللبيئات الإنتاجية يمكنك ربط محول SessionStore مدعوم بـ S3 أو Redis أو Postgres حتى تنجو الجلسات من إعادة تشغيل الحاويات.

نمط بناء 1: روبوت مراجعة كود في CI

هذه هي حالة الاستخدام الكلاسيكية "الأتمتة بلا واجهة تفاعلية". عند كل طلب سحب (pull request)، تُخرج مهمة CI الفرع، وتشغّل وكيلًا يقرأ الملفات المُغيَّرة، وينشر تعليق مراجعة.

سير العمل:

1. يُشغِّل حدث PR سير عمل GitHub Actions (أو مهمة GitLab CI).
2. يُخرج المُشغِّل (runner) الفرع ويشغّل سكربت مراجعتك.
3. يستدعي سكربتك query() بموجّه مراجعة، وallowedTools: ["Read", "Glob", "Grep", "Bash"]، وpermissionMode: "dontAsk".
4. يقرأ Claude الاختلافات (diff)، ويبحث عن الأنماط، ويستدلّ حول النتائج.
5. يحمل ResultMessage نص المراجعة؛ وينشره سكربتك على PR عبر GitHub API.

الخيار التصميمي الأساسي هو استخدام dontAsk مع قائمة أدوات للقراءة فقط. لا يمكن للوكيل كتابة ملفات أو إجراء استدعاءات شبكة تتجاوز ما تسمح به الأدوات، لذا لا يمكن لمهمة CI الخاصة بك دمج تعديلات أو استدعاء APIs خارجية بشكل عرضي. يحدّ سقف maxTurns (يُضبط في الخيارات) من عمق الوكيل بحيث لا تستنزف الحلقات المارقة الميزانية.

للحصول على البنية المُوضَّحة لهذا التدفق، راجع الرسم التخطيطي أدناه.

خط أنابيب مراجعة كود مؤتمت بالكامل. يعمل وكيل SDK داخل حاوية CI بقائمة أدوات للقراءة فقط؛ تتدفق النتائج مرة أخرى كـ ResultMessage وينشرها كودك كتعليق PR على GitHub. الوكيل لا يكتب ملفات أبدًا، ولا يخرج من الحاوية أبدًا.

يمكنك توسيع هذا النمط بواسطة hooks — ميزة في SDK مُغطّاة في دليلنا المتعمق حول Claude Code hooks — لتسجيل كل استدعاء أداة في ملف تدقيق، أو حظر مسارات ملفات معينة من القراءة، أو إصدار تلمترية (telemetry) مُهيكلة إلى جانب المراجعة.

نمط بناء 2: سلاسل أدوات متعددة الوكلاء

يتيح خيار agents في SDK تعريف وكلاء فرعيين مسمّين، كل منهم بموجّه نظام (system prompt) وقائمة أدوات وأذونات خاصة به. يفوّض وكيلك الرئيسي العمل إليهم عبر أداة Agent المدمجة. تشمل رسائل الوكلاء الفرعيين حقل parent_tool_use_id بحيث يمكنك تتبّع بالضبط أي تفويض أنتج أي جزء من المخرجات.

مثال عملي: سلسلة وكلاء لتدقيق أمني حيث يجد وكيل فرعي code-scanner نقاط ضعف محتملة باستخدام Grep وGlob، ويشغّل وكيل فرعي dependency-checker أداة Bash للاستفسار عن بيانات وصفية للحزم (package metadata)، ويُدمج وكيل منسّق (coordinator) كلا التقريرين في تدقيق موحد. كل وكيل فرعي يملك الحد الأدنى من الوصول للأدوات اللازم لدوره، مما يحدّ من نطاق التأثير إذا تخيّل وكيل فرعي أمرًا خطيرًا وهميًا.

تعمل سلاسل الوكلاء المتعددين بشكل جيد للمهام التي تتفكك بشكل طبيعي: وكيل واحد لكل جانب، كل منهم بقائمة أدوات محدودة، يُنسّقهم منسّق يحتاج فقط إلى Read وAgent. للحصول على نظرة أوسع حول كيفية تركيب بنى الوكلاء المتعددين مع ميزات Claude Code مثل ذاكرة CLAUDE.md وملفات skill، راجع دليلنا حول هندسة الأداة (harness).

نمط بناء 3: خطوط أنابيب أتمتة بلا واجهة تفاعلية

بعيدًا عن مراجعة الكود، يتفوّق SDK في أي أتمتة متكررة يكون فيها الوكيل خطوة في خط أنابيب أكبر:

تدقيقات ليلية للتبعيات. تستدعي مهمة cron query() بموجّه للبحث عن الحزم القديمة، وتشغيل ماسحات الأمان، وإصدار تقرير مُهيكل. تشغّل أداة Bash أوامر مثل npm audit أو pip check؛ وتفحص Read ملفات القفل (lock files). يُغذّي ResultMessage إشعار Slack.

الترجمة وتدويل (i18n) عند دمج PR. عندما يُدمج PR، يُشغِّل webhook وكيلًا يقرأ ملفات النصوص المُغيَّرة باستخدام Glob وRead، وينتج نسخًا مترجمة باستخدام Write، ويفتح PR جديدًا عبر Bash (بتشغيل gh pr create).

اكتشاف الشذوذ في السجلات (logs). ضخّ مخرجات السجل الحديثة في موجّه query(). يقرأ الوكيل ملفات سياق إضافية عند الحاجة، ويستدل على السجلات، ويصدر نتيجة مُهيكلة. لا حاجة لكتابة ملفات؛ تكفي قائمة أدوات للقراءة فقط.

مزامنة الوثائق. بعد دمج طلبات السحب (PRs)، يقرأ وكيل ملفات المصدر المُحدَّثة ويعيد كتابة صفحات الوثائق المقابلة، ثم يُلزم (commit) التغييرات. يتعامل permissionMode: "acceptEdits" مع كتابة الملفات دون طلب إذن.

القاسم المشترك: يحل query() محل تكامل LLM مُصمّم خصيصًا. أنت لا تنفّذ حلقة أدوات، ولا تُدير نوافذ السياق يدويًا، ولا تحلّل مخرجات النموذج لتحديد ما يجب تنفيذه بعد ذلك. يتولى الوكيل التنظيم؛ وأنت تُقدّم الموجّه وتستهلك النتيجة.

مثال عملي توضيحي: وكيل لإصلاح الأخطاء (Bugs)

توضّح دليل البدء السريع الرسمي هذا النمط بشكل واضح (يتبع الكود أدناه واجهة API الموثّقة — تحقق من الصياغة الدقيقة في وثائق البدء السريع من Anthropic):

توضيحي بلغة Python (تحقق من واجهة API الدقيقة في الوثائق الرسمية):

# توضيحي — تأكد من مسارات الاستيراد الدقيقة وأسماء الخيارات في الوثائق الرسمية
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ResultMessage

async def run_bug_fixer(file_path: str):
    async for message in query(
        prompt=f"Review {file_path} for bugs that would cause crashes. Fix any issues.",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Glob"],
            permission_mode="acceptEdits",
        ),
    ):
        if isinstance(message, AssistantMessage):
            for block in message.content:
                if hasattr(block, "text"):
                    print(block.text)
        elif isinstance(message, ResultMessage):
            print(f"Completed: {message.subtype}")

asyncio.run(run_bug_fixer("src/utils.py"))

توضيحي بلغة TypeScript (تحقق من واجهة API الدقيقة في الوثائق الرسمية):

// توضيحي — تأكد من مسارات الاستيراد الدقيقة وأسماء الخيارات في الوثائق الرسمية
import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Review src/utils.ts for crash-causing bugs and fix them.",
  options: {
    allowedTools: ["Read", "Edit", "Glob"],
    permissionMode: "acceptEdits",
  },
})) {
  if (message.type === "assistant" && message.message?.content) {
    for (const block of message.message.content) {
      if ("text" in block) console.log(block.text);
    }
  }
  if (message.type === "result") console.log("Done:", message.subtype);
}

ما يحدث عند تشغيل هذا: يقرأ Claude ملف utils.py (أو .ts) باستخدام أداة Read، ويستدل على الكود، ويحدد الحالات الحدّية (edge cases)، ثم يستدعي Edit لإدراج معالجة دفاعية. تشاهد الاستدلال واستدعاءات الأدوات تتدفق أمامك كأجسام AssistantMessage؛ ويشير ResultMessage النهائي إلى الاكتمال. حلقة الوكيل بالكامل — بما فيها إعادة قراءة الملف للتحقق من التعديل — يُديرها SDK.

هذا ما يجعل SDK مختلفًا عن استدعاء API نماذج Anthropic مباشرة: أنت لا تنفّذ طبقة تنفيذ الأدوات. يقرر Claude متى يستدعي Read، ويستدعيها، ويحصل على محتوى الملف مرة أخرى، ويستمر في الاستدلال. الحلقة ذاتية التشغيل (autonomous).

الأذونات، الحماية (Sandboxing)، وأمان الإنتاج

يتطلب تشغيل وكلاء ذاتيين في بيئة الإنتاج تفكيرًا دقيقًا حول ما يمكنهم الوصول إليه. يوفّر SDK عدة ضوابط متراكبة.

تحديد نطاق الأدوات هو خط الدفاع الأول. إذا لم يحتج الوكيل إلى Bash، فلا تُدرجها في allowedTools. لا يمكن لوكيل يملك فقط ["Read", "Glob", "Grep"] تعديل الملفات، أو تشغيل أوامر shell، أو إجراء استدعاءات شبكة بغض النظر عمّا يقوله موجّهه.

أنماط الأذونات توفّر بوابة ثانية. يضمن dontAsk أن أي شيء خارج allowedTools يُرفض بصمت بدلًا من طلب الإذن. هذا حاسم في البيئات بلا واجهة تفاعلية — طلب إذن يتعلق في انتظار إدخال المستخدم سيُعطّل خط أنابيبك.

خيار cwd يحدّ نطاق وصول الوكيل إلى نظام الملفات لدليل معيّن. في البيئات متعددة المستأجرين (multi-tenant)، مرّر دليل عمل خاص بكل جلسة بحيث لا يستطيع الوكلاء من مستأجرين مختلفين قراءة ملفات بعضهم البعض.

عزل المستأجرين يتطلب خطوات إضافية: ضبط settingSources: [] بحيث لا تتسرب إعدادات نظام الملفات عبر المستأجرين؛ وضبط CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 لمنع تحميل الذاكرة التلقائية؛ وتوجيه CLAUDE_CONFIG_DIR إلى مسار خاص بكل مستأجر. هذه موثّقة بالتفصيل في دليل الاستضافة (hosting guide) من Anthropic.

الحماية بالحاويات (Container sandboxing) هي الغلاف الخارجي. للوكلاء الإنتاجيين الذين يحتاجون إلى وصول Bash، شغّل SDK داخل حاوية بخروج شبكة (network egress) مُقيَّد إلى النطاقات التي تسمح بها صريحًا. تُشير وثائق Anthropic إلى مزودين مثل Modal وE2B وCloudflare Sandboxes وFly Machines وVercel Sandbox كخيارات لعمليات نشر SDK محمية.

maxTurns يحدّ عدد الجولات ذهابًا وعودة لاستخدام الأدوات، مما يحدّ من الكلفة والحلقات المارقة معًا. اضبطها بناءً على التعقيد المتوقع لمهمتك — مراجعة قراءة ملف بسيطة قد تحتاج إلى 5-10 جولات؛ وإعادة هيكلة معقدة متعددة الملفات قد تحتاج إلى 30-50 جولة.

للفرق التي تبني hooks وتدفقات أذونات إنتاجية، يُغطّي دليلنا حول Claude Code hooks دورة حياة hooks الخاصة بـ PreToolUse وPostToolUse بالتفصيل، بما في ذلك كيفية كتابة دوال hook التي تحظر أو تحوّل أو تسجّل استدعاءات الأدوات قبل تنفيذها.

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

يدعم SDK بروتوكول سياق النموذج (Model Context Protocol - MCP) بشكل كامل، والذي يتيح لك ربط وكيلك بأي نظام خارجي يعرض خادم MCP: قواعد البيانات، وأتمتة المتصفح، وJira، وSlack، وGitHub، ومئات الخوادم المُنشأة من قبل المجتمع.

تُهيّئ خوادم MCP في خيار mcpServers — يحدد كل إدخال أمرًا لتشغيله ومعاملات (arguments) اختيارية. يشغّل SDK هذه الخوادم كعمليات فرعية، ويمكن للوكيل استدعاء أدواتها بنفس الطريقة التي يستدعي بها الأدوات المدمجة. هذه هي طريقة منح وكيل مراجعة الكود الوصول إلى متعقب المشاكل (issue tracker) الخاص بك، أو ربط وكيل وثائق بقاعدة معرفة شركتك.

ينطبق نموذج الأذونات على استدعاءات أدوات MCP أيضًا — يمكن أن يشمل allowedTools أسماء أدوات MCP، ويحكم permissionMode ما يحدث للأدوات غير المُدرجة.

المزالق والأخطاء الشائعة

الجلسات محلية بالنسبة للعملية الفرعية بشكل افتراضي. تعيش نصوص الجلسة (transcripts) على القرص المحلي للمضيف تحت ~/.claude/projects/. في عمليات النشر المُحوسبة (containerized) أو المُوسَّعة أفقيًا، هذا يعني أن حالة الجلسة تُفقد عند إعادة التشغيل أو إعادة تعيين العقدة (node). استخدم محول SessionStore لأي جلسة تحتاج إلى استكمالها عبر حاويات مختلفة.

نموذج العملية الفرعية له تأثيرات على الذاكرة. كل جلسة قيد التشغيل هي عملية فرعية منفصلة. تشغيل خمسين جلسة متزامنة يعني خمسين عملية Claude Code. التوجيه الرسمي يقارب 1 جيجابايت من الذاكرة العشوائية لكل وكيل كنقطة بداية، لكن استخدام الذاكرة الفعلي في العالم الحقيقي يعتمد على طول الجلسة ونشاط الأدوات. حدّد حجم حاوياتك وفقًا لذلك واضبط maxTurns للحدّ من عمق الجلسة.

توزيع الوكلاء الفرعيين الكبير يصطدم بحدود المعدل (rate limits). إذا فوّض منسّقك العمل إلى عشرين وكيلًا فرعيًا في وقت واحد، فمن المرجح أن تصطدم بحدود معدل API الخاصة بـ Anthropic. قسّم عمليات التوزيع الواسعة إلى مجموعات (batches) وأضف تأخيرًا بسيطًا بين عمليات الإرسال.

bypassPermissions يتطلب بيئة محمية حقيقية. يتجاوز هذا النمط جميع بوابات الأذونات. صُمِّم للبيئات المُتحكَّم بها بالكامل مثل حاويات CI حيث تملك سياق التنفيذ الكامل. استخدامه على جهاز مطور — حيث يملك الوكيل وصولًا إلى مفاتيح SSH، وبيانات اعتماد السحابة، ومسارات نظام ملفات عشوائية — يُعد خطرًا أمنيًا.

حزمة TypeScript SDK تُضمّن الملف الثنائي لـ Claude Code؛ ولا يتطلبه Python بشكل منفصل. لكن كلا الحزمتين مُرتبطتان بإصدار CLI محدد. عند ترقية حزمة SDK، تُرقّي CLI الأساسي. راجع سجل التغييرات (changelog) قبل الترقيات الفرعية — تُعلَن تغييرات السلوك الجذرية هناك.

نص الموجّه ومدخلات الأدوات ليست ضمن تصديرات OTEL بشكل افتراضي. هذا سلوك خصوصية مقصود. إذا احتجت إلى تتبّع على مستوى الموجّه لأغراض تصحيح الأخطاء، عليك التفعيل الصريح عبر متغيرات البيئة الموثّقة في دليل قابلية المراقبة (observability guide) من Anthropic.

إصدارات SDK القديمة قد لا تدعم النماذج الأحدث. تُشير وثائق Anthropic إلى أن النماذج الحديثة قد تتطلب إصدار SDK حديث بسبب تغييرات في واجهة معامل التفكير (thinking-parameter API)، لذا قد يفشل SDK القديم مع نموذج جديد. راجع سجل التغييرات دائمًا وثبّت إصدارًا معروف الجودة عند تبني نماذج جديدة.

SDK مقابل CLI: أيهما تحتاج؟

بالنسبة لأغلب المطورين، الجواب هو كلاهما — وهذا مقصود بالتصميم.

تُعد الواجهة التفاعلية CLI الأداة المناسبة للتطوير اليومي: استكشاف قاعدة كود غير مألوفة، أو حل خطأ معقد بشكل تفاعلي، أو تشغيل إعادة هيكلة لمرة واحدة. أما SDK فهو الأداة المناسبة لأي شيء يحتاج للتشغيل دون وجود إنسان: CI، والمهام المُجدولة، وميزات التطبيق، وخطوط أنابيب الوكلاء المتعددين.

SDK وCLI ليسا منتجين متنافسين. تدفقات العمل التي تطوّرها بشكل تفاعلي باستخدام CLI تُترجم مباشرة إلى أتمتة SDK — نفس الأدوات، ونفس مفاهيم الأذونات، ونفس ذاكرة CLAUDE.md ونظام skills. تدفق عمل مراجعة تُنشئه كنموذج أولي باستخدام claude في طرفيتك اليوم يصبح روبوت CI مدعومًا بـ SDK غدًا.

للفرق التي تستخدم النسخة الويب من Claude Code (مُغطّاة في دليلنا حول Claude Code على الويب)، يفتح SDK الباب لدمج جلسات الويب مع التنظيم البرمجي — بدء مهمة طويلة الأمد من الويب، ثم ربطها برمجيًا من خلفيتك.

أسئلة شائعة

ما هو Claude Code SDK (Agent SDK) بالتحديد؟ هي مكتبة بلغتي Python (‏claude-agent-sdk) وTypeScript (‏@anthropic-ai/claude-agent-sdk) تعرض محرك Claude Code الوكيلي الكامل — الأدوات، والأذونات، وإدارة الجلسات، والوكلاء الفرعيين، وMCP — كـ API غير متزامن قابل للبرمجة. تستدعي query()، وتمرّر موجّهًا وخيارات، وتستقبل تدفق عمل الوكيل كأجسام رسائل مُصنّفة.

هل أحتاج إلى تثبيت Claude Code لاستخدام SDK؟ بالنسبة لـ SDK بلغة TypeScript، لا — تحتوي الحزمة على ملف ثنائي أصلي لـ Claude Code. بالنسبة لـ SDK بلغة Python، تتولى حزمة claude-agent-sdk هذه التبعية. تحتاج إلى مفتاح API من Anthropic من Anthropic Console.

هل يمكنني استخدام SDK مع نماذج أخرى غير Claude على API الخاصة بـ Anthropic؟ نعم. يدعم SDK Amazon Bedrock وGoogle Vertex AI وMicrosoft Azure AI Foundry وClaude Platform على AWS من خلال متغيرات البيئة. يمكنك أيضًا توجيه الطلبات عبر بروكسي مخصص بضبط ANTHROPIC_BASE_URL.

كيف أستخدم SDK في سير عمل GitHub Actions؟ أضِف مفتاح ANTHROPIC_API_KEY كسر (secret) في GitHub Actions، وأخرِج فرع PR في سير عملك، وثبّت حزمة SDK، وشغّل سكربت وكيلك. استخدم permissionMode: "dontAsk" مع قائمة allowedTools للقراءة فقط بحيث لا يستطيع الوكيل تعديل الملفات في بيئة CI الخاصة بك. تُغطّي وثائق Anthropic أيضًا تكاملًا مخصصًا مع GitHub Actions يُؤتمت مراجعة PR وفرز المشاكل (issue triage) دون كتابة كود SDK مخصص.

ما الفرق بين Agent SDK و Managed Agents؟ Agent SDK هو مكتبة تُشغّل حلقة الوكيل داخل عمليتك وبنيتك التحتية الخاصة. أما Managed Agents فهو API REST مُستضاف تُشغّل فيه Anthropic الوكيل والبيئة المحمية (sandbox) — أنت ترسل أحداثًا وتستقبل النتائج بشكل متدفق. SDK أفضل للنمذجة الأولية المحلية والوكلاء الذين يعملون مباشرة على نظام ملفاتك؛ وManaged Agents أفضل للإنتاج عندما لا تريد تشغيل بنية تحتية للحاويات.

كيف أحدّ من ما يمكن للوكيل الوصول إليه؟ استخدم allowedTools لتقييد الأدوات المتاحة، وpermissionMode: "dontAsk" لرفض أي شيء خارج تلك القائمة، وcwd لتحديد نطاق الوصول لنظام الملفات إلى دليل معيّن. للنشر متعدد المستأجرين، ضبط settingSources: [] وCLAUDE_CODE_DISABLE_AUTO_MEMORY=1 بالإضافة إلى ذلك.

هل يدعم SDK تدفق المخرجات (streaming)؟ نعم — يتدفق المُكرِّر غير المتزامن من query() الرسائل في الوقت الفعلي. إذا لم تحتج إلى مخرجات مباشرة (للمهام الخلفية أو خطوط أنابيب CI حيث تهتم فقط بالنتيجة النهائية)، تصف وثائق Anthropic نمط دور واحد (single-turn) يجمع كل الرسائل قبل العودة. راجع التدفق مقابل النمط ذو الدور الواحد في الوثائق الرسمية.

هل يمكنني تشغيل عدة وكلاء بالتوازي؟ نعم. كل استدعاء لـ query() يُشغّل عملية فرعية مستقلة. يمكنك تشغيل N جلسة متزامنة — لكن كل واحدة عملية منفصلة، فوفّر الذاكرة وفقًا لذلك وكن حذرًا من حدود معدل API. لعمليات توزيع الوكلاء الفرعيين المتزامنة من منسّق واحد، جمّع عمليات إرسالك في مجموعات لتجنب الاصطدام بحدود المعدل.

ماذا يحدث إذا تعطلت الجلسة في وسط المهمة؟ بشكل افتراضي، تكون نصوص الجلسة محلية للحاوية وتُفقد عند إعادة التشغيل. للنجاة من عمليات إعادة التشغيل، هيّئ محول SessionStore (S3 أو Redis أو Postgres) ومرّره في الخيارات. يمكنك بعدها استكمال الجلسة بواسطة session_id على حاوية جديدة.

تشغيل الوكلاء دون إعداد محلي

القيمة الأساسية لـ SDK هي الأتمتة — لكن تشغيل تلك الأتمتة يتطلب بنية تحتية حقيقية: بيئة تشغيل (runtime) بلغة Python أو Node، ومفتاح API، واستراتيجية حاويات، وقرار حماية (sandboxing)، ووقتًا يُصرف على نمذجة الأذونات قبل أول عملية نشر إنتاجية.

بالنسبة للمطورين الذين يريدون التكرار على أفكار الوكلاء دون هذا العبء الإعدادي، تُشغّل Happycapy وكلاء بأسلوب Claude Code مباشرة في المتصفح. لا يوجد تثبيت محلي، ولا إدارة عمليات فرعية، ولا توفير حاويات. تُقدّم أنت موجّهًا، وتتولى Happycapy بيئة التنفيذ — مع الوصول إلى أكثر من 150 نموذج وبيئة محمية سحابية آمنة. إنه مسار سريع للنمذجة الأولية لسلوك الوكيل الذي ستنقله لاحقًا إلى الإنتاج باستخدام SDK.

ابدأ مجانًا على happycapy.ai

أدلة ذات صلة

• Claude Code Hooks: دليل المستخدم المتقدم لأتمتة وكيلك
• كيف تعمل مراجعة Claude Code فعليًا: الاختلافات، وHooks، وما يكشفه الوكيل
• Claude Code Web: كيف تُشغّل Claude Code في متصفحك (بلا تثبيت)
• ما هي هندسة الأداة (Harness Engineering)؟ بناء أدوات وكلاء ذكاء اصطناعي موثوقة (2026)