تعامل مع نتائج التشغيل

بعد استدعاء invoke() أو chat()، لا تكتفِ بعرض result.message. اقرأ result.status أولًا؛ فهي التي تبيّن هل انتهت العملية أم تنتظر المكتبة معلومة أو اختيارًا أو Confirmation.

ابدأ بـ Tool البحث التي ربطتها في البداية السريعة. لا تحتاج إلى تشغيل مثال الحجز لفهم الحالات الأساسية.

تعامل أولًا مع البحث البسيط

إذا اكتمل البحث، تعود completed مع البيانات المتاحة. اعرض نتائج API؛ وإذا كانت القائمة فارغة، أخبر المستخدم بعدم وجود نتائج بدل عرض خطأ.

إذا كان الـ Input المطلوب غائبًا، تعود needs_input. اعرض سؤالًا عن القيمة الناقصة. في واجهة نموذج إدخال، يمكنك استدعاء invoke() من جديد بالقيم المكتملة. وفي المحادثة، أرسل جواب المستخدم عبر chat() مع الـ Session نفسها لتتابع المكتبة العمل المعلّق.

إذا فشل الطلب، تعود error مع تفاصيل الخطأ. فرّق بين مدخل غير صالح ومصادقة مرفوضة وAPI غير متاحة. لا تعالج كل الحالات برسالة «حاول مرة أخرى»؛ قد لا تكون الإعادة هي الإجراء الصحيح.

أما completed في محادثة عامة فقد تعني أن المساعد أجاب دون استخدام Tool. افحص result.tool والبيانات قبل إعلان أن عملية عمل حدثت فعلًا.

أضف Selection والـ Confirmation عند احتياج العملية إليهما

تظهر needs_selection عندما تحتاج المكتبة إلى اختيار المستخدم من نتائج API. اعرض selection.options، ثم مرّر selection.id وID الخيار الذي اختاره المستخدم إلى select().

تظهر needs_confirmation عندما تكون العملية جاهزة وتنتظر موافقة المستخدم. اعرض confirmation.preview ووقت انتهاء الصلاحية. بعد الموافقة فقط، استدعِ confirm() ومرّر في confirmationId قيمة confirmation.id التي أعادها AGENTO.

هاتان حالتان مختلفتان: اختيار موعد يحدد أي موعد نريد، والـ Confirmation يوافق على إنشاء الحجز. لا تجعل اختيار عنصر يعني موافقة تلقائية على كل ما يليه. نشرح إعداد كل منهما في الـ Dependencies وعمليات الكتابة.

اختر الدالة وفق إجراء المستخدم

invoke() يبدأ عملية معروفة بالاسم والـ Input. ليس زر متابعة عامًا؛ استدعاؤه من جديد يستبدل العمل المعلّق.

chat() يستقبل رسالة ويستخدم AI Model لفهمها، ويمكنه متابعة مدخل ناقص في المحادثة. لا تستخدم مجرد كلمة «نعم» كبديل عن مسار Confirmation الصريح في التطبيق.

select() يتابع اختيارًا أعادته المكتبة. وconfirm() ينفّذ العملية المجهّزة بعد الموافقة. وcancel() يمسح العمل المعلّق؛ إغلاق بطاقة في الواجهة دون استدعائه ليس إلغاءً لحالة Runtime.

استخدم Session ID نفسه طوال هذه الخطوات. يتحقق خادمك من أن الـ Session تخص المستخدم؛ وجود sessionId في الـ Request لا يثبت ذلك وحده.

تتبّع الحجز من التاريخ الناقص إلى اكتماله

1. استدعِ book دون تاريخ. تعود needs_input قبل أي استعلام عن المواعيد.
2. اجمع التاريخ. في نموذج الإدخال، استدعِ invoke() بالقيم المكتملة. في المحادثة، مرّر إجابة المستخدم إلى chat() لتحديث العمل المعلّق.
3. إذا عادت عدة مواعيد، اعرض selection.options كما هي. لا تنشئ IDs جديدة ولا تطلب من الـ AI Model إعادة صياغة قائمة الخيارات.
4. بعد اختيار المستخدم، استدعِ select(). ينقل الـ Runtime الـ Token الأصلي من نتيجة الـ API ويجهّز طلب الحجز.
5. اعرض confirmation.preview ووقت انتهاء الصلاحية. لم تُرسل عملية الكتابة بعد.
6. بعد الموافقة الصريحة، استدعِ confirm() واعرض اكتمال الحجز فقط إذا سمحت الحالة التي أعادها AGENTO بذلك.

قد تعيد كل متابعة حالة وسيطة أخرى أو خطأ. لا تفترض أن select() تكمل العملية دائمًا، أو أن confirm() تنجح دائمًا.

مرّر كل نتيجة عبر Handler واحد

هذا pseudocode للتطبيق؛ دوال العرض مسؤولية واجهتك.

function handleResult(result) {
  switch (result.status) {
    case "completed":
      renderCompleted({ message: result.message, data: result.data });
      break;
    case "needs_input":
      renderInputRequest({ fields: result.missing ?? [], message: result.message });
      break;
    case "needs_selection":
      renderChoices(result.selection);
      break;
    case "needs_confirmation":
      renderApproval(result.confirmation);
      break;
    case "error":
      renderRecoverableError(result.error);
      break;
  }
}

احتفظ بالـ IDs وأوقات انتهاء الصلاحية كما وردت في النتيجة ضمن State التطبيق. تحقق من صلاحية المستخدم في كل Server Handler؛ الـ ID الخاص بالمحادثة لا يثبت هويته.

ماذا يفعل Runtime بين الحالات؟

load session inside a serialized transaction
  → check expiry, config identity, credential transport, and budgets
  → route a message or start a known tool
  → validate user-owned inputs
  → resolve read-only dependencies and choices
  → validate completed arguments
  → prepare a fixed HTTP request
  → wait for confirmation if required
  → execute, validate response, redact, and present

تمنع آلة الحالات الداخلية الانتقالات غير المدعومة. اعتمد في تطبيقك على حالات النتيجة العامة وIDs المتابعة، بدل تعديل الحالة المخزنة يدويًا.

يمكن للمحادثة أن تتفرع دون منح موافقة

أثناء انتظار التاريخ، قد يقول المستخدم «شكرًا». مع تفعيل المحادثة، يستطيع AGENTO الرد مع الاحتفاظ بالعمل المعلّق. أما السؤال عن ساعات الدوام فيحتاج إلى Tool API مناسبة أو مصدر موثوق؛ لا يجوز أن تخترع المحادثة معلومة عمل.

إذا كتب المستخدم كلمة موافقة يتعرف عليها AGENTO، يعيد الـ Confirmation المعلّق إلى التطبيق ولا ينفّذ العملية. وقد يبدأ طلب جديد مسارًا يحل محل المسار القديم. كذلك قد يؤدي تغيّر الـ Input إلى إبطال بيانات Dependencies السابقة والحاجة إلى خيارات جديدة.

الإلغاء والانتهاء والتنفيذ غير المحسوم

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

إذا انتهت صلاحية الـ Session أو لم تعد متوافقة مع الـ Config، يعيد AGENTO الخطأ SESSION_EXPIRED ويمسح الـ State غير المتوافقة. ابدأ مسارًا جديدًا. أما وجود الحالة EXECUTING في التخزين فيؤدي إلى TOOL_EXECUTION_UNCERTAIN؛ تحقق من نتيجة العملية لدى الـ API قبل مسح الحالة وإعادة المحاولة.

اختبر التطبيق خارج المسار المثالي

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