借助第三方开发者工具，编码智能体可以查看 DOM、网络请求和控制台日志之外的内容。通过直接从您的网站或框架中公开自定义工具，您可以让智能体与原本无法访问的应用状态和数据进行交互。
这些工具通过 JavaScript 创建，当网页加载时，Chrome 开发者工具会自动为代理发现这些工具。
了解第三方开发者工具
在编码代理的背景下，工具是代理执行特定操作的现成函数。对于智能体专用开发者工具，此类工具可以直接向编码智能体公开其内部运行时状态，从而弥合渲染输出与内部逻辑之间的差距。
使用第三方工具时，请注意以下几点：
- 运行时发现。当应用响应 Chrome DevTools 为全局
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;
},
}
第三方开发者工具的应用场景
指示代理检查深层应用逻辑，而不仅仅是表面级界面元素。使用这些自定义工具可简化有状态应用或框架密集型应用的调试。
工具发现提示
添加吸引眼球的工具名称和说明，让您的工具脱颖而出。智能体会将这些说明用作上下文来决定使用哪个工具，清晰的语言有助于智能体自主确定何时使用某个工具来完成任务。
调试应用特定的运行时指标
静默缓存未命中或冗余 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 工具。它会调用该工具，分析返回的命中与未命中比率，并确定前端不必要地重新提取整个流水线，而不是更新本地缓存。
检查功能标志
定义自定义数据点，以公开特定用户会话的当前环境变量或有效的功能标志。这有助于您调试特定用户看到或看不到某些功能的原因。如果用户报告了 bug，客服人员可以验证用户是否属于可能导致该问题的实验组。
例如，创建如下工具以返回内部功能标志状态：
// 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参数，代理可以避免提取整个状态树（可能非常庞大），而只专注于相关部分，从而节省 token 并提高性能。 - 标准化接口：即使您切换了状态管理库，只要更新此
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。您用于构建该端点的框架并不重要。