Claude Agent SDK 2026: الدليل الكامل (بناء وكلاء ذكاء اصطناعي في الإنتاج)

Claude Agent SDK من Anthropic هو الإطار الرسمي لبناء وكلاء (agents) ذكاء اصطناعي قادرين على استعمال أدوات حقيقية: قراءة ملفات، استدعاء APIs، تنفيذ أوامر، اتخاذ قرارات متعددة الخطوات. في هذا الدليل المرجعي لعام 2026، نشرح كيف تبني وكيلاً جاهزاً للإنتاج بالعربية، يخدم متجراً في القاهرة أو منصة استشارات في الرياض، بميزانية معقولة وأمان عالٍ.

1. ما هو Claude Agent SDK ولماذا الآن؟

SDK يلفّ Claude API بنمط Agent Loop: نموذج Claude يقرر، يستدعي أداة، يقرأ النتيجة، يقرر ثانيةً، يستدعي أداة أخرى، حتى يصل إلى الجواب النهائي. الإصدار 0.4.x (يناير 2026) يدعم: Tool Use، Sub-agents، Hooks، Permissions، Memory، Compaction، MCP servers، Prompt Caching. النموذج الأساسي للإنتاج: Claude Sonnet 4.6 (سرعة وسعر متوازن) أو Opus 4.7 للمهام الأعقد.

2. بنية الوكيل: المكونات الستة

1. System prompt: تعليمات الدور والقيود.
2. Tools: دوال JavaScript/Python ينفذها الوكيل.
3. Memory: محادثات سابقة + ذاكرة طويلة الأمد عبر vector DB.
4. Hooks: نقاط اعتراض قبل/بعد كل خطوة.
5. Permissions: ما الذي يحق للوكيل فعله بدون موافقة مستخدم.
6. MCP servers: امتدادات أدوات خارجية بروتوكول مفتوح.

3. أول وكيل عربي: مساعد دعم لمتجر إلكتروني

تثبيت SDK:

npm install @anthropic-ai/claude-agent-sdk
export ANTHROPIC_API_KEY=sk-ant-...

كود قاعدي:

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

const result = await query({
  prompt: "ابحث عن طلبات العميل أحمد محمد في آخر 30 يوماً",
  options: {
    model: 'claude-sonnet-4-6',
    systemPrompt: 'أنت مساعد دعم لمتجر إلكتروني في الرياض. تجيب بالعربية الفصحى المهذبة.',
    allowedTools: ['Bash', 'Read', 'Grep'],
    maxTurns: 8
  }
});
for await (const msg of result) console.log(msg);

4. أدوات (Tools) متخصصة لسوقك

SDK يحوّل أي دالة إلى Tool عبر تعريف JSON Schema. مثال: أداة تحقق من رصيد محفظة Wave/Orange Money:

const checkWalletBalance = {
  name: 'check_wallet_balance',
  description: 'التحقق من رصيد محفظة Wave أو Orange Money بناءً على رقم الهاتف',
  input_schema: {
    type: 'object',
    properties: { phone: { type: 'string' }, provider: { type: 'string', enum: ['wave', 'om', 'free_money'] } },
    required: ['phone', 'provider']
  },
  handler: async ({phone, provider}) => {
    return await fetchWalletApi(provider, phone);
  }
};

5. Sub-agents والتنسيق متعدد الوكلاء

وكيل رئيسي يستدعي وكلاء فرعيين متخصصين. مثال: وكيل تجارة إلكترونية يستدعي sub-agent للترجمة، آخر للحساب، ثالث للمحاسبة. كل sub-agent له system prompt و tools خاصة، ويتلقى مهمة محدودة. هذا يقلل من تلوث السياق ويحسن النتائج بنسبة 40-60% في مهامنا الفعلية.

6. Hooks: التحكم الدقيق في كل خطوة

Hooks تُكتب بـ shell أو Node أو Python عبر settings.json.

7. الذاكرة طويلة الأمد عبر MCP + Vector DB

اربط الوكيل بـ MCP server خاص يستعمل Qdrant أو pgvector على PostgreSQL ذاتي الاستضافة على Hetzner (28 €/شهر). كل محادثة جديدة تستفيد من تاريخ الاستفسارات السابقة. هذا أساسي لمنصة استشارات قانونية في الدار البيضاء أو منصة طبية في الرياض.

8. الأمان وحماية البيانات

• لا ترسل أبداً بيانات مالية حساسة (أرقام بطاقات Mada/CIB/CMI) إلى Claude. شفّرها على مستوى التطبيق.
• التزم بـ SDAIA السعودية، CDP السنغال، ARTCI كوت ديفوار، NESA الإمارات.
• استعمل Hooks لمنع تنفيذ أوامر مدمرة (rm، delete from).
• سجّل كل استدعاء أداة لـ Loki + Grafana للتدقيق.
• قيّد عدد maxTurns و maxTokens لكل وكيل.

9. التكلفة وإدارة الميزانية

Sonnet 4.6 = 3$ لكل مليون token دخل، 15$ خرج. Opus 4.7 = 15$/75$. باستعمال Prompt Caching تنخفض التكلفة 90% للسياقات المتكررة. وكيل دعم متجر إلكتروني متوسط (1500 محادثة شهرياً، 3000 token متوسط) يكلف ~25-40 USD/شهر. ضع حداً يومياً عبر API Keys منفصلة لكل بيئة.

10. الأخطاء الشائعة

11. أسئلة متكررة

هل يعمل Claude Agent SDK مع Python؟ نعم، توجد claude-agent-sdk للبايثون بنفس الميزات.

هل أحتاج خادماً ذاتي الاستضافة؟ SDK يعمل في Node/Python على أي خادم. للذاكرة طويلة الأمد، MCP + pgvector على VPS صغير كافٍ.

كم وكيلاً متوازياً يستوعب SDK؟ محدد بحدود API: 50 طلب/دقيقة افتراضياً، يرفع لمئات في خطط أعلى.

للاستزادة

• بناء وكيل مخصص مع Claude SDK
• بناء MCP server مخصص
• تنسيق Sub-agents
• Hooks والصلاحيات