Benutzerdefinierte Anwendungsstatus mit Drittanbietertools für KI-Agents verfügbar machen

Matthias Rohmer

José Luis Zapata

Mit Entwicklertools von Drittanbietern können Coding-Agenten mehr als nur das DOM, Netzwerkanfragen und Konsolenlogs sehen. Wenn Sie benutzerdefinierte Tools direkt von Ihrer Website oder Ihrem Framework aus zur Verfügung stellen, kann Ihr Agent mit Anwendungsstatus und -daten interagieren, auf die er sonst keinen Zugriff hätte.

Diese Tools werden mit JavaScript erstellt und beim Laden Ihrer Seite automatisch von Chrome-Entwicklertools für Agenten erkannt.

Entwicklertools von Drittanbietern

Im Zusammenhang mit Coding-Agenten sind Tools vorgefertigte Funktionen, mit denen Agenten bestimmte Aktionen ausführen können. Bei DevTools für Agenten können solche Tools den internen Laufzeitstatus direkt für Coding-Agenten verfügbar machen und so die Lücke zwischen gerenderter Ausgabe und interner Logik schließen.

Beachten Sie bei der Verwendung von Tools von Drittanbietern Folgendes:

• Laufzeiterkennung Tools werden automatisch erkannt, wenn Ihre Anwendung auf das Ereignis devtoolstooldiscovery antwortet, das von Chrome DevTools für Agenten im globalen window-Objekt ausgegeben wird.
• Kontextbereich Tools werden nur im Kontext der Seite ausgeführt, auf der sie definiert sind. Sie bleiben nicht über Ursprünge und Seitenneuladungen hinweg bestehen.
• Toolspezifität Tools sind nur eine zusätzliche Möglichkeit für Ihren Agenten, eine Aufgabe auszuführen. Möglicherweise bevorzugt er integrierte Tools oder die reinen Modellfunktionen, um eine Eingabeaufforderung zu erfüllen. Daher sollten Toolnamen und -beschreibungen so aussagekräftig wie möglich sein.

Vorbereitung

Bevor Sie Tools von Drittanbietern implementieren, müssen Sie die folgenden Anforderungen erfüllen:

• Chrome-Entwicklertools für Agenten Verwenden Sie Version 0.25.0 oder höher.
• JavaScript aktiviert JavaScript muss aktiviert sein und ausgeführt werden.

Tool implementieren

Wenn Sie ein Tool implementieren möchten, müssen Sie auf ein bestimmtes Erkennungsereignis warten und mit Ihren Tooldefinitionen antworten. Der folgende Code stellt eine Antwort mit Tooldefinitionen dar:

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

So registrieren Sie Tools in Ihrer Anwendung:

1. Toolgruppe definieren Erstellen Sie eine ToolGroup mit einem Namen, einer Beschreibung und einem Array mit einzelnen Tooldefinitionen.

   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. Auf das Erkennungsereignis warten Chrome-Entwicklertools für Agenten sendet nach jeder Navigation und immer dann, wenn eine aktualisierte Liste der verfügbaren Tools benötigt wird, ein benutzerdefiniertes devtoolstooldiscovery-Ereignis an das globale window-Objekt.

3. Tools registrieren Rufen Sie die Methode respondWith() des Ereignisses auf, um dem Agenten Ihre Toolgruppe zur Verfügung zu stellen.

Wichtige Komponenten für einzelne Tools

Jede von Ihnen implementierte Tooldefinition muss die folgenden drei Teile enthalten:

• Name und Beschreibung Diese enthalten die Anweisungen, anhand derer der Agent entscheidet, wann und wie er Ihr Tool aufrufen soll.
• Eingabeschema Ein JSON-Schema, das die Struktur und die Typen der Argumente definiert, die das Tool erwartet.
• Ausführungsfunktion Der tatsächliche JavaScript-Code, der auf der Seite ausgeführt wird, wenn der Agent das Tool aufruft.

Im folgenden Beispiel sind diese drei Komponenten in einer einzelnen Tooldefinition dargestellt:

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

Anwendungsfälle für Entwicklertools von Drittanbietern

Weisen Sie Ihren Agenten an, die detaillierte Anwendungslogik zu prüfen und nicht nur UI-Elemente auf der Oberfläche. Mit diesen benutzerdefinierten Tools können Sie das Debugging von zustandsorientierten oder frameworklastigen Anwendungen optimieren.

Tipps zur Toolerkennung

Verwenden Sie aussagekräftige Toolnamen und -beschreibungen. Agenten verwenden diese Beschreibungen als Kontext, um zu entscheiden, welches Tool verwendet werden soll. Eine klare Sprache hilft dem Agenten, selbstständig zu entscheiden, wann ein Tool für eine Aufgabe geeignet ist.

Anwendungsspezifische Laufzeitmesswerte debuggen

Probleme wie stille Cache-Fehler oder redundante API-Aufrufe sind bei der Standardprüfung oft nicht sichtbar. Wenn Sie interne Statistiken zur Verfügung stellen, kann Ihr Agent erklären, warum ein bestimmtes Verhalten aufgetreten ist.

Angenommen, Sie haben eine Funktion, die interne Statistiken zur Verfügung stellt. Zuerst müssen Sie ein Tool wie dieses erstellen:

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

Wenn Ihre Toolbeschreibung klar ist, kann Ihr Agent das Tool bei Bedarf selbstständig verwenden. Sie können Ihren Agenten auffordern, eine Aufgabe mit dem Tool auszuführen, z. B. so:

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.

Beispiel für die Ausführung des Agenten:Ihr Agent erkennt das Tool getCacheStatistics, das von Ihrer Anwendung zur Verfügung gestellt wird. Er ruft das Tool auf, analysiert das zurückgegebene Verhältnis von Treffern zu Fehlern und stellt fest, dass das Frontend die gesamte Pipeline unnötigerweise neu abruft, anstatt den lokalen Cache zu aktualisieren.

Funktions-Flags prüfen

Definieren Sie benutzerdefinierte Datenpunkte, um die aktuellen Umgebungsvariablen oder Funktions-Flags verfügbar zu machen, die für eine bestimmte Nutzersitzung aktiv sind. So können Sie debuggen, warum bestimmte Funktionen für bestimmte Nutzer sichtbar sind oder nicht. Wenn ein Nutzer einen Fehler meldet, kann der Agent prüfen, ob er sich in einer Testgruppe befindet, die das Problem möglicherweise verursacht.

Erstellen Sie beispielsweise ein Tool wie dieses, um den internen Status des Funktions-Flags zurückzugeben:

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

Wenn Ihre Toolbeschreibung klar ist, kann Ihr Agent das Tool bei Bedarf selbstständig verwenden. Sie können Ihren Agenten auffordern, eine Aufgabe mit dem Tool auszuführen, z. B. so:

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

Beispiel für die Ausführung des Agenten: Ihr Agent ruft das Tool getFeatureFlags auf, bestätigt, dass das Flag new-ui-enabled aktiv ist, und debuggt dann die Komponenten, die mit der neuen Benutzeroberfläche verknüpft sind.

Globalen Anwendungsstatus prüfen

Stellen Sie die Laufzeitstatusstruktur Ihrer Anwendung zur Verfügung, damit Ihr Agent die interne Logik verstehen kann, ohne das gesamte DOM abrufen zu müssen.

Sie können ein Tool wie dieses erstellen, um bestimmte Pfade in Ihrer Statusstruktur abzufragen, z. B. so:

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

Wenn Ihre Toolbeschreibung klar ist, kann Ihr Agent das Tool bei Bedarf selbstständig verwenden. Sie können Ihren Agenten auffordern, eine Aufgabe mit dem Tool auszuführen, z. B. so:

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.

Beispiel für die Ausführung des Agenten: Ihr Agent ruft getGlobalState mit dem path Parameter auf. Er ruft die Liste der Artikel aus dem Warenkorb ab und stellt eine Diskrepanz zwischen dem internen Status und den auf der Seite gerenderten Artikeln fest.

Einige wichtige Hinweise zu diesem Toolbeispiel:

• Entkoppelte Logik: Der KI-Agent fragt nach „Status“. Sie als Entwickler entscheiden in der Funktion execute, wie diese Anfrage Ihrer tatsächlichen Datenstruktur zugeordnet wird.
• Gezieltes Debugging: Wenn Sie den Parameter path einfügen, kann der Agent vermeiden, die gesamte Statusstruktur abzurufen (die sehr groß sein kann), und sich nur auf den relevanten Teil konzentrieren. So werden Tokens gespart und die Leistung verbessert.
• Standardisierte Schnittstelle: Auch wenn Sie die Bibliotheken für die Statusverwaltung wechseln, benötigt Ihr KI-Debugging-Agent keine neuen Anweisungen oder Tools, solange Sie diese eine execute-Funktion aktualisieren.

Datenbankinhalte prüfen

Prüfen Sie, ob Ihre Backend-Daten mit dem UI-Status übereinstimmen, indem Sie Datenbankeinträge direkt über einen schreibgeschützten Debug-Endpunkt abfragen.

Stellen Sie einen sicheren Debug-Endpunkt zur Verfügung und erstellen Sie ein Tool wie dieses, um Backend-Einträge zu prüfen:

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

Wenn Ihre Toolbeschreibung klar ist, kann Ihr Agent das Tool bei Bedarf selbstständig verwenden. Sie können Ihren Agenten auffordern, eine Aufgabe mit dem Tool auszuführen, z. B. so:

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.

Beispiel für die Ausführung des Agenten: Ihr Agent ruft queryDatabaseTable für die Tabelle „orders“ auf. Er ruft den JSON-Eintrag ab, erkennt einen Fehler bei der Steuerberechnung im Backend und schlägt eine Korrektur für die Serverlogik vor.

Einige wichtige Hinweise zu diesem Toolbeispiel:

• Sicherheit und Authentifizierung: Sie müssen dem KI-Agenten keine Datenbankanmeldedaten übergeben. Der fetch-Aufruf verwendet die aktuelle Anmeldesitzung des Browsers, um die Anfrage in Ihrem Backend zu autorisieren.
• Umsetzbares Debugging: Wenn ein KI-Agent einen UI-Fehler erkennt, kann er sofort queryDatabaseTable aufrufen, um zu prüfen, ob der Fehler in den Quelldaten oder in der Frontend-Berechnung liegt.
• Minimale Einrichtung: Sie müssen nur einen „sicheren“ (schreibgeschützten) Debug- Endpunkt auf Ihrem Server zur Verfügung stellen, der einen Tabellennamen akzeptiert und JSON zurückgibt. Das Framework, mit dem Sie diesen Endpunkt erstellen, spielt keine Rolle.