تصميم الـ API بمنهجية Agent-First: كيف تبني APIs تفهمها الـ AI Agents حقاً

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

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

ما هو تصميم API الموجه للعملاء الآليين (Agent-First)؟

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

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

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

خطأ API الموجه للعملاء الآليين (Agent-first):

{
  "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 ✓

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

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

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

عندما يرسل الوكيل 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 دقة ثلاثية الطبقات: تعيين الأسماء المستعارة الثابتة من بيانات الإنتاج، ومطابقة السلاسل النصية المعيارية، ومسافة التحرير المحدودة (edit distance). يتم التحقق من جميع المرشحين مقابل قائمة النماذج المباشرة، لذا لا نقترح أبداً نموذجاً غير متصل بالإنترنت حالياً.

النمط 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: تجاوز حد المعدل (Rate Limited) ← توقيت إعادة المحاولة الدقيق

{
  "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-LemonData-Hint: This model supports native Anthropic format. Use POST /v1/messages for better performance.
X-LemonData-Native-Endpoint: /v1/messages

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

إذا كنت تبني واجهات برمجة تطبيقات سيستهلكها وكلاء الذكاء الاصطناعي:

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

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

معظم الفرق لا تحتاج إلى إعادة تصميم الـ API بالكامل في أسبوع واحد.

نقطة البداية العملية أصغر:

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

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

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

ما هو تصميم API الموجه للعملاء الآليين (Agent-first)؟

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

كيف يختلف Agent-first عن تصميم API الموجه للمطورين (Developer-first)؟

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

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

لا. حقول Agent-first إضافية، مما يعني أن العملاء الحاليين يمكنهم تجاهلها والاستمرار في العمل دون تغيير.

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

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

---

توفر LemonData وصولاً موحداً إلى أكثر من 300 نموذج ذكاء اصطناعي من خلال API واحد. جربه مجاناً لاختبار Agent-first API مع رصيد تجريبي بقيمة 1 دولار.