Navigation وReferences

استخدم Dependency عندما تحتاج الـ Tool إلى بيانات أخرى قبل تنفيذها. واستخدم Navigation عندما يتصفح المستخدم قائمة ويؤدي اختياره إلى تشغيل Tool تالية. واستخدم Reference للاحتفاظ بقيمة اختيرت فعلًا، كي تستفيد منها Tool لاحقًا دون فرض انتقال فوري.

اقرأ الـ Dependencies أولًا؛ تتبع مسارات Selection قواعد القراءة من العنصر نفسه.

تصفّح الفئات ثم اعرض المنتجات

يتوقع هذا الإعداد الكامل أن تعيد API الفئات الشكل { data: [{ code: "hair", label: "Hair care" }] }. وتُعرض Response API المنتجات كبيانات خام.

version: "2"
tools:
  - id: categories
    tool:
      description: Browse product categories before viewing their products.
      input_schema:
        type: object
        properties: {}
    request:
      method: GET
      url: https://api.example.com/categories
    selection:
      items_path: $.data
      id_path: $.code
      label_path: $.label
    navigates_to:
      tool: products
      map:
        $.category_id: $.code
  - id: products
    tool:
      description: List products in a category.
      input_schema:
        type: object
        properties:
          category_id: { type: string }
        required: [category_id]
    request:
      method: GET
      url: https://api.example.com/categories/{category}/products
      map:
        path:
          category: $.category_id

استدعِ categories. يحوّل القسمان selection وnavigates_to القائمة إلى خيارات للمستخدم. مرّر الخيار الذي حدده إلى runtime.select(). ينسخ AGENTO قيمة code من العنصر المختار إلى category_id في Tool المسماة products، ثم يبني Path Mapping العنوان /categories/hair/products.

يجب تعريف الـ Tool التالية، بما يشمل الـ Input المستهدف وطلب HTTP الخاص بها. كتابة navigates_to.tool: products وحدها لا تنشئ الـ Tool.

إذا كانت الـ Tool التالية تكتب بيانات، تبقى قواعد Dependencies والـ Confirmation الخاصة بها سارية. Navigation لا يتجاوزها.

انقل الـ Input الأصلي منفصلًا عن بيانات Selection

# Fragment on a source tool whose schema declares date and notes.
navigates_to:
  tool: book
  arguments:
    date: $.date
    notes: $.notes
  map:
    $.slot_token: $.slot_token

يقرأ arguments الـ Input الأصلي للـ Tool الأولى، بينما يقرأ map العنصر المختار من الـ API وينقل قيمه إلى Input الخاص بالـ Tool التالية. يحتفظ المثال بالتاريخ والملاحظات عبر خطوة التصفح، ويأخذ slot_token من العنصر المختار.

يجب تعريف الوجهات في Schema الـ Tool التالية. يرفض compiler الوجهات المتداخلة بين arguments وmap، والـ Input غير المعلنة، واستخدام حقائق العرض كمدخلات تنفيذ. أبقِ مصدر كل قيمة واضحًا.

احتفظ بخدمة مختارة لاستخدامها في Tool لاحقة

انشر Reference من Tool قائمة خدمات تشارك في اختيار صريح:

references:
  publish:
    name: selected_service
    path: $.id
    ttl_ms: 60000

عند اختيار خدمة فعلًا، يحفظ الـ Runtime قيمة id الخاصة بها. لا ينشر كل العناصر، ولا يفترض أن آخر عنصر هو المطلوب. يبدأ مسار النشر في references.publish من العنصر المختار؛ ويُرفض نشر العنصر كاملًا أو حقل خاص.

وفي Tool لاحقة تعرّف service_id في الـ Schema:

references:
  consume:
    service_id: selected_service

تملأ الـ Reference السارية قيمة الـ Input إذا كانت غائبة، وتخفي حقل المستوى الأول من الـ Schema المعروضة للـ AI Model. إذا مرّر التطبيق أو Navigation قيمة صريحة، تُستخدم بدل الـ Reference المخزّنة. ولجلب القيمة بعد انتهاء صلاحيتها، أضف Dependency مناسبة باستخدام when: missing. تسهّل الـ Reference إعادة استخدام القيمة، ولا تثبت بقاء صلاحيتها لدى الـ API.

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

افصل أسماء العرض عن IDs المستخدمة في التنفيذ

# Selection fragment:
items_path: $.slots
id_path: $.slot_token
label_path: $.label
id_sensitive: true
facts:
  time: $.label

توفر facts.time معلومات لسياق المحادثة ومعاينة الـ Confirmation، ولا تصلح مصدرًا لقيمة في طلب HTTP. عند تفعيل id_sensitive، يعيد AGENTO IDs لا تكشف القيم الأصلية. مرّرها كما هي إلى select() ليصل إلى العنصر الأصلي داخليًا.

وجود ID غير مكشوف لا يمنح حق الوصول إلى Session مستخدم آخر. يبقى التطبيق مسؤولًا عن Auth وربط الـ Session بالمستخدم.

اختبر الانتقال والمسار البديل

استخدم Response فيها فئتان. تحقق أن categories تعمل أولًا، ثم تصل قيمة code للفئة المختارة وحدها إلى products. اختبر ID اختيار غير صالح، وانتهاء Selection، وغياب code، وانتهاء Reference قبل استهلاكها. وإذا كانت الوجهة تكتب بيانات، فتأكد من عدم الكتابة قبل الموافقة.

تابع إلى مثال الحجز لترى حقائق Selection داخل معاينة Confirmation فعلية.