有了第三方開發人員工具，程式碼代理程式就能查看 DOM、網路要求和控制台記錄檔以外的內容。直接從網站或框架公開自訂工具，即可讓代理與原本無法存取的應用程式狀態和資料互動。
這些工具是透過 JavaScript 建立，且會在網頁載入時，由 Chrome 開發人員工具自動探索代理程式。
瞭解第三方開發人員工具
在程式碼編寫代理的環境中，工具是代理可執行的現成函式，以代理程式專用的開發人員工具為例，這類工具可直接向程式碼編寫代理程式公開內部執行階段狀態，縮小算繪輸出內容與內部邏輯之間的差距。
使用第三方工具時，請注意下列事項：
- 執行階段探索。當應用程式回應 Chrome 開發人員工具為全域
window物件上的代理程式發出的devtoolstooldiscovery事件時，系統就會自動偵測工具。 - 情境範圍。工具只會在定義工具的頁面環境中執行。不會在來源和頁面重新載入時保留。
- 工具專一性。工具只是代理執行工作的額外方式，這項功能可能會偏好使用內建工具，或運用模型的基本功能來完成提示。因此，請盡可能使用描述性名稱和說明。
必要條件
導入第三方工具前，請確認您符合下列需求：
- 代理程式專用的 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;
},
},
],
});
},
);
如要在應用程式中註冊工具，請按照下列步驟操作：
定義工具群組。建立包含名稱、說明和個別工具定義陣列的
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[]; }監聽探索事件。代理程式專用的 Chrome 開發人員工具會在每次導覽後，以及需要更新可用工具清單時，在全域
window物件上分派自訂devtoolstooldiscovery事件。註冊工具。呼叫事件的
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;
},
}
第三方開發人員工具的應用實例
指示代理程式檢查深層應用程式邏輯，而不只是表面層級的 UI 元素。使用這些自訂工具，簡化有狀態或架構繁重的應用程式偵錯作業。
尋找工具的訣竅
撰寫明確的工具名稱和說明，代理會根據這些說明決定要使用哪些工具，因此清楚的語言有助於代理自主判斷工具是否適合用於特定工作。
偵錯應用程式專屬的執行階段指標
無聲快取未命中或多餘的 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 工具。這會叫用工具、分析傳回的命中/未命中比率，並識別前端不必要地重新擷取整個管道，而非更新本機快取。
檢查功能旗標
定義自訂資料點，顯示特定使用者工作階段目前啟用的環境變數或功能標記。這有助於偵錯，瞭解特定使用者是否能看到某些功能，如果使用者回報錯誤，服務專員可以確認使用者是否屬於可能導致問題的實驗群組。
舉例來說，您可以建立類似下方的工具，傳回內部功能旗標狀態：
// 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.
代理執行範例：代理會使用 path 參數呼叫 getGlobalState。這項功能會從購物車擷取商品清單，並找出內部狀態與網頁上顯示的商品之間的差異。
這個工具範例有幾項重要注意事項：
- 邏輯分離：AI 代理會詢問「州別」。開發人員可以決定如何將該要求對應至
execute函式中的實際資料結構。 - 目標式偵錯：加入
path參數後，代理程式可以避免提取整個狀態樹 (可能很大)，只專注於相關部分，節省權杖並提升效能。 - 標準化介面：即使切換狀態管理程式庫，只要更新這個
execute函式，AI 偵錯代理程式就不需要任何新指令或工具。
檢查資料庫內容
透過唯讀偵錯端點直接查詢資料庫記錄，確認後端資料與 UI 狀態相符。
公開安全偵錯端點，並建立類似這樣的工具，驗證後端記錄：
// 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 代理程式發現 UI 錯誤，可以立即呼叫
queryDatabaseTable，查看來源資料或前端計算中是否有錯誤。 - 最簡單的設定：您只需要在伺服器上公開一個「安全」(唯讀) 的偵錯端點，接受資料表名稱並傳回 JSON 即可。您使用哪個架構建構該端點並不重要。