تصميم API الموجه للعملاء الآليين أولاً: كيف تبني واجهات برمجة تطبيقات تفهمها وكلاء الذكاء الاصطناعي حقاً

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

هذه هي قصة كيف أعدنا تصميم LemonData's unified AI API بناءً على مبدأ بسيط: لا تكن ذكياً، بل كن غنياً بالمعلومات. والنتيجة هي ما نسميه تصميم API الموجه للعملاء الآليين أولاً (agent-first API design) — وقد أدى ذلك إلى تقليل التوكنات (tokens) المهدرة لمستخدمينا بنسبة تزيد عن 60%.

ما هو تصميم API الموجه للعملاء الآليين أولاً؟

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

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

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

خطأ API الموجه للعملاء الآليين أولاً:

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

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

لماذا تفشل واجهات برمجة التطبيقات التقليدية مع وكلاء الذكاء الاصطناعي

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

Agent: POST /v1/chat/completions {"model": "gpt5"}
API:   400 {"error": {"message": "Model not found"}}
Agent: (searches the web for "lemondata 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-4o"}
API:   200 ✓

ست خطوات. طلبات شبكة متعددة. مئات التوكنات (tokens) المهدرة. وهذا هو المسار السعيد — حيث خمن الوكيل رابط التوثيق الصحيح.

مع تصميم agent-first:

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

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

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

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

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

الخطوة الصحيحة هي الفشل السريع والفشل المعلوماتي. امنح الوكيل كل البيانات. واتركه يقرر.

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

النمط 1: النموذج غير موجود ← اقتراحات مرنة (Fuzzy Suggestions)

{
  "error": {
    "code": "model_not_found",
    "did_you_mean": "gpt-4-turbo",
    "suggestions": [
      {"id": "gpt-4o"},
      {"id": "gpt-4o-mini"},
      {"id": "claude-sonnet-4-5"}
    ],
    "hint": "Did you mean 'gpt-4-turbo'? 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": "gpt-4o-mini", "estimated_cost_usd": 0.02},
      {"id": "deepseek-chat", "estimated_cost_usd": 0.01}
    ],
    "hint": "Insufficient balance. Try a cheaper model or top up."
  }
}

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

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

{
  "error": {
    "code": "all_channels_failed",
    "retryable": true,
    "retry_after": 30,
    "alternatives": [
      {"id": "claude-sonnet-4-5", "status": "available"},
      {"id": "gpt-4o", "status": "available"}
    ],
    "hint": "All channels for 'claude-opus-4-6' 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."
  }
}

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

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

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

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

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

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

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

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

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

بالاقتران مع الحقول الموجودة (التسعير، القدرات، الأسماء المستعارة، الحد الأقصى للتوكنات)، يمكن للوكيل اتخاذ قرارات اختيار نموذج مستنيرة تماماً من مكالمة API واحدة.

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

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

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

الوكيل الذي يقرأ هذا الملف قبل مكالمة API الأولى سيحصل على الأرجح على النتيجة الصحيحة من المحاولة الأولى.

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

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

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

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

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

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

كيف تطبق تصميم Agent-First على API الخاص بك

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

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

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

ما هو تصميم API الموجه للعملاء الآليين أولاً؟

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

كيف يختلف تصميم agent-first عن تصميم API الموجه للمطورين أولاً؟

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

هل يكسر تصميم agent-first العملاء الحاليين؟

لا. حقول agent-first هي إضافية — حقول زائدة في استجابة JSON. العملاء الذين لا يعرفون عنها يتجاهلونها ببساطة. تستمر التكاملات الحالية في العمل دون تغيير.

كيف تطبق LemonData تصميم agent-first؟

تضيف بوابة LemonData الموحدة لـ AI API تلميحات أخطاء منظمة لجميع النماذج التي تزيد عن 300 نموذج. تتضمن كل استجابة خطأ اقتراحات قابلة للتنفيذ، وتوفر نقطة نهاية llms.txt اكتشافاً لـ API مقروءاً آلياً.

---

توفر LemonData وصولاً موحداً إلى أكثر من 300 نموذج ذكاء اصطناعي من خلال API واحد. جرب API الموجه للعملاء الآليين أولاً في lemondata.cc.