Mengekspos status aplikasi kustom ke agen AI dengan alat pihak ketiga

Matthias Rohmer

José Luis Zapata

Alat developer pihak ketiga memungkinkan agen coding melihat di luar DOM, permintaan jaringan, dan log konsol. Dengan mengekspos alat kustom langsung dari situs atau framework Anda, Anda mengizinkan agen Anda berinteraksi dengan status dan data aplikasi yang tidak dapat diakses.

Alat ini dibuat melalui JavaScript dan otomatis ditemukan oleh Chrome DevTools untuk agen saat halaman Anda dimuat.

Memahami alat developer pihak ketiga

Dalam konteks agen coding, alat adalah fungsi siap pakai untuk agen melakukan tindakan tertentu. Khusus untuk DevTools untuk agen, alat tersebut dapat mengekspos status runtime internalnya langsung ke agen coding, sehingga menjembatani kesenjangan antara output yang dirender dan logika internal.

Saat menggunakan alat pihak ketiga, perhatikan hal berikut:

• Penemuan runtime. Alat akan otomatis terdeteksi saat aplikasi Anda merespons peristiwa devtoolstooldiscovery yang ditampilkan oleh Chrome DevTools untuk agen pada objek window global.
• Cakupan konteks. Alat hanya dijalankan dalam konteks halaman yang menentukannya. Alat tidak dipertahankan di seluruh asal dan pemuatan ulang halaman.
• Spesifisitas alat. Alat hanya merupakan cara tambahan bagi agen Anda untuk melakukan tugas. Agen mungkin lebih memilih alat bawaan, atau kemampuan model kosong untuk memenuhi perintah. Jadi, buat nama dan deskripsi alat sejelas mungkin.

Prasyarat

Sebelum menerapkan alat pihak ketiga, pastikan Anda memenuhi persyaratan berikut:

• Chrome DevTools untuk agen. Gunakan versi 0.25.0 atau yang lebih baru.
• JavaScript diaktifkan. JavaScript harus diaktifkan dan dijalankan.

Menerapkan alat

Untuk menerapkan alat, Anda memproses peristiwa penemuan tertentu dan merespons dengan definisi alat Anda. Kode berikut mewakili respons yang menyertakan definisi alat:

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

Untuk mendaftarkan alat di aplikasi Anda:

1. Tentukan grup alat Anda. Buat ToolGroup yang berisi nama, deskripsi, dan array definisi alat individual.

   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. Proses peristiwa penemuan. Chrome DevTools untuk agen mengirimkan peristiwa devtoolstooldiscovery kustom pada objek window global setelah setiap navigasi dan setiap kali memerlukan daftar alat yang tersedia yang diperbarui.

3. Daftarkan alat Anda. Panggil metode respondWith() peristiwa untuk memberikan grup alat Anda kepada agen.

Komponen penting untuk alat individual

Setiap definisi alat yang Anda terapkan harus menyertakan tiga bagian berikut:

• Nama dan deskripsi. Bagian ini memberikan petunjuk yang digunakan agen untuk memutuskan kapan dan bagaimana memanggil alat Anda.
• Skema input. Skema JSON yang menentukan struktur dan jenis argumen yang diharapkan alat.
• Fungsi eksekusi. Kode JavaScript sebenarnya yang berjalan di halaman saat agen memanggil alat.

Contoh berikut menunjukkan ketiga komponen ini dalam satu definisi alat:

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

Kasus penggunaan untuk alat developer pihak ketiga

Instruksikan agen Anda untuk memeriksa logika aplikasi yang mendalam, bukan hanya elemen UI tingkat atas. Gunakan alat kustom ini untuk menyederhanakan proses debug aplikasi stateful atau yang menggunakan banyak framework.

Tips untuk penemuan alat

Tulis nama dan deskripsi alat yang deskriptif. Agen menggunakan deskripsi ini sebagai konteks untuk memutuskan alat mana yang akan digunakan. Bahasa yang jelas membantu agen menentukan secara mandiri kapan alat sesuai untuk tugas.

Melakukan debug metrik runtime khusus aplikasi

Masalah seperti cache yang tidak ada atau panggilan API yang berlebihan sering kali tidak terlihat oleh pemeriksaan standar. Dengan mengekspos statistik internal, agen Anda dapat menjelaskan mengapa perilaku tertentu terjadi.

Misalkan Anda memiliki fungsi yang mengekspos statistik internal; pertama, Anda harus membuat alat seperti ini:

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();
        }
      }
    ]
  });
});

Jika deskripsi alat Anda jelas, agen Anda mungkin menggunakan alat secara mandiri jika dianggap sesuai. Anda dapat meminta agen Anda untuk melakukan tugas menggunakan alat seperti berikut:

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.

Contoh eksekusi agen: Agen Anda mendeteksi alat getCacheStatistics yang diekspos oleh aplikasi Anda. Agen memanggil alat, menganalisis rasio hit yang ditampilkan untuk tidak ada, dan mengidentifikasi bahwa frontend mengambil ulang seluruh pipeline secara tidak perlu, bukan mengupdate cache lokal.

Memeriksa feature flag

Tentukan titik data kustom untuk mengekspos variabel lingkungan saat ini atau feature flag yang aktif untuk sesi pengguna tertentu. Hal ini membantu Anda melakukan debug mengapa fitur tertentu terlihat atau tidak terlihat oleh pengguna tertentu. Jika pengguna melaporkan bug, agen dapat memverifikasi apakah pengguna tersebut berada dalam grup eksperimen yang mungkin menyebabkan masalah.

Misalnya, buat alat seperti ini untuk menampilkan status tombol fitur internal:

// 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'
          };
        }
      }
    ]
  });
});

Jika deskripsi alat Anda jelas, agen Anda mungkin menggunakan alat secara mandiri jika dianggap sesuai. Anda dapat meminta agen Anda untuk melakukan tugas menggunakan alat seperti berikut:

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

Contoh eksekusi agen: Agen Anda memanggil alat getFeatureFlags, mengonfirmasi bahwa flag new-ui-enabled aktif, dan melanjutkan untuk melakukan debug komponen yang terkait dengan antarmuka baru.

Memeriksa status aplikasi global

Ekspos hierarki status runtime aplikasi Anda untuk membantu agen Anda memahami logika internal tanpa mengambil seluruh DOM.

Anda dapat membuat alat seperti ini untuk membuat kueri jalur tertentu di hierarki status Anda, seperti berikut:

// 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);
        }
      }
    ]
  });
});

Jika deskripsi alat Anda jelas, agen Anda mungkin menggunakan alat secara mandiri jika dianggap sesuai. Anda dapat meminta agen Anda untuk melakukan tugas menggunakan alat seperti berikut:

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.

Contoh eksekusi agen: Agen Anda memanggil getGlobalState dengan path parameter. Agen mengambil daftar item dari keranjang dan mengidentifikasi perbedaan antara status internal dan item yang dirender di halaman.

Beberapa catatan penting terkait contoh alat ini:

• Logika yang dipisahkan: Agen AI meminta "status". Anda, sebagai developer, memutuskan cara memetakan permintaan tersebut ke struktur data sebenarnya dalam fungsi execute.
• Debug yang Ditargetkan: Dengan menyertakan parameter path, agen dapat menghindari pengambilan seluruh hierarki status (yang mungkin sangat besar) dan hanya berfokus pada bagian yang relevan, sehingga menghemat token dan meningkatkan performa.
• Antarmuka standar: Meskipun Anda mengganti library pengelolaan status, selama Anda mengupdate satu fungsi execute ini, agen debug AI Anda tidak memerlukan petunjuk atau alat baru.

Memeriksa Konten database

Pastikan data backend Anda cocok dengan status UI dengan membuat kueri rekaman database langsung melalui endpoint debug hanya baca.

Ekspos endpoint debug yang aman dan buat alat seperti ini untuk memverifikasi rekaman backend:

// 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}` };
          }
        }
      }
    ]
  });
});

Jika deskripsi alat Anda jelas, agen Anda mungkin menggunakan alat secara mandiri jika dianggap sesuai. Anda dapat meminta agen Anda untuk melakukan tugas menggunakan alat seperti berikut:

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.

Contoh eksekusi agen: Agen Anda memanggil queryDatabaseTable untuk tabel pesanan. Agen mengambil rekaman JSON, mengidentifikasi error dalam perhitungan pajak backend, dan menyarankan perbaikan untuk logika server.

Beberapa catatan penting terkait contoh alat ini:

• Keamanan dan autentikasi: Anda tidak perlu meneruskan kredensial database ke agen AI. Panggilan fetch menggunakan sesi login saat ini di browser untuk mengotorisasi permintaan di backend Anda.
• Debug yang dapat ditindaklanjuti: Jika agen AI mengidentifikasi bug UI, agen dapat langsung memanggil queryDatabaseTable untuk melihat apakah error ada dalam data sumber atau perhitungan frontend.
• Penyiapan minimal: Anda hanya perlu mengekspos satu "aman" (hanya baca) debug endpoint di server yang menerima nama tabel dan menampilkan JSON. Framework yang Anda gunakan untuk membuat endpoint tersebut tidak masalah.