تصميم واجهات برمجة التطبيقات (API) بأسلوب "الوكيل أولاً": كيف تبني APIs تفهمها وكلاء الذكاء الاصطناعي بالفعل

تم تصميم معظم واجهات برمجة التطبيقات (APIs) للمطورين البشر الذين يقرؤون الوثائق، ويتصفحون الأمثلة، ويقومون بتصحيح الأخطاء باستخدام تتبعات المكدس (stack traces). في عام 2026، تأتي حصة متزايدة من حركة مرور الـ API من وكلاء الذكاء الاصطناعي، وهم لا يتفاعلون مع هذه الواجهات بنفس الطريقة التي يتفاعل بها البشر.

هذه هي الطريقة التي أعدنا بها تصميم واجهة برمجة تطبيقات الذكاء الاصطناعي الموحدة من TokenLab بناءً على مبدأ واحد: لا تحاول أن تكون ذكياً، بل كن غنياً بالمعلومات. نحن نسمي النتيجة تصميم API الموجه للوكلاء (agent-first API design)، وقد قلل هذا التصميم من هدر الـ tokens لمستخدمينا بأكثر من 60%.

أبرز النقاط

• يضيف تصميم API الموجه للوكلاء تلميحات مهيكلة وقابلة للقراءة آلياً إلى استجابات الخطأ، بحيث يمكن لوكلاء الذكاء الاصطناعي تصحيح أنفسهم ذاتياً دون الحاجة إلى عمليات بحث على الويب أو مساعدة بشرية.
• اقترح بدائل، ولا تقم بالتصحيح التلقائي. حقول مثل did_you_mean وsuggestions وretryable تتيح للوكلاء اتخاذ قرارات مستنيرة بدلاً من اتخاذ القرار نيابة عنهم.
• كل اقتراح مبني على بيانات الإنتاج، لذا لا تظهر النماذج غير المتصلة أو التي تم إيقاف دعمها (deprecated) في قائمة المرشحين أبداً.
• حقول التلميحات هي حقول إضافية ومتوافقة مع الإصدارات السابقة، لذا تستمر العملاء المتوافقة مع OpenAI في العمل دون تغيير.

ما هو تصميم API الموجه للوكلاء؟

يعني تصميم API الموجه للوكلاء هيكلة استجاباتك، وخاصة استجابات الخطأ، بحيث يمكن لوكيل الذكاء الاصطناعي فهم ما حدث من خطأ وإصلاحه دون مغادرة المحادثة.

خطأ API التقليدي:

{"error": {"message": "Model not found"}}

خطأ API الموجه للوكلاء:

{
  "error": {
    "code": "model_not_found",
    "message": "Model 'gpt5.5' not found",
    "did_you_mean": "gpt-5.5",
    "suggestions": [{"id": "gpt-5.5"}, {"id": "gemini-3.5-flash"}],
    "hint": "Use GET /v1/models to list all available models."
  }
}

مع الـ API التقليدي، يضطر الوكيل للبحث في الويب، والعثور على الوثائق، وتحليل HTML، والتخمين. أما مع الـ API الموجه للوكلاء، فإنه يصحح نفسه في خطوة واحدة.

لماذا تفشل الـ APIs التقليدية مع وكلاء الذكاء الاصطناعي؟

شاهد ما يحدث عندما يصل وكيل إلى مجمع API نموذجي لأول مرة:

Agent: POST /v1/chat/completions {"model": "gpt5.5"}
API:   400 {"error": {"message": "Model not found"}}
Agent: (searches the web for "tokenlab models list")
Agent: (fetches a docs page, maybe the wrong one)
Agent: (parses HTML, finds a model name)
Agent: POST /v1/chat/completions {"model": "gpt-5.5"}
API:   200 ✓

ست خطوات، طلبات شبكة متعددة، ومئات الـ tokens المهدرة. وهذا في المسار المثالي، حيث صادف أن الوكيل خمن رابط الوثائق الصحيح.

مع التصميم الموجه للوكلاء:

Agent: POST /v1/chat/completions {"model": "gpt5.5"}
API:   400 {"did_you_mean": "gpt-5.5", "hint": "Use GET /v1/models..."}
Agent: POST /v1/chat/completions {"model": "gpt-5.5"}
API:   200 ✓

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

المبدأ الأساسي: الذكاء يبقى في جانب النموذج

الإغراء يكمن في بناء APIs "ذكية" تقوم بالتصحيح التلقائي لاسم النموذج، أو إعادة التوجيه بصمت إلى شيء مشابه، أو إضافة محرك توصيات. لقد رفضنا كل ذلك.

عندما يرسل الوكيل model: "gpt5.5"، فأنت لا تعرف في الواقع ما هي نيته. ربما يتحقق مما إذا كان هناك إصدار GPT أحدث. ربما لديه قيود ميزانية صارمة. ربما يحتاج إلى قدرة محددة لا يدعمها سوى نموذج واحد. إعادة التوجيه التلقائي إلى gpt-5.5 ستغير التكلفة والجودة والقدرات بصمت، ولن يعرف الوكيل أبداً أن ذلك قد حدث.

الخيار الأفضل هو الفشل السريع والفشل بوضوح. امنح الوكيل كل البيانات واتركه يقرر.

أربعة أنماط لتصميم API الموجه للوكلاء

النمط 1: النموذج غير موجود → اقتراحات تقريبية

{
  "error": {
    "code": "model_not_found",
    "did_you_mean": "gpt-5.5",
    "suggestions": [
      {"id": "gpt-5.5"},
      {"id": "gemini-3.5-flash"},
      {"id": "claude-sonnet-5"}
    ],
    "hint": "Did you mean 'gpt-5.5'? Use GET /v1/models to list all available models."
  }
}

يستخدم did_you_mean دقة من ثلاث طبقات: تعيين الأسماء المستعارة الثابتة من بيانات الإنتاج، ومطابقة السلاسل النصية الموحدة، ومسافة التعديل المحدودة. يتم التحقق من كل مرشح مقابل قائمة النماذج الحية، لذا لا نقترح أبداً نموذجاً غير متصل حالياً.

النمط 2: رصيد غير كافٍ → بدائل واعية بالميزانية

{
  "error": {
    "code": "insufficient_balance",
    "balance_usd": 0.12,
    "estimated_cost_usd": 0.35,
    "suggestions": [
      {"id": "gemini-3.5-flash", "estimated_cost_usd": 0.02},
      {"id": "deepseek-v4-flash", "estimated_cost_usd": 0.01}
    ],
    "hint": "Insufficient balance. Try a cheaper model or top up."
  }
}

بدلاً من مجرد قول "لا يوجد رصيد كافٍ"، نخبر الوكيل بالضبط كم لديه، وكم يحتاج، وأي النماذج يمكنه تحمل تكلفتها الآن. يمكن للوكيل الانتقال ذاتياً إلى نموذج ذكاء اصطناعي أرخص دون أي تدخل بشري. تحقق من الأسعار الحالية لكل نموذج على دليل نماذج TokenLab قبل برمجة حدود التكلفة.

النمط 3: فشل جميع القنوات → بدائل حية

{
  "error": {
    "code": "all_channels_failed",
    "retryable": true,
    "retry_after": 30,
    "alternatives": [
      {"id": "claude-sonnet-5", "status": "available"},
      {"id": "gpt-5.5", "status": "available"}
    ],
    "hint": "All channels for 'claude-opus-4-8' temporarily unavailable. Retry in 30s or try an alternative."
  }
}

قائمة alternatives ليست ثابتة. إنها استعلام مباشر مقابل بيانات صحة القنوات لدينا، لذا يحصل الوكيل على معلومات في الوقت الفعلي حول ما يعمل بالفعل الآن، وليس قائمة احتياطية مشفرة قد تكون قديمة.

النمط 4: تجاوز حد المعدل → توقيت إعادة المحاولة الدقيق

{
  "error": {
    "code": "rate_limit_exceeded",
    "retryable": true,
    "retry_after": 8,
    "limit": "1000/min",
    "remaining": 0,
    "hint": "Rate limited. Retry after 8s."
  }
}

لا تخمين، ولا تراجع أسي (exponential backoff) يبدأ من قيمة عشوائية. يعرف الوكيل وقت الانتظار الدقيق. لمزيد من المعلومات حول التعامل الجيد مع حدود المعدل، راجع دليل تحديد معدل الـ AI API الخاص بنا.

استجابات النجاح تحمل تلميحات أيضاً

عندما يستدعي الوكيل /v1/chat/completions باستخدام نموذج Claude، تتضمن الاستجابة:

X-TokenLab-Hint: This model supports native Anthropic format. Use POST /v1/messages for better performance.
X-TokenLab-Native-Endpoint: /v1/messages

نحن نخبر الوكيل: "لقد نجح هذا، ولكن هناك طريقة أفضل". يمكنه التبديل إلى نقطة النهاية الأصلية في الاستدعاء التالي والاستفادة من ميزات مثل التفكير الموسع (extended thinking) والتخزين المؤقت للمطالبات (prompt caching) التي لا يتم عرضها من خلال التنسيق المتوافق مع OpenAI.

تعيش هذه التلميحات في الترويسات (headers)، وليس في جسم الاستجابة، لأن الجسم يجب أن يتبع مواصفات OpenAI أو Anthropic بدقة. الترويسات هي نقطة التمديد الآمنة التي لن تكسر أي منطق تحليل موجود.

استجابة /v1/models كـ "ورقة غش" للوكيل

لقد أضفنا ثلاثة حقول لكل إدخال نموذج في استجابة /v1/models:

• category: نموذج محادثة، مولد صور، نموذج فيديو، أو صوت. لا مزيد من التخمين من الاسم.
• pricing_unit: لكل token، لكل صورة، لكل ثانية، أو لكل طلب. ضروري لأي تقدير تكلفة حقيقي.
• cache_pricing: أسعار التخزين المؤقت للمطالبات الأولية بالإضافة إلى خصم التخزين المؤقت الدلالي للمنصة.

بالاقتران مع الحقول الموجودة (التسعير، القدرات، الأسماء المستعارة، الحد الأقصى للـ tokens)، يمكن للوكيل إجراء اختيار مستنير تماماً للنموذج من استدعاء API واحد. يمكنك رؤية الكتالوج الحي الكامل في دليل نماذج TokenLab (تمت ملاحظته في 2026-07-07)، والذي يسرد حالياً أكثر من 300 نموذج عبر فئات المحادثة والصور والفيديو والصوت، بما في ذلك خيارات الحدود الحالية مثل Claude Sonnet 5 وGPT-5.5 وGemini 3.5 Flash. تحقق من الأسعار والتوافر الحالي على تلك الصفحة بدلاً من افتراض أن الأرقام في هذا المقال محدثة.

llms.txt: القراءة الأولى للوكيل

نحن نقدم ملف llms.txt ديناميكي على api.tokenlab.sh/llms.txt، وهو نظرة عامة قابلة للقراءة آلياً على كامل الـ API. يتضمن:

• قالب استدعاء أول مع كود يعمل
• أسماء النماذج الشائعة، التي يتم إنشاؤها تلقائياً من بيانات الاستخدام بدلاً من كونها مشفرة يدوياً
• جميع نقاط النهاية الـ 12 مع المعلمات
• معلمات التصفية لاكتشاف النماذج

الوكيل الذي يقرأ هذا الملف قبل استدعاء الـ API الأول له هو أكثر عرضة بكثير للحصول على الطلب الصحيح من المحاولة الأولى.

مدفوع بالبيانات، وليس مدفوعاً بالمعرفة

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

نحن نتتبع كل خطأ في النموذج في مجموعة مرتبة في Redis. بمجرد أن يتراكم عدد كافٍ من الزيارات لخطأ إملائي، يتم ترقيته إلى خريطة الأسماء المستعارة. عندما يصبح النموذج غير متصل، فإنه يسقط من كل قائمة اقتراحات تلقائياً. يقوم النظام بضبط نفسه بمرور الوقت بدلاً من أن يصبح قديماً، وهو أمر مهم عندما يتم إطلاق إصدارات نماذج جديدة مثل GPT-5.5 وClaude Sonnet 5 وGemini 3.5 Flash في جداول زمنية متداخلة.

قيد التصميم الذي جعل الأمر ينجح

وضعنا قاعدة واحدة: لا نقاط نهاية جديدة، لا SDKs جديدة، لا تغييرات جذرية. كان يجب أن يتناسب كل شيء داخل تنسيق الخطأ الحالي المتوافق مع OpenAI. الحقول الجديدة اختيارية، لذا فإن أي عميل يتجاهلها يحصل على نفس التجربة تماماً كما كان من قبل.

فرض هذا القيد دقة حول ما يساعد الوكيل حقاً على تصحيح نفسه، بدلاً من بناء APIs جديدة معقدة لن يكلف أحد نفسه عناء اعتمادها.

كيف تطبق تصميم "الموجه للوكلاء" على الـ API الخاص بك

إذا كنت تبني APIs سيستهلكها وكلاء الذكاء الاصطناعي:

1. اجعل كل خطأ قابلاً للتنفيذ. اذكر ما حدث من خطأ، ولماذا، وماذا يجب فعله بعد ذلك.
2. اقترح بدائل بدلاً من التصحيح التلقائي. دع الوكيل يتخذ القرار المستنير.
3. استخدم حقولاً مهيكلة، وليس نصوصاً سردية. did_you_mean قابلة للتحليل؛ أما "هل تقصد..." المدفونة في جملة فليست كذلك.
4. أسس الاقتراحات على بيانات حقيقية. أنماط استخدام الإنتاج تتفوق على قائمة مشفرة يدوياً تصبح قديمة.
5. قدم اكتشافاً قابلاً للقراءة آلياً من خلال llms.txt، أو مواصفات OpenAPI، أو قائمة نماذج مهيكلة.
6. حافظ على التوافق مع الإصدارات السابقة. يجب أن تكون حقول التلميحات الجديدة إضافية، ولا تكسر أي شيء أبداً.

من أين تبدأ دون إعادة كتابة كل شيء

معظم الفرق لا تحتاج إلى إعادة تصميم الـ API الخاص بها بالكامل في أسبوع واحد. نقطة بداية أصغر تعمل بشكل جيد:

1. أضف حقل تلميح واحد أو اثنين قابلين للقراءة آلياً إلى أكثر أخطائك تكراراً.
2. اجعل /v1/models أو نقطة نهاية الاكتشاف المكافئة لك أكثر ثراءً ووضوحاً.
3. انشر نظرة عامة واحدة قابلة للقراءة آلياً، مثل llms.txt.
4. اختبر الحلقة الكاملة مع عميل وكيل فعلي، وليس فقط curl.

إذا كنت تعمل بالفعل من خلال طبقة بوابة (gateway layer)، فإن دليل بوابة الذكاء الاصطناعي الموحدة يشرح سبب أهمية مستوى التحكم هذا. إذا كنت لا تزال تستخدم تكاملاً مباشراً متوافقاً مع OpenAI، فإن دليل الترحيل هو أسهل مكان للبدء قبل إضافة سلوك صديق للوكلاء.

الأسئلة الشائعة

ما هو تصميم API الموجه للوكلاء؟

إنه نهج تتضمن فيه استجابات الخطأ تلميحات مهيكلة وقابلة للقراءة آلياً (حقول مثل did_you_mean وsuggestions وhint) بحيث يمكن لوكلاء الذكاء الاصطناعي تصحيح أنفسهم دون تدخل بشري أو البحث في الوثائق.

كيف يختلف تصميم "الموجه للوكلاء" عن تصميم API "الموجه للمطورين"؟

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

هل يكسر تصميم "الموجه للوكلاء" العملاء الحاليين؟

لا. الحقول إضافية. العملاء الحاليون الذين لا يبحثون عن did_you_mean أو suggestions يتجاهلونها ببساطة ويستمرون في العمل تماماً كما كان من قبل.

---

توفر TokenLab وصولاً موحداً إلى أكثر من 300 نموذج ذكاء اصطناعي، بما في ذلك نماذج الحدود الحالية مثل GPT-5.5 وClaude Sonnet 5 وGemini 3.5 Flash، من خلال واجهة برمجة تطبيقات واحدة مدرجة في دليل النماذج. ابدأ مجاناً لاختبار الـ API الموجه للوكلاء مع رصيد بقيمة 1 دولار للبدء.