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

Matthias Rohmer

José Luis Zapata

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

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

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

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

عند استخدام أدوات تابعة لجهات خارجية، يُرجى مراعاة ما يلي:

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