Các công cụ dành cho nhà phát triển của bên thứ ba cho phép các tác nhân lập trình xem xét ngoài DOM, các yêu cầu mạng và nhật ký bảng điều khiển. Bằng cách hiển thị các công cụ tuỳ chỉnh ngay trên trang web hoặc khung của bạn, bạn cho phép tác nhân tương tác với trạng thái và dữ liệu ứng dụng mà nếu không thì không thể truy cập.
Những công cụ này được tạo thông qua JavaScript và được Chrome DevTools cho tác nhân tự động phát hiện khi trang của bạn tải.
Tìm hiểu về các công cụ dành cho nhà phát triển bên thứ ba
Trong bối cảnh của các tác nhân lập trình, công cụ là những hàm được tạo sẵn để các tác nhân thực hiện những hành động cụ thể. Cụ thể đối với DevTools cho các tác nhân, những công cụ như vậy có thể hiển thị trực tiếp trạng thái thời gian chạy nội bộ của công cụ cho các tác nhân mã hoá, thu hẹp khoảng cách giữa đầu ra được kết xuất và logic nội bộ.
Khi sử dụng công cụ của bên thứ ba, hãy lưu ý những điều sau:
- Khám phá trong thời gian chạy. Các công cụ sẽ tự động được phát hiện khi ứng dụng của bạn phản hồi sự kiện
devtoolstooldiscoverydo Chrome DevTools phát ra cho các tác nhân trên đối tượngwindowchung. - Phạm vi bối cảnh. Các công cụ chỉ thực thi trong ngữ cảnh của trang xác định các công cụ đó. Chúng không duy trì trên các nguồn gốc và lần tải lại trang.
- Tính cụ thể của công cụ. Công cụ chỉ là một cách bổ sung để tác nhân thực hiện một nhiệm vụ. Có thể Gemini sẽ ưu tiên các công cụ tích hợp hoặc các chức năng mô hình cơ bản để thực hiện một câu lệnh. Vì vậy, hãy đặt tên và nội dung mô tả cho công cụ một cách mô tả nhất có thể.
Điều kiện tiên quyết
Trước khi triển khai các công cụ của bên thứ ba, hãy đảm bảo bạn đáp ứng các yêu cầu sau:
- Chrome DevTools cho tác nhân. Sử dụng phiên bản 0.25.0 trở lên.
- Đã bật JavaScript. Đã bật và đang thực thi JavaScript.
Triển khai một công cụ
Để triển khai một công cụ, bạn sẽ lắng nghe một sự kiện khám phá cụ thể và phản hồi bằng các định nghĩa về công cụ của mình. Đoạn mã sau đây biểu thị một phản hồi bao gồm các định nghĩa về công cụ:
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;
},
},
],
});
},
);
Cách đăng ký các công cụ trong ứng dụng:
Xác định nhóm công cụ. Tạo một
ToolGroupchứa tên, nội dung mô tả và một mảng các định nghĩa công cụ riêng lẻ.export interface ToolDefinition { name: string; description: string; inputSchema: JSONSchema7; execute: (args: Record<string, unknown>) => unknown; } export interface ToolGroup { name: string; description: string; tools: ToolDefinition[]; }Theo dõi sự kiện khám phá. Chrome DevTools cho tác nhân gửi một sự kiện
devtoolstooldiscoverytuỳ chỉnh trên đối tượngwindowchung sau mỗi lần điều hướng và bất cứ khi nào cần danh sách mới về các công cụ hiện có.Đăng ký công cụ của bạn. Gọi phương thức
respondWith()của sự kiện để cung cấp nhóm công cụ cho tác nhân.
Các thành phần cần thiết cho từng công cụ
Mỗi định nghĩa công cụ mà bạn triển khai phải bao gồm 3 phần sau:
- Tên và nội dung mô tả. Các hướng dẫn này cung cấp thông tin để tác nhân quyết định thời điểm và cách gọi công cụ của bạn.
- Giản đồ đầu vào. Một Giản đồ JSON xác định cấu trúc và các loại đối số mà công cụ mong đợi.
- Hàm thực thi. Mã JavaScript thực tế chạy trên trang khi tác nhân gọi công cụ.
Ví dụ sau đây cho thấy 3 thành phần này trong một định nghĩa công cụ duy nhất:
{
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;
},
}
Trường hợp sử dụng công cụ dành cho nhà phát triển bên thứ ba
Hướng dẫn cho tác nhân của bạn kiểm tra logic ứng dụng chuyên sâu thay vì chỉ các thành phần giao diện người dùng ở cấp độ bề mặt. Sử dụng các công cụ tuỳ chỉnh này để đơn giản hoá việc gỡ lỗi các ứng dụng có trạng thái hoặc ứng dụng có nhiều khung.
Mẹo khám phá công cụ
Viết tên và nội dung mô tả rõ ràng cho công cụ. Các trợ lý ảo sử dụng những nội dung mô tả này làm ngữ cảnh để quyết định sử dụng công cụ nào. Ngôn ngữ rõ ràng giúp trợ lý ảo tự động xác định thời điểm một công cụ phù hợp với một tác vụ.
Gỡ lỗi các chỉ số thời gian chạy dành riêng cho ứng dụng
Những vấn đề như lỗi bộ nhớ đệm không báo cáo hoặc các lệnh gọi API dư thừa thường không xuất hiện trong quá trình kiểm tra tiêu chuẩn. Bằng cách hiển thị số liệu thống kê nội bộ, tác nhân có thể giải thích lý do xảy ra một hành vi nhất định.
Giả sử bạn có một hàm hiển thị số liệu thống kê nội bộ; trước tiên, bạn phải tạo một công cụ như công cụ này:
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();
}
}
]
});
});
Nếu nội dung mô tả công cụ của bạn rõ ràng, thì tác nhân có thể tự động sử dụng công cụ khi thấy phù hợp. Bạn có thể nhắc tác nhân thực hiện một việc bằng công cụ này, chẳng hạn như:
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.
Ví dụ về quá trình thực thi tác nhân: Tác nhân của bạn phát hiện công cụ getCacheStatistics do ứng dụng của bạn hiển thị. Thao tác này sẽ gọi công cụ, phân tích tỷ lệ truy cập/bỏ lỡ được trả về và xác định rằng giao diện người dùng đang tìm nạp lại toàn bộ quy trình một cách không cần thiết thay vì cập nhật bộ nhớ đệm cục bộ.
Kiểm tra cờ tính năng
Xác định các điểm dữ liệu tuỳ chỉnh để hiển thị các biến môi trường hiện tại hoặc cờ tính năng đang hoạt động cho một phiên người dùng cụ thể. Điều này giúp bạn gỡ lỗi để biết lý do một số tính năng nhất định có hoặc không hiển thị cho một số người dùng cụ thể. Nếu người dùng báo cáo một lỗi, thì nhân viên hỗ trợ có thể xác minh xem người dùng có thuộc một nhóm thử nghiệm có thể gây ra vấn đề hay không.
Ví dụ: tạo một công cụ như công cụ này để trả về trạng thái cờ tính năng nội bộ:
// 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'
};
}
}
]
});
});
Nếu nội dung mô tả công cụ của bạn rõ ràng, thì tác nhân có thể tự động sử dụng công cụ khi thấy phù hợp. Bạn có thể nhắc tác nhân thực hiện một việc bằng công cụ này, chẳng hạn như:
Check the active feature flags and tell me if the new-ui-enabled flag is set to
true for this session.
Ví dụ về việc thực thi tác nhân: Tác nhân của bạn gọi công cụ getFeatureFlags, xác nhận rằng cờ new-ui-enabled đang hoạt động và tiếp tục gỡ lỗi các thành phần được liên kết với giao diện mới.
Kiểm tra trạng thái ứng dụng chung
Hiển thị cây trạng thái thời gian chạy của ứng dụng để giúp tác nhân hiểu được logic nội bộ mà không cần tìm nạp toàn bộ DOM.
Bạn có thể tạo một công cụ như thế này để truy vấn các đường dẫn cụ thể trong cây trạng thái, chẳng hạn như sau:
// 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);
}
}
]
});
});
Nếu nội dung mô tả công cụ của bạn rõ ràng, thì tác nhân có thể tự động sử dụng công cụ khi thấy phù hợp. Bạn có thể nhắc tác nhân thực hiện một việc bằng công cụ này, chẳng hạn như:
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.
Ví dụ về việc thực thi tác nhân: Tác nhân của bạn gọi getGlobalState bằng tham số path. Thao tác này truy xuất danh sách các mặt hàng trong giỏ hàng và xác định sự khác biệt giữa trạng thái nội bộ và các mặt hàng được kết xuất trên trang.
Một số lưu ý quan trọng liên quan đến ví dụ về công cụ này:
- Logic tách biệt: Tác nhân AI yêu cầu "trạng thái". Bạn, với tư cách là nhà phát triển, sẽ quyết định cách liên kết yêu cầu đó với cấu trúc dữ liệu thực tế trong hàm
execute. - Gỡ lỗi có mục tiêu: Bằng cách thêm tham số
path, tác nhân có thể tránh kéo toàn bộ cây trạng thái (có thể rất lớn) và chỉ tập trung vào phần có liên quan, giúp tiết kiệm mã thông báo và cải thiện hiệu suất. - Giao diện chuẩn hoá: Ngay cả khi bạn chuyển đổi thư viện quản lý trạng thái, miễn là bạn cập nhật hàm
executenày, tác nhân gỡ lỗi AI sẽ không cần bất kỳ chỉ dẫn hoặc công cụ mới nào.
Kiểm tra nội dung cơ sở dữ liệu
Xác minh rằng dữ liệu phụ trợ của bạn khớp với trạng thái giao diện người dùng bằng cách truy vấn trực tiếp các bản ghi trong cơ sở dữ liệu thông qua một điểm gỡ lỗi chỉ đọc.
Hiển thị một điểm cuối gỡ lỗi an toàn và tạo một công cụ như thế này để xác minh các bản ghi phụ trợ:
// 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}` };
}
}
}
]
});
});
Nếu nội dung mô tả công cụ của bạn rõ ràng, thì tác nhân có thể tự động sử dụng công cụ khi thấy phù hợp. Bạn có thể nhắc tác nhân thực hiện một việc bằng công cụ này, chẳng hạn như:
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.
Ví dụ về việc thực thi tác nhân: Tác nhân của bạn gọi queryDatabaseTable cho bảng đơn đặt hàng. Thao tác này truy xuất bản ghi JSON, xác định lỗi trong quá trình tính thuế của phụ trợ và đề xuất cách khắc phục cho logic máy chủ.
Một số lưu ý quan trọng liên quan đến ví dụ về công cụ này:
- Bảo mật và xác thực: Bạn không cần truyền thông tin đăng nhập cơ sở dữ liệu cho tác nhân AI. Lệnh gọi
fetchsử dụng phiên đăng nhập hiện tại của trình duyệt để uỷ quyền cho yêu cầu trên phần phụ trợ của bạn. - Gỡ lỗi có thể thực hiện: Nếu xác định được một lỗi giao diện người dùng, thì tác nhân AI có thể gọi ngay
queryDatabaseTableđể xem lỗi đó có tồn tại trong dữ liệu nguồn hay phép tính giao diện người dùng hay không. - Thiết lập tối thiểu: Bạn chỉ cần hiển thị một điểm gỡ lỗi "an toàn" (chỉ đọc) trên máy chủ chấp nhận tên bảng và trả về JSON. Không quan trọng bạn dùng khung nào để tạo điểm cuối đó.