عرض حالات التطبيقات المخصّصة على وكلاء الذكاء الاصطناعي باستخدام أدوات خارجية

Matthias Rohmer

José Luis Zapata

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

يتم إنشاء هذه الأدوات من خلال JavaScript وتكتشفها تلقائيًا "أدوات مطوّري البرامج في Chrome" للوكلاء عند تحميل صفحتك.

التعرّف على أدوات المطوّرين الخارجية

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

عند استخدام أدوات خارجية، ضَع في اعتبارك ما يلي:

• الاكتشاف في وقت التشغيل: يتم رصد الأدوات تلقائيًا عندما يستجيب تطبيقك للحدث devtoolstooldiscovery الذي تنشئه "أدوات مطوّري Chrome" للوكلاء على عنصر window العام.
• نطاق السياق: لا يتم تنفيذ الأدوات إلا في سياق الصفحة التي تحدّدها. ولا يتم الاحتفاظ بها على مستوى المصادر وعمليات إعادة تحميل الصفحة.
• تخصّص الأداة : الأدوات ليست سوى طريقة إضافية ليؤدي وكيلك مهمة معيّنة. وقد يفضّل الوكيل استخدام الأدوات المضمّنة أو إمكانات النموذج الأساسية لتلبية طلب معيّن. لذا، اجعل أسماء الأدوات وأوصافها واضحة قدر الإمكان.

المتطلبات الأساسية

قبل تنفيذ الأدوات الخارجية، تأكَّد من استيفاء المتطلبات التالية:

• أدوات مطوّري Chrome للوكلاء: استخدِم الإصدار 0.25.0 أو إصدارًا أحدث.
• تفعيل JavaScript: تأكَّد من تفعيل JavaScript وتنفيذه.

تنفيذ أداة

لتنفيذ أداة، عليك الاستماع إلى حدث اكتشاف معيّن والردّ عليه بتعريفات أدواتك. يمثّل الرمز البرمجي التالي استجابة تتضمّن تعريفات الأدوات:

window.addEventListener(
  'devtoolstooldiscovery',
  (event: DevtoolsToolDiscoveryEvent) => {
    event.respondWith({
      name: 'Page-specific DevTools',
      description: 'Provide runtime info directly from the JavaScript in the page.',
      tools: [
        {
          name: 'add',
          description: 'Calculates the sum of two numbers.',
          inputSchema: {
            type: 'object',
            properties: {
              a: {type: 'number'},
              b: {type: 'number'},
            },
            required: ['a', 'b'],
          },
          execute: async (input: {a: number; b: number}) => {
            return input.a + input.b;
          },
        },
      ],
    });
  },
);

لتسجيل الأدوات في تطبيقك، اتّبِع الخطوات التالية:

1. حدِّد مجموعة أدواتك. أنشئ ToolGroup يتضمّن اسمًا ووصفًا ومصفوفة من تعريفات الأدوات الفردية.

   export interface ToolDefinition {
     name: string;
     description: string;
     inputSchema: JSONSchema7;
     execute: (args: Record<string, unknown>) => unknown;
   }
   export interface ToolGroup {
     name: string;
     description: string;
     tools: ToolDefinition[];
   }
   

2. استمِع إلى حدث الاكتشاف. تنشئ "أدوات مطوّري البرامج في Chrome" للوكلاء حدثًا مخصّصًا هو devtoolstooldiscovery على عنصر window العام بعد كل عملية تنقّل وكلما احتاجت إلى قائمة محدَّثة بالأدوات المتاحة.

3. سجِّل أدواتك. استخدِم طريقة respondWith() للحدث لتزويد الوكيل بمجموعة أدواتك.

المكوّنات الأساسية للأدوات الفردية

يجب أن يتضمّن كل تعريف أداة تنفّذها الأجزاء الثلاثة التالية:

• الاسم والوصف: يقدّمان التعليمات التي يستخدمها الوكيل لتحديد متى وكيفية استدعاء أداتك.
• مخطط الإدخال: مخطط JSON يحدّد بنية وأنواع الوسيطات التي تتوقعها الأداة.
• دالة التنفيذ: رمز JavaScript الفعلي الذي يتم تشغيله على الصفحة عندما يستدعي الوكيل الأداة.

يوضّح المثال التالي هذه المكوّنات الثلاثة في تعريف أداة واحدة:

{
  name: 'add',
  description: 'Calculates the sum of two numbers.',
  inputSchema: {
    type: 'object',
    properties: {
      a: {type: 'number'},
      b: {type: 'number'},
    },
    required: ['a', 'b'],
  },
  execute: async (input) => {
    return input.a + input.b;
  },
}

حالات استخدام أدوات المطوّرين الخارجية

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

نصائح لاكتشاف الأدوات

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

تصحيح أخطاء مقاييس وقت التشغيل الخاصة بالتطبيق

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

لنفترض أنّ لديك دالة تعرض إحصاءات داخلية، عليك أولاً إنشاء أداة مثل هذه:

window.addEventListener('devtoolstooldiscovery', (event) => {
  event.respondWith({
    name: 'My app',
    description: 'Tools to debug my app',
    tools: [
      {
        name: 'getCacheStatistics',
        description: 'Exposes runtime cache hits and misses for the frontend API service.',
        inputSchema: {},
        execute: async () => {
          // Assuming window.__apiCacheService exists in your app
          return window.__apiCacheService.getStats();
        }
      }
    ]
  });
});

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

When I reassign a lead to a new sales rep, the dashboard takes a second to
update. Please verify if the frontend is correctly updating the local cache,
or if it is doing a full cache miss and refetching the entire pipeline from the
database.

مثال على تنفيذ الوكيل: يرصد وكيلك الأداة getCacheStatistics التي يعرضها تطبيقك. يستدعي الوكيل الأداة ويحلّل النسبة التي تم العثور عليها إلى النسبة التي لم يتم العثور عليها، ويحدّد أنّ الواجهة الأمامية تعيد بشكل غير ضروري جلب المسار بالكامل بدلاً من تعديل ذاكرة التخزين المؤقت المحلية.

التحقّق من علامات الميزات

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

على سبيل المثال، أنشئ أداة مثل هذه لعرض حالة علامة الميزة الداخلية:

// Implementation for a website creator to expose feature flags
window.addEventListener('devtoolstooldiscovery', (event) => {
  event.respondWith({
    name: 'Application Configuration Tools',
    description: 'Tools for inspecting runtime environment and feature toggles',
    tools: [
      {
        name: 'getFeatureFlags',
        description: 'Returns a list of all active feature flags and their current values for the session.',
        inputSchema: {
          type: 'object',
          properties: {} // No input parameters required for this tool
        },
        execute: async () => {
          // This should return your internal feature flag state
          // Example: return window.AppConfig.getFlags();
          return {
            "new-ui-enabled": true,
            "beta-search-v2": false,
            "experiment-group": 'control',
            "log-level": 'debug'
          };
        }
      }
    ]
  });
});

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

Check the active feature flags and tell me if the new-ui-enabled flag is set to
true for this session.

مثال على تنفيذ الوكيل: يستدعي وكيلك الأداة getFeatureFlags، ويؤكّد أنّ العلامة new-ui-enabled نشطة، ثم يبدأ في تصحيح أخطاء المكوّنات المرتبطة بالواجهة الجديدة.

فحص حالة التطبيق العامة

اعرض شجرة حالة وقت تشغيل تطبيقك لمساعدة وكيلك في فهم المنطق الداخلي بدون جلب نموذج DOM بالكامل.

يمكنك إنشاء أداة مثل هذه للاستعلام عن مسارات معيّنة في شجرة الحالة، مثل ما يلي:

// Library-agnostic implementation for inspecting global application state
window.addEventListener('devtoolstooldiscovery', (event) => {
  event.respondWith({
    name: "Global State Inspector",
    description: 'Tools to inspect the runtime state tree of the application',
    tools: [
      {
        name: 'getGlobalState',
        description: "Returns the current application state. Use the 'path' parameter to drill down into specific sections (for example, 'auth.user' or 'cart.items'). ",
        inputSchema: {
          type: 'object',
          properties: {
            path: {
              type: 'string',
              description: 'Optional dot-notation path to a specific property in the state tree.'
            }
          }
        },
        execute: async (input) => {
          // Library-agnostic access:
          // Website creators can point this to whatever global store they use.
          const state = window.__APP_STATE__ ||
                        (window.store && typeof window.store.getState === 'function' ? window.store.getState() : null);

          if (!state) {
            return { error: 'Application state is not accessible via window.__APP_STATE__ or window.store.' };
          }

          if (!input.path) {
            return state;
          }

          // Helper to resolve a dot-notated path against the state object
          return input.path.split('.').reduce((acc, part) => {
            return acc && acc[part] !== undefined ? acc[part] : undefined;
          }, state);
        }
      }
    ]
  });
});

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

The number of items in my cart is not updating. Inspect the global state at the
path cart.items and list the current items and their quantities, see if they are
the same.

مثال على تنفيذ الوكيل: يستدعي وكيلك getGlobalState مع المَعلمة path. يستردّ الوكيل قائمة العناصر من سلّة التسوّق ويحدّد تباينًا بين الحالة الداخلية والعناصر المعروضة على الصفحة.

في ما يلي بعض الملاحظات المهمة بشأن مثال هذه الأداة:

• المنطق غير المرتبط: يطلب وكيل الذكاء الاصطناعي "الحالة". أنت كمطوّر تحدّد كيفية ربط هذا الطلب ببنية البيانات الفعلية في دالة execute.
• تصحيح الأخطاء المستهدَف: من خلال تضمين المَعلمة path، يمكن للوكيل تجنُّب جلب شجرة الحالة بالكامل (التي قد تكون كبيرة جدًا) والتركيز فقط على الجزء ذي الصلة، ما يؤدي إلى توفير الرموز وتحسين الأداء.
• واجهة موحّدة: حتى إذا بدّلت مكتبات إدارة الحالة، لن يحتاج وكيل تصحيح الأخطاء المستند إلى الذكاء الاصطناعي إلى أي تعليمات أو أدوات جديدة طالما أنّك تعدِّل دالة execute هذه.

فحص محتوى قاعدة البيانات

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

اعرض نقطة نهاية تصحيح أخطاء آمنة وأنشئ أداة مثل هذه للتحقّق من سجلات الخلفية:

// Framework-agnostic implementation for inspecting database content
window.addEventListener('devtoolstooldiscovery', (event) => {
  event.respondWith({
    name: 'Database Inspection Tools',
    description: 'Tools to query backend database records using existing browser session',
    tools: [
      {
        name: 'queryDatabaseTable',
        description: 'Retrieves a limited set of records from a specific table. Useful for verifying that backend data matches the UI state.',
        inputSchema: {
          type: 'object',
          properties: {
            tableName: {
              type: 'string',
              description: 'The name of the database table to inspect.'
            },
            limit: {
              type: 'number',
              default: 5,
              description: 'Maximum number of rows to return.'
            }
          },
          required: ['tableName']
        },
        execute: async (input) => {
          // This calls a generic debug endpoint you've set up on your server.
          // It's framework-agnostic because it just expects a JSON response.
          try {
            const response = await fetch(`/api/debug/db-inspect?table=${input.tableName}&limit=${input.limit}`);
            if (!response.ok) {
              return { error: `Backend returned ${response.status}: ${response.statusText}` };
            }
            return await response.json();
          } catch (error) {
            return { error: `Failed to connect to debug endpoint: ${error.message}` };
          }
        }
      }
    ]
  });
});

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

The total price on the checkout page seems wrong. Query the orders table for my
last order to verify the subtotal and tax values and see what may be causing the
problem, if any.

مثال على تنفيذ الوكيل: يستدعي وكيلك queryDatabaseTable لجدول الطلبات. يستردّ الوكيل سجل JSON ويحدّد خطأ في احتساب الضرائب في الخلفية، ويقترح إصلاحًا لمنطق الخادم.

في ما يلي بعض الملاحظات المهمة بشأن مثال هذه الأداة:

• الأمان والمصادقة: لست بحاجة إلى تمرير بيانات اعتماد قاعدة البيانات إلى وكيل الذكاء الاصطناعي. يستخدم طلب fetch جلسة تسجيل الدخول الحالية للمتصفّح لتفويض الطلب على الخلفية.
• تصحيح الأخطاء القابل للتنفيذ: إذا رصد وكيل الذكاء الاصطناعي خطأ في واجهة المستخدم، يمكنه على الفور استدعاء queryDatabaseTable لمعرفة ما إذا كان الخطأ موجودًا في البيانات المصدر أو في عملية الاحتساب في الواجهة الأمامية.
• الإعداد البسيط: ما عليك سوى عرض نقطة نهاية تصحيح أخطاء "آمنة" واحدة (للقراءة فقط) على خادمك تقبل اسم جدول وتعرض JSON. لا يهم إطار العمل الذي تستخدمه لإنشاء نقطة النهاية هذه.