חשיפת מצבים של אפליקציות בהתאמה אישית לסוכני AI באמצעות כלים של צד שלישי

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;
  },
}

תרחישי שימוש בכלים של צד שלישי למפתחים

מנחים את הסוכן לבדוק את הלוגיקה המורכבת של האפליקציה ולא רק את רכיבי ממשק המשתמש ברמה הבסיסית. אפשר להשתמש בכלים המותאמים אישית האלה כדי לייעל את ניפוי הבאגים באפליקציות עם מצב או באפליקציות שמסתמכות על מסגרות עבודה.

טיפים לגילוי כלים

כדאי לכתוב שמות ותיאורים תמציתיים לכלים. הסוכנים משתמשים בתיאורים האלה כהקשר כדי להחליט באיזה כלי להשתמש. שפה ברורה עוזרת לסוכן לקבוע באופן אוטונומי מתי כלי מתאים למשימה.

ניפוי באגים במדדי זמן ריצה ספציפיים לאפליקציה

בעיות כמו החמצות מטמון שקטות או קריאות API מיותרות לרוב לא נראות בבדיקה רגילה. הסוכן יכול להסביר למה התרחשה התנהגות מסוימת, על ידי הצגת נתונים סטטיסטיים פנימיים.

נניח שיש לכם פונקציה שחושפת נתונים סטטיסטיים פנימיים. קודם כול, אתם צריכים ליצור כלי כמו זה:

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 שנחשף על ידי האפליקציה. הכלי מופעל, מנתח את יחס הפגיעות במטמון, ומזהה שהקצה הקדמי שולף מחדש את כל הפייפליין שלא לצורך, במקום לעדכן את המטמון המקומי.

בדיקת סימוני תכונות

אתם יכולים להגדיר נקודות נתונים מותאמות אישית כדי לחשוף את משתני הסביבה הנוכחיים או את דגלי התכונות שפעילים בסשן משתמש ספציפי. כך תוכלו לנפות באגים כדי להבין למה תכונות מסוימות מוצגות למשתמשים ספציפיים או לא מוצגות להם. אם משתמש מדווח על באג, הנציג יכול לבדוק אם הוא נמצא בקבוצת ניסוי שעשויה לגרום לבעיה.

לדוגמה, אפשר ליצור כלי כמו זה כדי להחזיר את המצב של feature flag פנימי:

// 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. הוא מאחזר את רשימת הפריטים מעגלת הקניות ומזהה אי התאמה בין המצב הפנימי לבין הפריטים שמוצגים בדף.

כמה הערות חשובות לגבי דוגמה זו של כלי:

• לוגיקה מנותקת: סוכן ה-AI מבקש "מצב". אתם, כמפתחים, מחליטים איך למפות את הבקשה הזו למבנה הנתונים בפועל בפונקציה execute.
• ניפוי באגים ממוקד: הכללת הפרמטר path מאפשרת לסוכן להימנע משליפה של כל עץ המצב (שיכול להיות גדול מאוד) ולהתמקד רק בחלק הרלוונטי, וכך לחסוך באסימונים ולשפר את הביצועים.
• ממשק סטנדרטי: גם אם מחליפים ספריות לניהול מצב, כל עוד מעדכנים את הפונקציה execute הזו, לא צריך לתת לסוכן ה-AI לניפוי באגים הוראות או כלים חדשים.

בדיקת התוכן של מסד הנתונים

כדי לוודא שהנתונים בקצה העורפי תואמים למצב בממשק המשתמש, אפשר לשלוח שאילתה לרשומות במסד הנתונים ישירות דרך נקודת קצה לניפוי באגים שהגישה אליה היא לקריאה בלבד.

חשיפת נקודת קצה בטוחה לניפוי באגים ויצירת כלי כמו זה כדי לאמת רשומות של קצה עורפי:

// 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, מזהה שגיאה בחישוב המס של העורף ומציע תיקון ללוגיקה של השרת.

כמה הערות חשובות לגבי דוגמה זו של כלי:

• אבטחה ואימות: לא צריך להעביר את פרטי הכניסה למסד הנתונים לסוכן ה-AI. הקריאה fetch משתמשת בסשן ההתחברות הנוכחי של הדפדפן כדי לאשר את הבקשה בשרת העורפי.
• ניפוי באגים שניתן לפעול לפיו: אם סוכן AI מזהה באג בממשק המשתמש, הוא יכול להתקשר מיד אל queryDatabaseTable כדי לבדוק אם השגיאה קיימת בנתוני המקור או בחישוב של קצה קדמי.
• הגדרה מינימלית: אתם צריכים לחשוף בשרת רק נקודת קצה אחת של ניפוי באגים שהיא "בטוחה" (לקריאה בלבד), שמקבלת שם של טבלה ומחזירה JSON. לא משנה באיזו מסגרת אתם משתמשים כדי ליצור את נקודת הקצה הזו.