Gli strumenti per sviluppatori di terze parti consentono agli agenti di codifica di vedere oltre il DOM, le richieste di rete e i log della console. Se esponi strumenti personalizzati direttamente dal tuo sito web o framework, consenti al tuo agente di interagire con lo stato e i dati dell'applicazione altrimenti inaccessibili.
Questi strumenti vengono creati tramite JavaScript e vengono rilevati automaticamente da Chrome DevTools per gli agenti quando la pagina viene caricata.
Informazioni sugli strumenti per sviluppatori di terze parti
Nel contesto degli agenti di codifica, gli strumenti sono funzioni predefinite che gli agenti possono utilizzare per eseguire azioni specifiche. Per DevTools per gli agenti in particolare, questi strumenti possono esporre il relativo stato di runtime interno direttamente agli agenti di codifica, colmando il divario tra l'output sottoposto a rendering e la logica interna.
Quando utilizzi strumenti di terze parti, tieni presente quanto segue:
- Rilevamento di runtime. Gli strumenti vengono rilevati automaticamente quando l'applicazione risponde all'evento
devtoolstooldiscoveryemesso da Chrome DevTools per gli agenti sull'oggettowindowglobale. - Ambito di contesto. Gli strumenti vengono eseguiti solo nel contesto della pagina che li definisce. Non vengono mantenuti tra le origini e i ricaricamenti delle pagine.
- Specificità dello strumento. Gli strumenti sono solo un modo aggiuntivo per l'agente di eseguire un'attività. Potrebbe preferire gli strumenti integrati o le funzionalità del modello di base per soddisfare una richiesta. Quindi, rendi i nomi e le descrizioni degli strumenti il più descrittivi possibile.
Prerequisiti
Prima di implementare strumenti di terze parti, assicurati di soddisfare i seguenti requisiti:
- Chrome DevTools per gli agenti. Utilizza la versione 0.25.0 o successive.
- JavaScript attivato. JavaScript deve essere attivato ed eseguito.
Implementare uno strumento
Per implementare uno strumento, devi ascoltare un evento di rilevamento specifico e rispondere con le definizioni dello strumento. Il seguente codice rappresenta una risposta che include le definizioni degli strumenti:
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;
},
},
],
});
},
);
Per registrare gli strumenti nella tua applicazione:
Definisci il gruppo di strumenti. Crea un
ToolGroupche contenga un nome, una descrizione e un array di definizioni di strumenti individuali.export interface ToolDefinition { name: string; description: string; inputSchema: JSONSchema7; execute: (args: Record<string, unknown>) => unknown; } export interface ToolGroup { name: string; description: string; tools: ToolDefinition[]; }Ascolta l'evento di rilevamento. Chrome DevTools per gli agenti invia un evento
devtoolstooldiscoverypersonalizzato sull'oggettowindowglobale dopo ogni navigazione e ogni volta che ha bisogno di un elenco aggiornato degli strumenti disponibili.Registra gli strumenti. Chiama il metodo
respondWith()dell'evento per fornire il gruppo di strumenti all'agente.
Componenti essenziali per i singoli strumenti
Ogni definizione di strumento che implementi deve includere le seguenti tre parti:
- Nome e descrizione. Questi forniscono le istruzioni che l'agente utilizza per decidere quando e come chiamare lo strumento.
- Schema di input. Uno schema JSON che definisce la struttura e i tipi di argomenti previsti dallo strumento.
- Funzione di esecuzione. Il codice JavaScript effettivo che viene eseguito sulla pagina quando l'agente richiama lo strumento.
L'esempio seguente mostra questi tre componenti in una singola definizione di strumento:
{
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;
},
}
Casi d'uso per gli strumenti per sviluppatori di terze parti
Chiedi all'agente di ispezionare la logica dell'applicazione in modo approfondito anziché solo gli elementi dell'interfaccia utente a livello di superficie. Utilizza questi strumenti personalizzati per semplificare il debug delle applicazioni con stato o con molti framework.
Suggerimenti per il rilevamento degli strumenti
Scrivi nomi e descrizioni degli strumenti descrittivi. Gli agenti utilizzano queste descrizioni come contesto per decidere quale strumento utilizzare. Un linguaggio chiaro aiuta l'agente a determinare autonomamente quando uno strumento è appropriato per un'attività.
Eseguire il debug delle metriche di runtime specifiche dell'applicazione
Problemi come gli errori di cache silenziosi o le chiamate API ridondanti sono spesso invisibili all'ispezione standard. Se esponi le statistiche interne, l'agente può spiegare perché si è verificato un determinato comportamento.
Supponiamo di avere una funzione che espone le statistiche interne. Innanzitutto, devi creare uno strumento come questo:
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();
}
}
]
});
});
Se la descrizione dello strumento è chiara, l'agente potrebbe utilizzare lo strumento autonomamente quando lo ritiene opportuno. Puoi chiedere all'agente di eseguire un'attività utilizzando lo strumento come segue:
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.
Esempio di esecuzione dell'agente:l'agente rileva lo strumento getCacheStatistics esposto dalla tua applicazione. Richiama lo strumento, analizza il rapporto tra hit e mancati risultati restituiti e identifica che il frontend sta recuperando inutilmente l'intera pipeline anziché aggiornare la cache locale.
Controllare i flag funzionalità
Definisci punti dati personalizzati per esporre le variabili di ambiente correnti o i flag funzionalità attivi per una sessione utente specifica. In questo modo puoi eseguire il debug e capire perché alcune funzionalità sono visibili o meno a utenti specifici. Se un utente segnala un bug, l'agente può verificare se fa parte di un gruppo di esperimenti che potrebbe causare il problema.
Ad esempio, crea uno strumento come questo per restituire lo stato del flag funzionalità interno:
// 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'
};
}
}
]
});
});
Se la descrizione dello strumento è chiara, l'agente potrebbe utilizzare lo strumento autonomamente quando lo ritiene opportuno. Puoi chiedere all'agente di eseguire un'attività utilizzando lo strumento come segue:
Check the active feature flags and tell me if the new-ui-enabled flag is set to
true for this session.
Esempio di esecuzione dell'agente: l'agente richiama lo strumento getFeatureFlags,
conferma che il flag new-ui-enabled è attivo e procede al debug dei
componenti associati alla nuova interfaccia.
Ispezionare lo stato dell'applicazione globale
Espone l'albero dello stato di runtime dell'applicazione per aiutare l'agente a comprendere la logica interna senza recuperare l'intero DOM.
Puoi creare uno strumento come questo per eseguire query su percorsi specifici nell'albero degli stati, ad esempio:
// 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);
}
}
]
});
});
Se la descrizione dello strumento è chiara, l'agente potrebbe utilizzare lo strumento autonomamente quando lo ritiene opportuno. Puoi chiedere all'agente di eseguire un'attività utilizzando lo strumento come segue:
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.
Esempio di esecuzione dell'agente: l'agente chiama getGlobalState con il path
parametro. Recupera l'elenco degli articoli dal carrello e identifica una discrepanza tra lo stato interno e gli articoli sottoposti a rendering nella pagina.
Di seguito sono riportate alcune note importanti relative a questo esempio di strumento:
- Logica disaccoppiata: l'agente AI chiede "stato". In qualità di sviluppatore, decidi come mappare questa richiesta alla struttura dei dati effettiva nella funzione
execute. - Debug mirato: includendo il parametro
path, l'agente può evitare di estrarre l'intero albero degli stati (che potrebbe essere enorme) e concentrarsi solo sulla parte pertinente, risparmiando token e migliorando le prestazioni. - Interfaccia standardizzata: anche se cambi le librerie di gestione dello stato,
se aggiorni questa funzione
execute, l'agente di debug AI non avrà bisogno di nuove istruzioni o strumenti.
Ispezionare i contenuti del database
Verifica che i dati di backend corrispondano allo stato dell'interfaccia utente eseguendo query sui record del database direttamente tramite un endpoint di debug di sola lettura.
Espone un endpoint di debug sicuro e crea uno strumento come questo per verificare i record di 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}` };
}
}
}
]
});
});
Se la descrizione dello strumento è chiara, l'agente potrebbe utilizzare lo strumento autonomamente quando lo ritiene opportuno. Puoi chiedere all'agente di eseguire un'attività utilizzando lo strumento come segue:
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.
Esempio di esecuzione dell'agente: l'agente chiama queryDatabaseTable per la
tabella degli ordini. Recupera il record JSON, identifica un errore nel calcolo delle imposte del backend e suggerisce una correzione per la logica del server.
Di seguito sono riportate alcune note importanti relative a questo esempio di strumento:
- Sicurezza e autenticazione: non devi passare le credenziali del database
all'agente AI. La chiamata
fetchutilizza la sessione di accesso corrente del browser per autorizzare la richiesta sul backend. - Debug eseguibile: se un agente AI identifica un bug dell'interfaccia utente, può
chiamare immediatamente
queryDatabaseTableper verificare se l'errore esiste nei dati di origine o nel calcolo del frontend. - Configurazione minima: devi solo esporre un endpoint di debug "sicuro" (di sola lettura) sul server che accetta un nome di tabella e restituisce JSON. Il framework che utilizzi per creare l'endpoint non ha importanza.