Üçüncü taraf geliştirici araçları, kodlama aracıların DOM, ağ istekleri ve konsol günlüklerinin ötesini görmesini sağlar. Web sitenizden veya çerçevelerinizden özel araçları doğrudan kullanıma sunarak temsilcinizin, normalde erişilemeyen uygulama durumu ve verileriyle etkileşim kurmasına izin verirsiniz.
Bu araçlar JavaScript ile oluşturulur ve sayfanız yüklendiğinde Chrome Geliştirici Araçları tarafından otomatik olarak keşfedilir.
Üçüncü taraf geliştirici araçları hakkında bilgi
Kodlama aracı bağlamında araçlar, ajanların belirli işlemleri gerçekleştirmesi için hazır işlevlerdir. Özellikle aracılar için DevTools'da bu tür araçlar, dahili çalışma zamanı durumunu doğrudan kodlama aracılarına gösterebilir ve oluşturulan çıkış ile dahili mantık arasındaki boşluğu kapatabilir.
Üçüncü taraf araçlarını kullanırken aşağıdakileri göz önünde bulundurun:
- Çalışma zamanı keşfi. Uygulamanız, global
windownesnesindeki aracılar için Chrome Geliştirici Araçları tarafından yayınlanandevtoolstooldiscoveryetkinliğine yanıt verdiğinde araçlar otomatik olarak algılanır. - Bağlam kapsamı. Araçlar yalnızca kendilerini tanımlayan sayfanın bağlamında çalışır. Kaynaklar ve sayfa yeniden yüklemeleri arasında kalıcı olmazlar.
- Aracın özgünlüğü. Araçlar, temsilcinizin görevleri yerine getirmesi için yalnızca ek bir yöntemdir. Bir istemi yerine getirmek için yerleşik araçları veya temel model özelliklerini tercih edebilir. Bu nedenle, araç adlarını ve açıklamalarını mümkün olduğunca açıklayıcı hale getirin.
Ön koşullar
Üçüncü taraf araçlarını uygulamadan önce aşağıdaki koşulları karşıladığınızdan emin olun:
- Temsilciler için Chrome Geliştirici Araçları 0.25.0 veya sonraki bir sürümü kullanın.
- JavaScript'i etkinleştirin. JavaScript'in etkin ve çalışır durumda olması gerekir.
Bir aracı uygulama
Bir aracı uygulamak için belirli bir keşif etkinliğini dinler ve araç tanımlarınızla yanıt verirsiniz. Aşağıdaki kod, araç tanımlarını içeren bir yanıtı gösterir:
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;
},
},
],
});
},
);
Uygulamanıza araç kaydetmek için:
Araç grubunuzu tanımlayın. Ad, açıklama ve tek tek araç tanımlarından oluşan bir dizi içeren bir
ToolGroupoluşturun.export interface ToolDefinition { name: string; description: string; inputSchema: JSONSchema7; execute: (args: Record<string, unknown>) => unknown; } export interface ToolGroup { name: string; description: string; tools: ToolDefinition[]; }Keşif etkinliğini dinleyin. Aracıların kullandığı Chrome Geliştirici Araçları, her gezinmeden sonra ve kullanılabilir araçların güncellenmiş bir listesine ihtiyaç duyduğunda genel
windownesnesinde özel birdevtoolstooldiscoveryetkinliği gönderir.Araçlarınızı kaydedin. Aracınıza araç grubunuzu sağlamak için etkinliğin
respondWith()yöntemini çağırın.
Tek tek araçlar için temel bileşenler
Uyguladığınız her araç tanımı aşağıdaki üç bölümü içermelidir:
- Ad ve açıklama. Bunlar, aracınızın ne zaman ve nasıl çağrılacağına karar vermek için aracının kullandığı talimatları sağlar.
- Giriş şeması. Aracın beklediği bağımsız değişkenlerin yapısını ve türlerini tanımlayan bir JSON şeması.
- Yürütme işlevi. Ajan, aracı çağırdığında sayfada çalışan gerçek JavaScript kodu.
Aşağıdaki örnekte, bu üç bileşen tek bir araç tanımında gösterilmektedir:
{
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;
},
}
Üçüncü taraf geliştirici araçlarının kullanım alanları
Aracınıza, yalnızca yüzey düzeyindeki kullanıcı arayüzü öğeleri yerine derin uygulama mantığını incelemesini söyleyin. Durumlu veya çerçeve ağırlıklı uygulamalarda hata ayıklamayı kolaylaştırmak için bu özel araçları kullanın.
Araç keşfiyle ilgili ipuçları
Açıklayıcı araç adları ve açıklamaları yazın. Temsilciler, hangi aracı kullanacaklarına karar vermek için bu açıklamalardan bağlam olarak yararlanır. Açık bir dil, temsilcinin bir aracın bir görev için uygun olup olmadığını bağımsız olarak belirlemesine yardımcı olur.
Uygulamaya özel çalışma zamanı metriklerinde hata ayıklama
Sessiz önbellek kaçırmaları veya gereksiz API çağrıları gibi sorunlar genellikle standart incelemeyle tespit edilemez. Ajanınız, dahili istatistikleri göstererek belirli bir davranışın neden gerçekleştiğini açıklayabilir.
Dahili istatistikleri gösteren bir işleviniz olduğunu varsayalım. Öncelikle, aşağıdakine benzer bir araç oluşturmanız gerekir:
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();
}
}
]
});
});
Aracınızın açıklaması netse aracınız, uygun gördüğü durumlarda aracı otonom olarak kullanabilir. Aracı kullanarak temsilcinizden aşağıdaki gibi bir görevi yerine getirmesini isteyebilirsiniz:
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.
Örnek temsilci yürütme: Temsilciniz, uygulamanız tarafından kullanıma sunulan getCacheStatistics aracını algılıyor. Bu araç çağrılır, döndürülen isabet/kaçırma oranı analiz edilir ve ön ucun yerel önbelleği güncellemek yerine tüm işlem hattını gereksiz yere yeniden getirdiği belirlenir.
Özellik işaretlerini kontrol etme
Mevcut ortam değişkenlerini veya belirli bir kullanıcı oturumu için etkin olan özellik işaretlerini göstermek üzere özel veri noktaları tanımlayın. Bu sayede, belirli özelliklerin neden belirli kullanıcılara gösterilmediğini veya gösterildiğini belirleyebilirsiniz. Bir kullanıcı hata bildirirse temsilci, kullanıcının soruna neden olabilecek bir deneme grubunda olup olmadığını doğrulayabilir.
Örneğin, dahili özellik bayrağı durumunu döndürmek için aşağıdaki gibi bir araç oluşturun:
// 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'
};
}
}
]
});
});
Aracınızın açıklaması netse aracınız, uygun gördüğü durumlarda aracı otonom olarak kullanabilir. Aracı kullanarak temsilcinizden aşağıdaki gibi bir görevi yerine getirmesini isteyebilirsiniz:
Check the active feature flags and tell me if the new-ui-enabled flag is set to
true for this session.
Örnek ajan yürütme: Ajanınız getFeatureFlags aracını çağırır, new-ui-enabled işaretinin etkin olduğunu onaylar ve yeni arayüzle ilişkili bileşenlerde hata ayıklamaya devam eder.
Genel uygulama durumunu inceleme
Uygulamanızın çalışma zamanı durum ağacını göstererek temsilcinizin, DOM'un tamamını getirmeden dahili mantığı anlamasına yardımcı olun.
Durum ağacınızdaki belirli yolları sorgulamak için aşağıdaki gibi bir araç oluşturabilirsiniz:
// 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);
}
}
]
});
});
Aracınızın açıklaması netse aracınız, uygun gördüğü durumlarda aracı otonom olarak kullanabilir. Aracı kullanarak temsilcinizden aşağıdaki gibi bir görevi yerine getirmesini isteyebilirsiniz:
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.
Örnek aracı yürütme: Aracınız, path parametresiyle getGlobalState işlevini çağırıyor. Alışveriş sepetindeki öğelerin listesini alır ve dahili durum ile sayfada oluşturulan öğeler arasındaki tutarsızlığı tanımlar.
Bu araç örneğiyle ilgili bazı önemli notlar:
- Ayrılmış mantık: Yapay zeka aracısı "durum" istiyor. Geliştirici olarak siz, bu isteği
executeişlevindeki gerçek veri yapınızla nasıl eşleyeceğinize karar verirsiniz. - Hedeflenen Hata Ayıklama:
pathparametresini ekleyerek aracı, tüm durum ağacını (çok büyük olabilir) çekmekten kaçınabilir ve yalnızca ilgili bölüme odaklanabilir. Böylece jeton tasarrufu sağlanır ve performans artırılır. - Standartlaştırılmış arayüz: Durum yönetimi kitaplıklarını değiştirseniz bile
executeişlevini güncellediğiniz sürece yapay zeka hata ayıklama aracınızın yeni talimatlara veya araçlara ihtiyacı olmaz.
Veritabanı içeriğini inceleme
Salt okunur bir hata ayıklama uç noktası aracılığıyla doğrudan veritabanı kayıtlarını sorgulayarak arka uç verilerinizin kullanıcı arayüzü durumuyla eşleştiğini doğrulayın.
Güvenli bir hata ayıklama uç noktası kullanıma sunun ve arka uç kayıtlarını doğrulamak için aşağıdaki gibi bir araç oluşturun:
// 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}` };
}
}
}
]
});
});
Aracınızın açıklaması netse aracınız, uygun gördüğü durumlarda aracı otonom olarak kullanabilir. Aracı kullanarak temsilcinizden aşağıdaki gibi bir görevi yerine getirmesini isteyebilirsiniz:
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.
Örnek aracı yürütme: Aracınız, siparişler tablosu için queryDatabaseTable işlevini çağırıyor. JSON kaydını alır, arka uçtaki vergi hesaplamasında bir hata olduğunu belirler ve sunucu mantığı için bir düzeltme önerir.
Bu araç örneğiyle ilgili bazı önemli notlar:
- Güvenlik ve kimlik doğrulama: Veritabanı kimlik bilgilerini yapay zeka aracısına iletmeniz gerekmez.
fetchçağrısı, arka uçtaki isteği yetkilendirmek için tarayıcının mevcut oturumunu kullanır. - İşleme hazır hata ayıklama: Bir yapay zeka aracısı kullanıcı arayüzünde bir hata tespit ederse hatanın kaynak verilerde mi yoksa ön uç hesaplamasında mı olduğunu görmek için hemen
queryDatabaseTableişlevini çağırabilir. - Minimum kurulum: Sunucunuzda yalnızca bir tablo adını kabul eden ve JSON döndüren "güvenli" (salt okunur) hata ayıklama uç noktası kullanıma sunmanız gerekir. Bu uç noktayı oluşturmak için kullandığınız çerçeve önemli değildir.