ما هو Claude Agent SDK؟ دليل شامل لتطوير وكلاء الذكاء الاصطناعي

"أعطِ الأمر للذكاء الاصطناعي ودعه يتولى الباقي بنفسه..." هذا بالضبط ما يحققه وكيل الذكاء الاصطناعي. يُعد Claude Agent SDK من Anthropic مكتبة لبناء وكلاء ذكاء اصطناعي باستخدام Python أو TypeScript، حيث يكون Claude هو العقل المدبّر. وهي تضع في برامجك الأدوات نفسها وحلقة الوكيل نفسها وإدارة السياق نفسها التي يعمل بها Claude Code — وكيل البرمجة الرسمي من Anthropic.

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

ما هو وكيل الذكاء الاصطناعي؟

يختلف وكيل الذكاء الاصطناعي جوهرياً عن نمط "السؤال والجواب" التقليدي. ميزته الأساسية هي تقسيم المهام بشكل مستقل، واستخدام الأدوات، وتحليل النتائج، واتخاذ القرارات بشأن الخطوات التالية.

على سبيل المثال، عندما تطلب من الوكيل "إصلاح الخلل في auth.py"، فإنه يقوم بالخطوات التالية:

1. قراءة الملف وفهم الكود
2. البحث عن الملفات المرتبطة لاستيعاب الصورة الكاملة
3. تحديد سبب الخطأ
4. تعديل الكود
5. تشغيل الاختبارات للتحقق
6. تقديم تقرير بالنتائج

كل هذا يتم دون تدخل بشري — يتخذ الوكيل القرارات في كل مرحلة بشكل مستقل. هذه هي قوة الوكيل.

نظرة عامة على Claude Agent SDK

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

الميزات الرئيسية:

يتيح لك Agent SDK أن تأخذ الوكيل الذي يعمل في الكود (Claude Code) في Claude وتدمجه في تطبيقاتك وسكربتاتك الخاصة خارج تلك الواجهة.

كيف تعمل حلقة الوكيل

جوهر Agent SDK هو حلقة الوكيل — آلية تدير تلقائياً دورة "يفكر Claude، يستخدم أداة، يتحقق من النتيجة، ثم يفكر مجدداً".

تسير العملية كالتالي:

1. استقبال الطلب: تمرير تعليمات المستخدم إلى Claude
2. تحليل Claude: تحليل التعليمات وتحديد الإجراءات اللازمة
3. تنفيذ الأداة: استدعاء أدوات مثل Bash وEdit وRead لتنفيذ العمل
4. معالجة النتيجة: إعادة نتيجة التنفيذ إلى Claude
5. الاستمرار أو الانتهاء: إذا كان هناك المزيد من العمل، العودة للخطوة 2؛ وإلا يُعاد رد نصي نهائي

النقطة الجوهرية: تنتهي الحلقة عندما لا تعود هناك حاجة لاستدعاء الأدوات. بمجرد أن يقرر Claude أنه لم يعد بحاجة لأي أداة، يعود بالرد النصي النهائي.

البداية: التثبيت والكود الأساسي

التثبيت

متاح لكل من Python وTypeScript.

# Python
pip install claude-agent-sdk

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

يتطلب ذلك Node.js 18 أو أحدث، أو Python 3.10 أو أحدث (دليل البدء السريع الرسمي).

المصادقة: استخدم مفتاح API (وليس تسجيل الدخول إلى claude.ai)

يعمل الـ SDK بمفتاح API المضبوط في متغير البيئة ANTHROPIC_API_KEY. وإذا أردت العمل عبر Amazon Bedrock أو Google Cloud (النسخة التي تشغّلها Google) أو Microsoft Foundry، فاضبط CLAUDE_CODE_USE_BEDROCK=1 أو CLAUDE_CODE_USE_VERTEX=1 أو CLAUDE_CODE_USE_FOUNDRY=1 على التوالي، وجهّز بيانات اعتماد تلك السحابة. لا يقرأ الـ SDK ملفات .env تلقائياً، لذا اضبط المتغير في الصدفة (shell) التي يعمل فيها الوكيل. وشرحنا خطوات استخدام Claude على Google Cloud وأسعاره في مقال طريقة استخدام Claude على Vertex AI.

انتبه إلى مسألة تسجيل الدخول إلى claude.ai (اشتراكات Pro وMax وغيرها). فما لم تحصل على موافقة مسبقة، لا تسمح الوثائق الرسمية للمطورين الخارجيين بأن يقدّموا في منتجاتهم تسجيل الدخول إلى claude.ai أو حدود استخدامه، بما في ذلك الوكلاء المبنيون على Agent SDK. أما التطبيقات التي تبنيها بالـ SDK فيجب أن تُصادَق بمفتاح API.

وكيل بسيط (Python)

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

async def main():
    async for message in query(
        prompt="ابحث عن الخلل في src/auth.py وأصلحه",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Bash", "Grep"],
            max_turns=30,
        ),
    ):
        if isinstance(message, ResultMessage):
            if message.subtype == "success":
                print(message.result)
            if message.total_cost_usd is not None:
                print(f"التكلفة: ${message.total_cost_usd:.4f}")

asyncio.run(main())

وكيل بسيط (TypeScript)

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

for await (const message of query({
  prompt: "ابحث عن الخلل في src/auth.py وأصلحه",
  options: {
    allowedTools: ["Read", "Edit", "Bash", "Grep"],
    maxTurns: 30,
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

هذا كل شيء — يكفي هذا القدر لتشغيل وكيل يقرأ الملفات ويبحث عن الأخطاء ويصلحها ويقدم تقريراً بالنتائج. لكن انتبه: allowed_tools ليست قائمة الأدوات المسموح لـ Claude باستخدامها، بل قائمة الأدوات التي تُعتمد تلقائياً دون سؤال. ولأن هذا المثال يتضمن Bash، فإن أوامر الصدفة التي يختارها Claude تُنفَّذ دون تأكيد (باستثناء عمليات قليلة، مثل بعض عمليات الحذف، لا يعتمدها أي إعداد تلقائياً). ولأن هذا المثال لا يحدد permission_mode، يُؤخذ الوضع من permissions.defaultMode في ملفات الإعدادات، وإلا فمن القيمة الافتراضية المدمجة، وكانت تلك القيمة منذ الإصدار v2.1.285 هي auto في الجلسات التي لا تجلب feature flags، كما مع مزوّد خارجي (Bedrock أو Google Cloud أو Microsoft Foundry) أو عند إيقاف القياس عن بُعد (الوثائق الرسمية). غير أن الإصدار v2.1.302 (16 أكتوبر 2026) غيّر ذلك: صارت جلسات Agent SDK وclaude -p التي لا تحدد وضع الأذونات تبدأ بوضع default، حتى عبر المزوّدين الخارجيين. ولتشغيل auto يلزم التحديد صراحةً (في CLI: --permission-mode auto؛ سجل التحديثات، تم التحقق منه في 18 أكتوبر 2026). ووضع auto يُسقط قواعد السماح الواسعة مثل Bash، لذا إن كنت تعتمد على السلوك أعلاه فمرّر permission_mode="default" (TS: permissionMode: "default") صراحةً (الوثائق الرسمية). جرّبه في مجلد عمل لا يضرك أن يتلف. ويشرح القسم التالي كيف تقيّد الأدوات فعلاً.

الأدوات المدمجة

يأتي Agent SDK مع مجموعة من الأدوات الجاهزة للاستخدام دون الحاجة لكتابة كود إضافي.

لا تحتاج إلى كتابة كود لمعالجة الأدوات المدمجة. المهم أن تعرف أن "أي الأدوات يراها Claude" و"أي الأدوات تعمل دون سؤال" إعدادان منفصلان. يلخّص الجدول التالي ما تقوله الوثائق الرسمية:

فمثلاً، إذا جمعت allowed_tools=["Read"] مع permission_mode="bypassPermissions" فسيُعتمد كل شيء، بما في ذلك Bash وWrite وEdit غير المذكورة في القائمة (وتحذّر الوثائق الرسمية صراحةً من هذا الجمع). ولإبعاد أداة عن متناول Claude، أزلها عبر tools أو disallowed_tools. وإذا أردت العمل بمجموعة ثابتة من الأدوات فقط، فاجمع allowed_tools مع permission_mode="dontAsk" الذي يرفض كل ما كان سيطلب تأكيداً.

ملاحظة أخرى: في macOS وLinux وWSL لا تدخل Glob وGrep ضمن الأدوات الافتراضية (بخلاف Windows). وفي هذه الأنظمة يبحث Claude باستخدام find وgrep عبر أداة Bash. وتعود الأداتان إذا ذكرت أياً منهما في tools أو allowed_tools (مرجع الأدوات الرسمي).

إنشاء أدوات مخصصة

عندما لا تكفي الأدوات المدمجة، يمكنك إنشاء أدوات خاصة. إليك مثالاً على التكامل مع واجهة برمجة تطبيقات الطقس.

نسخة Python

from claude_agent_sdk import tool, create_sdk_mcp_server

@tool(
    "get_weather",
    "الحصول على حالة الطقس الحالية لمدينة محددة",
    {"city": str}
)
async def get_weather(args: dict) -> dict:
    city = args["city"]
    # في التطبيق الفعلي يتم استدعاء API
    weather_data = await fetch_weather_api(city)
    return {
        "content": [
            {"type": "text", "text": f"الطقس في {city}: {weather_data}"}
        ]
    }

weather_server = create_sdk_mcp_server(
    name="weather",
    version="1.0.0",
    tools=[get_weather]
)

نسخة TypeScript

import { tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";

const getWeather = tool(
  "get_weather",
  "الحصول على حالة الطقس الحالية لمدينة محددة",
  { city: z.string().describe("اسم المدينة") },
  async (args) => {
    const data = await fetchWeatherApi(args.city);
    return {
      content: [{ type: "text", text: `الطقس في ${args.city}: ${data}` }]
    };
  }
);

تُنشأ الأدوات المخصصة كخوادم MCP وتُمرَّر إلى الوكيل عبر mcp_servers (TS: mcpServers). ويصبح الاسم الكامل لكل أداة بالصيغة mcp__اسم-الخادم__اسم-الأداة، فإذا أردت أن تعمل دون سؤال فأضف هذا الاسم إلى allowed_tools:

options=ClaudeAgentOptions(
    mcp_servers={"weather": weather_server},
    allowed_tools=["mcp__weather__get_weather"],
)

إذا ألقت أداتك استثناءً، فلن تتوقف حلقة الوكيل. إذ يلتقط خادم MCP التابع للـ SDK الاستثناء ويسلّم رسالته كما هي إلى Claude على شكل نتيجة خطأ. أما إذا التقطت الخطأ بنفسك وأعدت "is_error": True (في TypeScript: isError: true)، فستكتب أنت الرسالة التي يقرؤها Claude: أي طلب فشل، وما الذي يمكن تجربته بدلاً منه. وفي الحالتين يستطيع Claude إعادة المحاولة أو تجربة أداة أخرى أو شرح سبب الفشل (الوثائق الرسمية: الأدوات المخصصة).

المعالجة المتوازية بالوكلاء الفرعيين

من الأكفأ تقسيم المهام الكبيرة إلى وكلاء فرعيين وتنفيذها بالتوازي. هذا يحافظ على نظافة سياق (ذاكرة) الوكيل الرئيسي مع تفويض المهام المتخصصة لوكلاء مستقلين.

متى تكون الوكلاء الفرعيون مفيدة

• تشغيل اختبارات واسعة النطاق: حتى لو كانت سجلات الاختبار ضخمة، فلن تؤثر على سياق الوكيل الرئيسي
• البحث المتوازي: تحليل عدة وحدات برمجية في آنٍ واحد واستقبال النتائج فقط
• فصل المسؤوليات: تعيين "مراجعة الكود" و"تشغيل الاختبارات" لوكلاء مختلفين

وكلاء فرعيون مخصصون في Claude Code

في Claude Code (CLI)، يكفي وضع ملف Markdown في مجلد .claude/agents/ لتعريف وكيل فرعي مخصص.

# .claude/agents/reviewer.md
---
name: code-reviewer
description: وكيل متخصص في مراجعة الكود
tools: Read, Glob, Grep
model: sonnet
---

أنت مراجع كود خبير.
قم بالمراجعة من حيث جودة الكود
والأمان وأفضل الممارسات.

تقييد الأدوات المتاحة (في المثال أعلاه: أدوات القراءة فقط) يمنع المراجع من تعديل الكود عن طريق الخطأ.

الأذونات والخطافات والجلسات

هذه الثلاثة هي الأهم حين يعمل الوكيل في بيئة الإنتاج. وتذكرها الوثائق الرسمية جميعاً ضمن قدرات Claude Code المتاحة في الـ SDK.

الأذونات: كل استدعاء يُفحص بترتيب ثابت

عندما يطلب Claude أداة، يفحص الـ SDK بالترتيب: الخطافات ← قواعد الرفض ← قواعد السؤال ← وضع الأذونات ← قواعد السماح ← دالة can_use_tool. والاستدعاء الذي يطابق قاعدة رفض (من disallowed_tools مثلاً) يُحجب حتى في وضع bypassPermissions. والاستثناء هو الـ mod (إضافة تُكتب خطافاتها كدوال): فهو يعمل أيضاً في جلسات Agent SDK التي تحمّله (الوثائق الرسمية)، والـ mod الذي يجيب عن tool.check يستطيع اعتماد استدعاء رفضته قاعدة رفض، إلا على الأجهزة التي فيها إعدادات مُدارة أو عند تسجيل الدخول بخطة Team أو Enterprise (الوثائق الرسمية). لا تثبّت إلا mods من مؤلفين تثق بهم؛ وللتفاصيل راجع شرح الـ mods في Claude Code. ويُختار الوضع عبر permission_mode (بحسب الوثائق الرسمية في سبتمبر 2026):

الخطافات: شغّل كودك الخاص في لحظات محددة

الخطافات (hooks) دوال استدعاء تعمل عند أحداث مثل ما قبل تشغيل أداة (PreToolUse) أو ما بعده (PostToolUse) أو عند توقف التنفيذ (Stop). وهي تعمل قبل فحص الأذونات، لذا فالعملية التي تريد حجبها في كل الأوضاع مكانها هنا. يحجب المثال التالي (وهو نسخة مختصرة من مثال في الوثائق الرسمية) الكتابة في ملفات .env:

from claude_agent_sdk import ClaudeAgentOptions, HookMatcher

async def protect_env_files(input_data, tool_use_id, context):
    file_path = input_data["tool_input"].get("file_path", "")
    if file_path.split("/")[-1] == ".env":
        return {
            "hookSpecificOutput": {
                "hookEventName": input_data["hook_event_name"],
                "permissionDecision": "deny",
                "permissionDecisionReason": "Cannot modify .env files",
            }
        }
    return {}

options = ClaudeAgentOptions(
    hooks={"PreToolUse": [HookMatcher(matcher="Write|Edit", hooks=[protect_env_files])]}
)

الجلسات: أكمل من حيث توقفت أو تفرّع

يحفظ الـ SDK تلقائياً على القرص سجلّ المحادثة (المطالبات واستدعاءات الأدوات والنتائج والردود) على شكل جلسة. احتفظ بـ session_id من رسالة النتيجة ومرّره إلى resume في استدعاء query() التالي، فيكمل الوكيل عمله وهو يأخذ في الحسبان الملفات التي قرأها والقرارات التي اتخذها. ولمتابعة أحدث جلسة استخدم continue_conversation=True (TS: continue: true)، ولتجربة نهج آخر مع إبقاء الجلسة الأصلية كما هي استخدم fork_session=True (TS: forkSession: true). الجلسات تحفظ المحادثة فقط، ولا تُتراجَع تغييرات الملفات (الوثائق الرسمية: الجلسات).

إلى جانب ذلك، تُحمَّل تلقائياً المهارات (skills) والأوامر والذاكرة الموجودة في مجلد .claude/ الخاص بمشروعك وفي ~/.claude/، تماماً كما في Claude Code. كما يمكن تحميل الإضافات (plugins) التي تجمع المهارات والوكلاء والخطافات وخوادم MCP من مسار محلي.

Agent SDK vs Client SDK vs Claude Code

تعدّد المقارنة الرسمية أربع طرق للبناء باستخدام Claude: Agent SDK وClaude Code CLI وClient SDK وManaged Agents. ولنبدأ بالثلاث التي تشغّلها على جهازك أو خوادمك.

كيف تختار:

• التطوير اليومي ← Claude Code CLI
• بناء نظام أتمتة ← Agent SDK
• تطوير تطبيق ذكاء اصطناعي مخصص ← Client SDK
• تفويض تشغيل الحلقة والبيئة المعزولة أيضاً ← Managed Agents (وكيل تستضيفه Anthropic، تعمل جلساته في بيئة معزولة سحابية تديرها Anthropic أو في بيئة معزولة على بنيتك التحتية، ويُستخدم عبر SDK لغتك أو أداة ant أو REST API)

سيناريوهات الاستخدام العملية

أتمتة تطوير الكود

هذا هو الاستخدام الأكثر شيوعاً. يكفي أن تقول "نفّذ هذه الميزة"، وسيقوم الوكيل بفحص بنية الملفات وكتابة الكود وتشغيل الاختبارات.

# إصلاح تلقائي للأخطاء
async for msg in query(
    prompt="اختبارات وحدة المصادقة تفشل. اعثر على السبب وأصلحه",
    options=ClaudeAgentOptions(
        allowed_tools=["Read", "Edit", "Bash", "Grep"],
        max_turns=20,
        max_budget_usd=2.00,  # حد التكلفة $2
    ),
):
    pass

الدمج في خط أنابيب CI/CD

يمكن الربط مع GitHub Actions لإجراء مراجعة تلقائية للكود عند إنشاء طلب سحب (PR)، أو محاولة الإصلاح التلقائي عند فشل الاختبارات.

تحليل البيانات والبحث

"حلّل سجلات الشهر الماضي وحدد أنماط الأخطاء" — مهام البحث متعددة الخطوات كهذه يمكن تفويضها للوكيل. وبدمج أداة WebSearch يمكن أيضاً الحصول على أحدث المعلومات.

أفضل الممارسات

1. لا تنسَ التحكم في التكاليف

يعمل الوكيل بشكل دوري، لذا قد يستهلك رموزاً (tokens) أكثر مما تتوقع. احرص دائماً على تعيين max_budget_usd وmax_turns.

options=ClaudeAgentOptions(
    max_budget_usd=5.00,   # التوقف عند $5
    max_turns=30,           # التوقف بعد 30 دورة
    effort="medium",        # عمق التفكير (low/medium/high/xhigh/max)
)

في النماذج التي لا تدعم xhigh يُعامَل على أنه high. وعندما يُنهي حدٌّ ما التشغيل، تكون قيمة subtype في رسالة النتيجة الأخيرة "error_max_budget_usd" عند بلوغ max_budget_usd أو "error_max_turns" عند بلوغ max_turns، ويكون result فارغاً (None). ومن subtype تعرف سبب توقف الوكيل.

تذكّر أن هذا المبلغ تقدير يحسبه الـ SDK من جدول أسعار مضمّن، وليس فاتورتك الفعلية. والميزانية لا تحتسب إلا إنفاق الاستدعاء نفسه، فلا يدخل فيها ما أُنفق سابقاً في جلسة استأنفتها عبر resume. وللأرقام الدقيقة، راجع صفحة Usage في Claude Console أو Usage and Cost API (الوثائق الرسمية: تتبّع التكلفة).

2. قلّل الأدوات إلى الحد الأدنى

لكي لا يرى Claude الأدوات غير الضرورية أصلاً، اذكر في tools الأدوات التي تحتاجها فقط، أو أزل الأدوات بأسمائها في disallowed_tools. أما allowed_tools فتلغي السؤال فقط ولا تقلّص الأدوات المتاحة. واجعل قائمة الاعتماد التلقائي أيضاً في الحد الأدنى الذي تحتاجه المهمة.

3. أبلغ عن أخطاء الأدوات عبر is_error

الاستثناء داخل أداة مخصصة لا يوقف حلقة الوكيل، إذ يمرّر الـ SDK رسالة الاستثناء إلى Claude على شكل نتيجة خطأ. لكن رسالة الاستثناء الخام لا تكفي Claude دائماً ليقرر خطوته التالية. التقط الاستثناء بنفسك وأعد "is_error": True (في TypeScript: isError: true) مع وصف لما فشل وما يمكن تجربته بدلاً منه، فيسهل على Claude التعافي.

4. فوّض المهام الثقيلة للوكلاء الفرعيين

تشغيل الاختبارات وتحليل السجلات وغيرها من العمليات ذات المخرجات الكبيرة يفضّل تفويضها لوكلاء فرعيين لتجنب إرهاق سياق الوكيل الرئيسي.

5. اجعل التعليمات محددة

بدلاً من "حسّن الكود"، اكتب "أضف تحديداً لمعدل الطلبات في دالة تسجيل الدخول بملف auth.py واكتب اختبارات". التعليمات المحددة تجعل الوكيل يعمل بكفاءة أعلى.

الخلاصة

يُخفّض Claude Agent SDK بشكل كبير حاجز الدخول لتطوير وكلاء الذكاء الاصطناعي. باستخدام نفس المحرك الذي يشغّل Claude Code، يمكنك بناء وكلاء مستقلين بلغة Python أو TypeScript.

المنهج المقترح: ابدأ بتجربة Claude Code للتعرف التفاعلي على إمكانيات الوكلاء، وعندما تحتاج للأتمتة انتقل إلى Agent SDK.

وإذا كنت تفضّل عدم إدارة الحلقة والبيئة المعزولة والحالة بنفسك، فإن البديل المُدار بالكامل من Anthropic هو Claude Managed Agents.

للتعرف على الاستخدامات الأساسية لـ Claude، اطّلع أيضاً على مقال الفرق بين دردشة Claude وCowork والكود.