ما هو 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.

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

من بين أوضاع Claude الثلاثة — المحادثة والتعاون والبرمجة، يُعد Agent SDK التقنية الأساسية وراء وضع البرمجة (Claude Code).

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

جوهر 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

وكيل بسيط (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)
            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);
  }
}

هذا كل شيء — يكفي هذا القدر لتشغيل وكيل يقرأ الملفات ويبحث عن الأخطاء ويصلحها ويقدم تقريراً بالنتائج.

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

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

يكفي تحديد الأدوات في 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 وتُربط بالوكيل. النقطة المهمة: عند حدوث خطأ، لا تُلقِ استثناءً بل أعد isError: true. هذا يسمح لحلقة الوكيل بالاستمرار ويتيح لـ Claude تجربة نهج بديل.

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

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

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

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

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

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

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

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

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

Agent SDK vs Client SDK vs Claude Code

يوفر Claude ثلاث واجهات للمطورين، لكل منها نقاط قوة. اختر بحسب احتياجاتك.

كيف تختار:

• التطوير اليومي ← Claude Code CLI
• بناء نظام أتمتة ← Agent SDK
• تطوير تطبيق ذكاء اصطناعي مخصص ← Client SDK

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

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

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

# إصلاح تلقائي للأخطاء
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/max)
)

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

السماح بأدوات غير ضرورية يهدر نافذة السياق. حدد في allowed_tools الأدوات المطلوبة فعلاً للمهمة فقط.

3. عالج الأخطاء عبر isError

إلقاء استثناء من أداة مخصصة يوقف حلقة الوكيل بالكامل. بدلاً من ذلك، أعد isError: true لتتيح لـ Claude محاولة التعافي.

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

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

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

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

الخلاصة

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

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

للتعرف على الاستخدامات الأساسية لـ Claude، اطّلع أيضاً على مقال مقارنة تفصيلية بين أوضاع Claude الثلاثة: المحادثة والتعاون والبرمجة.