أدوات API

يأخذك هذا الدليل عبر إنشاء أداة API يقدر وكلاؤك الأذكياء استخدامها للتفاعل مع أنظمة خارجية.

ما هي أدوات API؟

تتيح أدوات API لوكيلك الذكي الاتصال بأنظمة خارجية وتنفيذ إجراءات نيابة عن العملاء:

الاستعلامات: التحقق من حالة الطلب، عرض رصيد الحساب، إيجاد توفر المنتج
الإجراءات: إنشاء طلبات، تحديث معلومات العميل، تشغيل سيناريوهات
التكاملات: الاتصال بـ CRMs، ERPs، أنظمة الدفع، واجهات API للشحن

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

الوصول إلى أدوات API

اذهب إلى التكاملات في الشريط الجانبي
اضغط على واجهات API — تفتح صفحة My APIs
اضغط على Create New API لإنشاء أداة جديدة

أقسام النموذج

المعلومات الأساسية

الحقل	الوصف	المتطلبات
عنوان الأداة	اسم داخلي للأداة (يُعرَض للذكاء الاصطناعي)	3 إلى 55 حرفاً، يبدأ بحرف، أحرف وأرقام وشرطات سفلية فقط
الوصف	يشرح ما تفعله هذه الأداة — يستخدمه الذكاء الاصطناعي ليقرر متى يستدعيها	10 إلى 5000 حرف

أمثلة على عناوين أدوات جيدة:

get_order_status
create_support_ticket
check_inventory

نصيحة: اكتب الوصف كأنك تشرح لمساعد بشري متى يستخدم هذه الأداة.

وصف جيد:

"يسترجع تفاصيل الطلب بما في ذلك الحالة، العناصر، ومعلومات الشحن بحسب معرّف الطلب. استخدم لما يسأل العميل عن حالة طلبه، التتبع، أو التوصيل."

غامض جداً:

"احصل على معلومات الطلب"

ضبط الـ API

الحقل	الوصف	مثال
الرابط الأساسي	الرابط الجذر للواجهة (يجب أن يكون عاماً بـ HTTPS/HTTP)	`https://api.yourcrm.com`
الطريقة	طريقة HTTP: GET, POST, PUT, DELETE	GET للاسترداد، POST للإنشاء
قالب نقطة النهاية	مسار الـ API (يقدر يتضمن متغيرات)	`/orders/{{order_id}}`

مهم: يجب أن يكون الرابط الأساسي قابلاً للوصول من الإنترنت. عناوين IP الخاصة (192.168.x.x، 10.x.x.x)، localhost، و127.0.0.1 غير مسموح بها.

القائمة البيضاء للنطاقات

استدعاءات الوكيل لا تخرج إلا إلى النطاقات المعتمدة. إذا كان نطاق رابطك الأساسي غير معتمد في القائمة البيضاء بعد، يعرض النموذج تحذيراً مع زر طلب مراجعة — قدّم النطاق (مع سبب اختياري) وسيوافق عليه مشرف Orki أو يرفضه. تقدر تتابع طلباتك تحت الإعدادات ← القائمة البيضاء للنطاقات.

Domain whitelist requests

تقدر تحفظ الأداة وتضبطها والطلب ما زال معلّقاً، لكن الاستدعاءات الفعلية إلى النطاق ستفشل حتى يتم اعتماده.

المتغيرات — تماماً مثل Postman!

تعمل المتغيرات تماماً مثل متغيرات بيئة Postman. استخدم القوسَين المتعرّجَين المزدوجَين {{variable_name}} لإدراج قيم ديناميكية.

نوعان من المتغيرات

1. المكوّنات — متغيرات مخصصة مستخرَجة من المحادثة

الصيغة: {{component_name}}
أمثلة: {{order_id}}, {{product_sku}}, {{search_query}}

يستخرج وكيل الذكاء الاصطناعي هذه القيم من رسائل العميل. مثلاً، لما يقول العميل "وش حالة الطلب رقم 12345؟"، يستخرج الذكاء الاصطناعي 12345 كمكوّن order_id.

2. سمات المستخدم — مُعَبَّأة مسبقاً من ملف العميل

الصيغة: {{$attribute_name}}
المتاحة: {{$name}}, {{$email}}, {{$phone}}, {{$location}}, {{$language}}, {{$whatsapp_number}}, {{$whatsapp_name}}, {{$instagram_username}}

تُعَبَّأ هذه تلقائياً من بيانات ملف العميل.

أين تقدر تستخدم المتغيرات؟

المكان	مثال
نقطة النهاية	`/users/{{user_id}}/orders`
معاملات الاستعلام	`email={{$email}}&status={{order_status}}`
الترويسات	`Authorization: Bearer {{api_token}}`
متن الطلب (JSON)	`{"customer_id": {{customer_id}}, "email": {{$email}}}`
متن الطلب (نموذج)	`name={{$name}}&order={{order_id}}`

معاملات الاستعلام

أضف معاملات استعلام URL كأزواج مفتاح-قيمة. تُلحَق هذه بالرابط كـ ?key=value&key2=value2.

المفتاح	القيمة	النتيجة
`order_id`	`{{order_id}}`	`?order_id=12345`
`email`	`{{$email}}`	`[email protected]`
`limit`	`10`	`?limit=10` (قيمة ثابتة)

الترويسات

أضف ترويسات HTTP مخصصة. الاستخدامات الشائعة:

الترويسة	القيمة	الغرض
`Authorization`	`Bearer {{api_token}}`	مصادقة API
`X-API-Key`	`{{api_key}}`	طريقة مصادقة بديلة
`X-Customer-ID`	`{{$email}}`	تمرير سياق العميل

ملاحظة

يُضبَط Content-Type تلقائياً بناءً على اختيار نوع المتن — ما تقدر تضبطه يدوياً.

استخدم موفّر مصادقة لبيانات الاعتماد

بدل لصق مفاتيح API في الترويسات، أنشئ بيانات اعتماد قابلة لإعادة الاستخدام تحت التكاملات ← المصادقة وأرفقها في قسم المصادقة الخاص بالأداة. السر يُشفَّر، ويُحقن من جهة الخادم في كل استدعاء، والوكيل الذكي لا يراه أبداً. راجع المصادقة لأدوات API.

متن الطلب

لطرق POST/PUT، تقدر ترسل بيانات في متن الطلب.

أنواع المتن:

JSON (application/json) — الأكثر شيوعاً للواجهات الحديثة
Form URL Encoded (application/x-www-form-urlencoded) — تقديم نموذج تقليدي
Form Data (multipart/form-data) — حقول مفتاح/قيمة تُرسَل كمتن multipart
XML / SOAP (text/xml) — خدمات SOAP القديمة وواجهات XML

مثال لمتن JSON:

{
  "customer_email": {{$email}},
  "customer_name": {{$name}},
  "order_id": {{order_id}},
  "quantity": {{quantity}},
  "notes": {{special_instructions}}
}

لا تضع أبداً علامات اقتباس حول المتغير

لا تُحِط المتغير بعلامات اقتباس — مهما كان نوعه. يستبدل Orki كل متغير بقيمة JSON بالنوع الصحيح: القيم النصية تُقتبَس نيابةً عنك، والأرقام والقيم المنطقية تبقى بدون اقتباس. إضافة علامات اقتباس بنفسك تُضاعِف اقتباس القيمة، فيرفضها الخادم.

صحيح: "name": {{$name}} و"quantity": {{quantity}} و"active": {{is_active}}
خطأ: "name": "{{$name}}"

متون XML و SOAP

اختر text/xml (SOAP) والصق المغلّف اللي تتوقعه خدمتك. المتغيرات تشتغل تماماً مثل بقية الأماكن:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
                  xmlns:ord="http://balloonbliss.example/orders">
  <soapenv:Body>
    <ord:GetOrderStatus>
      <ord:OrderId>{{order_id}}</ord:OrderId>
      <ord:CustomerEmail>{{$email}}</ord:CustomerEmail>
    </ord:GetOrderStatus>
  </soapenv:Body>
</soapenv:Envelope>

شارة Valid XML / Invalid XML حيّة تخبرك إذا كان القالب يُحلَّل بشكل صحيح وأنت تكتب.

القيم تُرمَّز XML نيابةً عنك

أي قيمة تُستبدل داخل {{placeholder}} تُرمَّز تلقائياً، فملاحظة طلب تحتوي & أو < ما تقدر تكسر المغلّف. لا ترمّز القيم بنفسك — بتحصل على ترميز مزدوج.

افتراضياً ترجع الاستجابة للوكيل كـ JSON نظيف بدل XML خام. راجع قسم الإعدادات المتقدمة أدناه.

وإذا كانت الخدمة تحتاج UsernameToken من نوع WS-Security، لا تكتبه يدوياً داخل المغلّف — أرفق بيانات اعتماد WS-Security من المصادقة ويضيف Orki الترويسة في كل استدعاء.

رفع الملفات

Form Data يرسل حقول مفتاح/قيمة عادية كمتن multipart. أما إرسال ملف فعلي — باسم ملف ونوع محتوى — فيُضبَط عبر الـ API مو عبر هذا النموذج، ويُوصَل إليه عادةً من مسار عمل بعد خطوة Convert to File.

مواصفات JOLT (اختيارية لكنها قوية)

ما هي JOLT؟

JOLT (لغة تحويل JSON إلى JSON) تحوّل استجابة الـ API إلى صيغة أبسط قبل أن يستلمها وكيل الذكاء الاصطناعي.

متى تستخدم JOLT:

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

ليش تستخدم JOLT؟

ردود ذكاء اصطناعي أنظف — يعمل الذكاء الاصطناعي بشكل أفضل مع بيانات بسيطة ومسطَّحة
تقليل استخدام التوكنز — استجابات أصغر = معالجة ذكاء اصطناعي أسرع وأرخص
إخفاء البيانات الحساسة — تمرير الحقول ذات الصلة فقط للذكاء الاصطناعي
توحيد الصيغ — جعل واجهات API المختلفة ترجع هياكل متسقة

مثال JOLT

ترجع الـ API:

{
  "data": {
    "order": {
      "id": "ORD-123",
      "customer": {
        "name": "John",
        "contact": { "email": "[email protected]" }
      },
      "status": "shipped",
      "items": [...]
    }
  }
}

مواصفات JOLT للتسطيح:

[
  {
    "operation": "shift",
    "spec": {
      "data": {
        "order": {
          "id": "order_id",
          "status": "order_status",
          "customer": {
            "name": "customer_name"
          }
        }
      }
    }
  }
]

النتيجة المحوَّلة:

{
  "order_id": "ORD-123",
  "order_status": "shipped",
  "customer_name": "John"
}

عمليات JOLT الشائعة:

shift — نقل/إعادة تسمية الحقول (الأكثر شيوعاً)
default — إضافة قيم افتراضية للحقول المفقودة
remove — حذف الحقول غير المرغوبة

بناء JOLT عبر درج الاختبار

لا تحتاج لكتابة JOLT دون رؤية النتيجة. يحتوي نموذج الأداة على درج اختبار (Test) مدمج ينفّذ الطلب الحقيقي على واجهة API عندك ويعرض الاستجابة الفعلية. يتضمن ساحة تجربة JOLT حيث يمكنك تجربة المواصفات على تلك الاستجابة الحية وتطبيقها على الأداة مباشرة عندما يصبح الناتج صحيحاً.

يمكنك أيضاً فتح AI View (معاينة "What does the AI see?" على بطاقة الأداة) في أي وقت لترى بالضبط المخطط والوصف اللذين يستلمهما وكيل الذكاء الاصطناعي لأداتك.

إعادة التسمية للوضوح

JOLT مفيدة بشكل خاص لإعادة تسمية أسماء حقول غامضة إلى شيء يفهمه الذكاء الاصطناعي بشكل أفضل:

الحقل الأصلي	تم إعادة التسمية إلى	السبب
`ord_sts`	`order_status`	معنى أوضح
`cust_nm`	`customer_name`	الذكاء الاصطناعي يفهم "name"
`dlvry_dt`	`delivery_date`	إزالة الاختصارات

البيانات الشخصية في الاستجابة

إذا كانت واجهتك ترجع بيانات شخصية — رقم هاتف، رقم مدني، آيبان — خبّر Orki أي الحقول تحملها. تُستبدل تلك القيم برموز نائبة قبل أن يراها نموذج الذكاء الاصطناعي، وتُخفى في لوحة التحكم عن الموظفين الأقل من مستوى الوصول المطابق.

تحديد حقول البيانات الشخصية على أداة API

الحقل	ما تدخله
مسار الحقل	مسار JSONPath داخل الاستجابة، مثل `$.data.customer.mobile` أو `$.bookings[*].phone`
نوع البيانات الشخصية	الاسم، البريد الإلكتروني، رقم الهاتف، الرقم المدني، رقم السجل التجاري، رقم الآيبان أو الحساب البنكي

تُطابَق المسارات بعد تحويل JOLT

اكتب المسارات حسب شكل الاستجابة بعد ما تخلّص مواصفة JOLT شغلها، مو حسب الشكل الخام القادم من الخادم. إذا غيّرت اسم cust_mobile إلى phone، صرّح بـ phone.

شغّل الأداة مرة واحدة بزر اختبار قبل تعبئة هذا القسم — عندها يعرض حقل مسار الحقل المسارات الحقيقية من تلك الاستجابة كاقتراحات.

هذا تصريحي عن قصد: يُخفي Orki بالضبط ما تصرّح به ولا شيء غيره، فرقم حساب صادف أنه يشبه رقم هاتف ما يُخلَط معه أبداً.

البيانات الشخصية في الاستجابة تعمل فقط أثناء تفعيل إخفاء البيانات الشخصية لمؤسستك.

الإعدادات المتقدمة

مطوية افتراضياً. فيها إعدادان.

تحويل استجابة XML إلى JSON

لأدوات XML/SOAP فقط. مُفعّل افتراضياً. تُفَك مغلّفات SOAP، وتُزال نطاقات الأسماء، وتُعرَض الأخطاء (faults) كخطأ منظّم، فتشتغل مواصفة JOLT والوكيل الذكي على JSON نظيف.

أطفئه فقط لو كنت تبغى تمرير XML الخام كما هو — «مطفأ» ما تعني «بدون XML»، تعني «بدون تحويل».

التحقق عند انتهاء المهلة

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

الحقل	الغرض
Verify endpoint	مسار للقراءة فقط يقدر يخبرك إذا تمت الكتابة
Method	`GET` أو `POST`
Verify query parameters	تُحَل بنفس متغيرات الطلب الأصلي
Match path (JSONPath)	مكان ظهور المرجع في استجابة التحقق، مثل `$.tickets[*].reference`
Expected value	المرجع المطلوب البحث عنه، مثل `{{reference_id}}`
Retry when not found	أعد الاستدعاء الأصلي إذا ما لقى التحقق شيئاً
Max retries	٠–٢

يحتاج مرجعاً يطابق عليه

أرسل قيمة فريدة — مكوّن مثل {{reference_id}} — في كلٍّ من متن الطلب وحقل Expected value. بدون شي يطابق عليه، ما يقدر Orki يميّز سجلك عن سجل غيرك.

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

قسم المتغيرات المشار إليها

يُعَبَّأ هذا القسم تلقائياً بناءً على المتغيرات المستخدمة في ضبطك.

مربع الاختيار "مطلوب":

مفعّل — إذا كانت هذه القيمة مفقودة، راح يسأل الذكاء الاصطناعي العميل لتوفيرها قبل استدعاء الـ API
معطّل — المتغير اختياري؛ يُستَدعَى الـ API حتى لو كانت القيمة مفقودة

ترميز الألوان:

شريحة زرقاء — مكوّن صحيح (موجود في قائمة مكوّناتك)
شريحة بنفسجية — سمة مستخدم صحيحة
شريحة حمراء — مرجع غير صحيح (المكوّن غير موجود أو خطأ في اسم السمة)

الأمان

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

الحقل	الوصف	الافتراضي
يتطلب رقم هاتف متحقَّق	عند التفعيل، يجب على العملاء إكمال تحقق OTP قبل تنفيذ هذه الأداة	معطّل
مدة صلاحية التحقق (أيام)	كم تبقى عملية التحقق الناجحة صالحة قبل أن يحتاج العميل للتحقق مرة أخرى	14 يوماً

متى تفعّل التحقق من الهاتف:

الأدوات اللي تنفّذ إجراءات حساسة (مثل تقديم الطلبات، إجراء المدفوعات)
الأدوات اللي تصل إلى معلومات حساب شخصية
الأدوات اللي تعدّل بيانات العميل عبر أنظمة خارجية

كيف يعمل:

يبدأ العميل محادثة تحتاج هذه الأداة
يرسل وكيل الذكاء الاصطناعي تلقائياً رمز OTP إلى رقم هاتف العميل
يردّ العميل بالرمز
يتحقق الوكيل من الرمز ويتابع لاستدعاء الأداة
الاستخدامات اللاحقة خلال مدة الصلاحية تتخطى التحقق

ملاحظة

تُعاد مدة الصلاحية (1 إلى 365 يوماً) من كل تحقق ناجح. راجع التحقق من الهاتف (OTP) للتفاصيل عن كيفية عمل تدفق التحقق.

إنشاء المكوّنات

قبل استخدام متغيرات {{component_name}}, تحتاج تنشئ المكوّن. تحدد المكوّنات نوع البيانات اللي يجب أن يستخرجها الذكاء الاصطناعي من المحادثات.

أنواع المكوّنات

النوع	الوصف	مثال للاستخدام
سلسلة	قيم نصية	order_id, product_name, search_query
رقم	قيم عددية	quantity, price, age
منطقية	صح/خطأ	is_urgent, wants_notification
Enum	خيارات محددة مسبقاً	order_status (pending/shipped/delivered)
تاريخ	تاريخ تقويمي (`2026-09-25`)	delivery_date, birth_date
تاريخ ووقت	تاريخ مع وقت بصيغة ISO مع فارق التوقيت (`2026-09-25T17:00:00+04:00`)	pickup_slot, appointment_at
كائن	بيانات متداخلة معقدة	shipping_address مع street, city, zip
مصفوفة	قائمة من القيم	product_ids, selected_options

إنشاء مكوّن

اضغط على شريحة مكوّن في قسم المتغيرات المشار إليها
أو اذهب إلى قسم المكوّنات واضغط على "إضافة مكوّن"
عبّئ:
- الاسم — معرّف بصيغة snake_case (مثل order_id)
- الوصف — اشرح ماذا تمثّل هذه البيانات (يساعد الذكاء الاصطناعي على الاستخراج بشكل صحيح)
- النوع — اختر النوع المناسب
- قواعد التحقق (اختياري) — قواعد حسب النوع: نطاق رقمي، أو طول النص وتعبير نمطي (Regex) مع توضيح صيغة بلغة بسيطة، أو نافذة تواريخ (سماح بالماضي/المستقبل، أقرب/أبعد تاريخ بالأيام). تظهر القاعدة للذكاء الاصطناعي ضمن وصف المعامل وتُفرض عند تشغيل الأداة — المعامل المخالف يُرفض مع نص القاعدة قبل الوصول إلى واجهتك أصلًا.
- قيمة مثال — بيانات نموذجية للتوثيق

اختبر القاعدة بدون الذكاء الاصطناعي

شغّل الأداة من درج الاختبار بقيمة تخالف القاعدة — الاستجابة تكون Invalid argument(s) مع اسم الحقل وقاعدته، وهو بالضبط ما سيُخبَر به الوكيل.

مثال كامل: أداة استعلام عن الطلب

السيناريو: أنشئ أداة تستعلم عن حالة الطلب من واجهة برمجة متجر التجارة الإلكترونية.

المعلومات الأساسية

العنوان: get_order_status
الوصف: يسترجع تفاصيل الطلب بما في ذلك الحالة الحالية، معلومات الشحن، وتاريخ التوصيل المتوقَّع. استخدم لما يسأل العميل عن حالة طلبه، التتبع، أو التوصيل.

ضبط الـ API

الرابط الأساسي: https://api.mystore.com
الطريقة: GET
نقطة النهاية: /v1/orders/{{order_id}}

الترويسات

الترويسة	القيمة
`Authorization`	`Bearer sk_live_xxxxxxxxxxxxx`
`X-Customer-Email`	`{{$email}}`

معاملات الاستعلام

المفتاح	القيمة
`include`	`shipping,items`

مواصفات JOLT

[
  {
    "operation": "shift",
    "spec": {
      "order_number": "order_number",
      "status": "status",
      "created_at": "order_date",
      "shipping": {
        "carrier": "shipping_carrier",
        "tracking_number": "tracking_number",
        "estimated_delivery": "delivery_date"
      },
      "total": "total_amount"
    }
  }
]

المتغيرات المشار إليها

order_id — مطلوب (مفعّل) — راح يسأل الذكاء الاصطناعي العميل عن رقم الطلب إذا ما قُدِّم
$email — اختياري — يُستخدم للتحقق

تعيين الأدوات للوكلاء

الأداة لا تفعل شيئاً حتى تعيّنها

إنشاء الأداة يحفظها في مساحة العمل فقط — ولا يقدر أي وكيل يراها أو يستدعيها بعد. إذا "تجاهل" الوكيل أداتك الجديدة، فأول شيء تتحقق منه هو التعيين أدناه.

بعد إنشاء أداة، تحتاج تعيّنها لوكيل:

اذهب إلى الوكلاء
اضغط على الوكيل اللي تبي تضبطه
اذهب إلى تبويب الأدوات
ابحث عن أداتك في قسم المتاحة
اقلب المفتاح إلى مفعّل لتعيينها

سوف تنتقل أداتك الجديدة إلى قسم المعيَّنة ويقدر الوكيل يبدأ باستخدامها فوراً.

أدوات مسارات العمل فقط لا تحتاج تعييناً

إذا كانت الأداة مخصصة للتشغيل داخل مسار عمل فقط، فلا تعيّنها للوكيل — عيّن مسار العمل فقط. خطوات مسار العمل تنفّذ أدواتها من جهة الخادم بغض النظر عن تعيين الوكيل، وإبقاء الأداة الخام غير معيَّنة يمنع الوكيل من استدعائها مباشرة خارج المسار.

راجع أدوات الوكيل لمزيد من التفاصيل.

نصائح لاستخدام أفضل للأدوات

اكتب الأوصاف بالنتائج المتوقعة

ضمّن ما ترجعه الأداة في وصفك. هذا يساعد الذكاء الاصطناعي على فهم متى يستخدمها:

وصف جيد:

"يسترجع تفاصيل الطلب بما في ذلك حالة الطلب، رقم التتبع، شركة الشحن، وتاريخ التوصيل المتوقَّع. استخدم لما يسأل العميل عن حالة طلبه، التتبع، أو التوصيل."

أقل فائدة:

"يحصل على معلومات الطلب."

الذكاء الاصطناعي الآن يعرف أن هذه الأداة ترجع أرقام تتبع، فراح يستخدمها لما يسأل العملاء "وين رقم التتبع؟"

إدارة الأدوات الكثيرة

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

مثال للتعليمات المخصصة:

إرشادات استخدام الأدوات:
- استخدم `get_order_status` لما يسأل العميل عن حالة الطلب، التتبع، أو التوصيل
- استخدم `check_inventory` لما يسأل العميل إذا كان المنتج متوفراً
- استخدم `create_support_ticket` فقط لما لا يمكن حل المشكلة وتحتاج متابعة بشرية
- جرّب دائماً `get_order_status` قبل `create_support_ticket` للمشاكل المتعلقة بالطلبات

هذا الإرشاد في التعليمات المخصصة يساعد الذكاء الاصطناعي على اتخاذ قرارات أفضل بشأن أي أداة يستدعي.

ماذا يحدث للاستجابات غير المعتادة

سلوكان ما لهما إعداد في النموذج، لكنك راح تقابلهما.

أخطاء SOAP (faults). إذا رجعت خدمة XML خطأً، يحوّله Orki إلى خطأ منظّم ويبلّغ عن فشل الاستدعاء، حتى لو وصل الخطأ بحالة 200. ويُتخطّى JOLT — ما فيه شي ذو معنى يُحوَّل. درج الاختبار يعرضه كشريط أحمر SOAP fault مع رمز الخطأ.

الاستجابات الثنائية (Binary). إذا رجعت واجهتك ملف PDF أو صورة أو أي محتوى غير نصي، يخزّنه Orki ويسلّم الوكيل كائن JSON صغير بدلاً منه:

{
  "file_url": "https://…",
  "content_type": "application/pdf",
  "size_bytes": 48213,
  "expires_in_seconds": 3600
}

بعدها يقدر الوكيل يرسل الملف للعميل. الرابط صالح لمدة ساعة. وفي درج الاختبار يُحذف المتن مع ملاحظة — المحتوى الثنائي ما يُعرَض هناك.

استكشاف الأخطاء وحلها

المشكلة	الحل
خطأ "مكوّن غير صحيح" (شريحة حمراء)	أنشئ المكوّن أولاً، أو افحص الأخطاء في الاسم
"يجب أن يكون الرابط الأساسي نطاقاً عاماً"	استخدم رابط API الإنتاج عندك، وليس localhost أو IPs داخلية
"JSON غير صحيح" في متن الطلب	افحص الفواصل المفقودة، المفاتيح غير المقتبَسة، أو الفواصل النهائية
ترجع الـ API لكن الذكاء الاصطناعي يعطي إجابة خاطئة	أضف مواصفات JOLT لتبسيط/تسطيح الاستجابة
"لا يمكن ضبط Content-Type"	أزِل Content-Type من الترويسات؛ يُضبَط تلقائياً بناءً على نوع المتن
شارة "Invalid XML" ما تختفي	القالب مو صحيح التكوين — دوّر على وسم غير مغلق. الرموز النائبة يتجاهلها الفحص
خطأ خادم عام في كل استدعاء رغم صحة الرابط	غالباً بيانات اعتماد فاشلة. افتح درج الاختبار — يسمّي السبب الحقيقي، بينما المحادثة لا تفعل
الاستدعاء يفشل بـ 413	تجاوزت الاستجابة حد الحجم — قلّصها بـ JOLT، أو أرجع بيانات أقل
الاستدعاء يفشل بـ 429 قبل ما يشتغل	وصلت حد النطاق الترددي اليومي لهذا العميل أو لمؤسستك
تكرار الطلبات/التذاكر بعد بطء الواجهة	فعّل التحقق عند انتهاء المهلة في الإعدادات المتقدمة

الحدود

عدد الأدوات اللي تقدر تنشئها يعتمد على باقتك — تحقق من الإعدادات > الفوترة.

وهذي حدود المنصة المطبَّقة على كل استدعاء، وتظهر كأخطاء حقيقية:

الحد	القيمة	ما تشوفه
متن الطلب	١ ميغابايت	يُرفض الاستدعاء
متن الاستجابة	٥ ميغابايت	خطأ `413` مع الحجم الفعلي
النطاق الترددي لكل عميل	١٠٠ ميغابايت / يوم	خطأ `429` قبل تنفيذ الاستدعاء
النطاق الترددي لكل مؤسسة	١ غيغابايت / يوم	خطأ `429` قبل تنفيذ الاستدعاء
مهلة الطلب	٩٠ ثانية	يُبلَّغ عن الاستدعاء كمنتهي المهلة

هذه الأداة تُغيّر البيانات

لكل أداة مفتاح واحد يحدّد ما إذا كان الذكاء الاصطناعي يستطيع استخدامها أثناء صياغة ردّ مقترح لموظف بشري:

الأدوات التي تُغيّر البيانات (إنشاء طلبات، تحديث سجلّات، إرسال أي شيء إلى العميل) تُستبعد عندما يصيغ الذكاء الاصطناعي اقتراحات ردود للموظفين البشريين. أطفئ هذا الخيار فقط للأدوات التي تقرأ فقط.

هذا المفتاح مُفعّل افتراضيًا — يُفترض أن الأداة تُغيّر البيانات ما لم تحدّد غير ذلك. عندما يتولّى موظف بشري محادثةً، يصوغ الذكاء الاصطناعي ردّه كتجربة داخلية لا تُرسَل، لذلك تُحجب أي أداة قد يكون لها أثر فعلي (إنشاء طلب، تحديث سجلّ، مراسلة العميل). أطفئ المفتاح فقط للأدوات التي تقرأ فقط — استعلام، فحص حالة، بحث — لتبقى متاحة أثناء الصياغة. لا أثر لهذا الإعداد عندما يدير الذكاء الاصطناعي المحادثة بنفسه؛ فهو يحكم صياغة الاقتراحات فقط. راجع الردود المقترحة ← ما الذي يستطيع الذكاء الاصطناعي فعله أثناء الصياغة.

الخطوات التالية

أدوات الوكيل - تعيين الأدوات لوكلائك
المصادقة لأدوات API - خزّن بيانات الاعتماد مرة وأرفقها بأي أداة
مرجع المصادقة - العقد الدقيق، للفريق اللي يملك الواجهة
إخفاء البيانات الشخصية - أبعِد بيانات العملاء عن نموذج الذكاء الاصطناعي
نظرة عامة على الوكلاء الأذكياء - ضبط سلوك الوكيل

ما هي أدوات API؟​

الوصول إلى أدوات API​

أقسام النموذج​

المعلومات الأساسية​

ضبط الـ API​

القائمة البيضاء للنطاقات​

المتغيرات — تماماً مثل Postman!​

نوعان من المتغيرات​

1. المكوّنات — متغيرات مخصصة مستخرَجة من المحادثة​

2. سمات المستخدم — مُعَبَّأة مسبقاً من ملف العميل​

أين تقدر تستخدم المتغيرات؟​

معاملات الاستعلام​

الترويسات​

متن الطلب​

متون XML و SOAP​

مواصفات JOLT (اختيارية لكنها قوية)​

مثال JOLT​

بناء JOLT عبر درج الاختبار​

إعادة التسمية للوضوح​

البيانات الشخصية في الاستجابة​

الإعدادات المتقدمة​

تحويل استجابة XML إلى JSON​

التحقق عند انتهاء المهلة​

قسم المتغيرات المشار إليها​

الأمان​

إنشاء المكوّنات​

أنواع المكوّنات​

إنشاء مكوّن​

مثال كامل: أداة استعلام عن الطلب​

المعلومات الأساسية​

ضبط الـ API​

الترويسات​

معاملات الاستعلام​

مواصفات JOLT​

المتغيرات المشار إليها​

تعيين الأدوات للوكلاء​

نصائح لاستخدام أفضل للأدوات​

اكتب الأوصاف بالنتائج المتوقعة​

إدارة الأدوات الكثيرة​

ماذا يحدث للاستجابات غير المعتادة​

استكشاف الأخطاء وحلها​

الحدود​

هذه الأداة تُغيّر البيانات​

الخطوات التالية​

ما هي أدوات API؟

الوصول إلى أدوات API

أقسام النموذج

المعلومات الأساسية

ضبط الـ API

القائمة البيضاء للنطاقات

المتغيرات — تماماً مثل Postman!

نوعان من المتغيرات

1. المكوّنات — متغيرات مخصصة مستخرَجة من المحادثة

2. سمات المستخدم — مُعَبَّأة مسبقاً من ملف العميل

أين تقدر تستخدم المتغيرات؟

معاملات الاستعلام

الترويسات

متن الطلب

متون XML و SOAP

مواصفات JOLT (اختيارية لكنها قوية)

مثال JOLT

بناء JOLT عبر درج الاختبار

إعادة التسمية للوضوح

البيانات الشخصية في الاستجابة

الإعدادات المتقدمة

تحويل استجابة XML إلى JSON

التحقق عند انتهاء المهلة

قسم المتغيرات المشار إليها

الأمان

إنشاء المكوّنات

أنواع المكوّنات

إنشاء مكوّن

مثال كامل: أداة استعلام عن الطلب

المعلومات الأساسية

ضبط الـ API

الترويسات

معاملات الاستعلام

مواصفات JOLT

المتغيرات المشار إليها

تعيين الأدوات للوكلاء

نصائح لاستخدام أفضل للأدوات

اكتب الأوصاف بالنتائج المتوقعة

إدارة الأدوات الكثيرة

ماذا يحدث للاستجابات غير المعتادة

استكشاف الأخطاء وحلها

الحدود

هذه الأداة تُغيّر البيانات

الخطوات التالية