Google, içerikleri tercih ettiğiniz dile çevirmek için yapay zeka teknolojisini kullanır. Yapay zeka çevirilerinde hata olabilir.

Imperative API

Alexandra Klepper

François Beaufort

Yayınlanma tarihi: 18 Mayıs 2026, Son güncelleme tarihi: 21 Eylül 2026

Açıklayıcı	Web	Uzantılar	Chrome Durumu	Amaç
GitHub	Kaynak denemesi		Görünüm	Deneme Yapma Amacı

Standart JavaScript ile birçok araç türünü tanımlamak için WebMCP Imperative API'yi kullanabilirsiniz. Araçlarınız, form girişi, site gezinme ve durum yönetimi gibi farklı işlevleri yerine getirebilir.

Bu API'yi kullanmadan önce kullanım örnekleri hakkında bilgi edinin.

Model bağlamı sağlama

Araçları kaydetmek için modelContext arayüzünü kullanın. Araç kaydı için ad, açıklama ve alakalı özelliklere sahip giriş şeması gerekir.

Model bağlamına tek bir araç eklemek için registerTool simgesini kullanın.

WebMCPza Maker

await document.modelContext.registerTool({
  name: 'toggle_layer',
  description: 'Control pizza layers (sauce, cheese). Use "add", "remove", or "toggle".',
  inputSchema: {
    type: 'object',
    properties: {
      layer: { type: 'string', enum: ['sauce-layer', 'cheese-layer'] },
      action: { type: 'string', enum: ['add', 'remove', 'toggle'] },
    },
    required: ['layer'],
  },
  execute: async ({ layer, action }) => {
    await toggleLayer(layer, action);
    return `Performed ${action || 'toggle'} on layer: ${layer}`;
  },
});

Sipariş durumunu alma

await document.modelContext.registerTool({
  name: 'get_order_status',
  description: 'Search orders in a given timeframe. Returns order number, shipping status and location',
  inputSchema: {
    "type": "object",
    "properties": {
      "timeframe": { "type": "string", "oneOf": [
        { "type": "string", "const": "today", "title": "Today" },
        { "type": "string", "const": "yesterday", "title": "Yesterday" },
        { "type": "string", "const": "last_7_days", "title": "Last 7 Days" },
        { "type": "string", "const": "last_30_days", "title": "Last 30 Days" },
        { "type": "string", "const": "last_6_months", "title": "Last 6 Months" }],
      "enum": [ "today", "yesterday", "last_7_days", "last_30_days", "last_6_months" ],
      "description": "Timeframe for the order lookup." }
    },
    "required": [ "timeframe" ]
  },
  execute: async ({ timeframe }) => {
    // Add your API or database logic here to fetch and return the order data as a string.
  },
});

Araç ek açıklamaları (isteğe bağlı)

Bir aracı kaydederken annotations özelliğine meta veri ekleyebilirsiniz. Bu ek açıklamalar, aracıların ve tarayıcıların bir aracın güvenlik özelliklerini, beklenen yan etkilerini, çıkış güvenilirliğini ve amaçlanan hedef kitleyi anlamasına yardımcı olur:

readOnlyHint (boolean, varsayılan olarak false): true olduğunda aracın yalnızca bilgi okuduğunu ve uygulamanın veya sistemin durumunu değiştirmediğini (örneğin, ürün kataloğunda arama yapma veya sipariş durumunu alma) gösterir. Bu, aracıların yan etkiler olmadan güvenli bir şekilde çağrılıp çağrılamayacağını belirlemesine yardımcı olur.
untrustedContentHint (boolean, varsayılan olarak false): true olduğunda, aracın çıkışının araç yazarının bakış açısına göre güvenilmeyen veriler içerdiğini (ör. kullanıcı tarafından oluşturulan içerik, yorumlar veya harici web verileri) gösterir. Bu, döndürülen yükün dolaylı istem enjeksiyonu riskini azaltmak için temizleme veya sınırlama gibi daha yüksek güvenlikli bir işlem gerektirdiğini aracıya ve istemciye bildirir.
consequentialHint (boolean, varsayılan olarak false): true olduğunda, aracın yürütülmesinin önemli, gerçek dünyada geçerli veya geri döndürülemez işlemlerle (ör. uçak bileti rezervasyonu yapma, para transferi veya veri silme) sonuçlandığını gösterir. Bu sayede, yüksek riskli araçlar yürütülmeden önce aracıların ve tarayıcıların zorunlu kullanıcı onayı istemlerini uygulamasına olanak tanınır. Böylece, kullanıcı niyetinin yanlışlıkla veya kötü niyetli olarak yanlış temsil edilmesi riski azaltılır.
debugging (boolean, varsayılan değer false, Chrome 156'dan itibaren kullanılabilir): true olduğunda, aracın son kullanıcı etkileşimlerinden ziyade özellikle inceleme ve geliştirici araçları (ör. test çerçeveleri veya Chrome Geliştirici Araçları AI yardımcısı) için tasarlandığını gösterir. Bu sayede genel amaçlı ve son kullanıcı aracılarının, geliştiricilere yönelik araçları filtrelemesine olanak tanınır.

await document.modelContext.registerTool({
  name: 'book_flight',
  description: 'Book a flight for the user with confirmed flight details.',
  inputSchema: {
    type: 'object',
    properties: {
      flightId: { type: 'string', description: 'ID of the flight to book' },
      passengers: { type: 'number', description: 'Number of tickets to purchase' },
    },
    required: ['flightId', 'passengers'],
  },
  annotations: {
    readOnlyHint: false,
    consequentialHint: true,
    untrustedContentHint: false,
    debugging: false,
  },
  execute: async ({ flightId, passengers }) => {
    // Add your flight booking transaction logic here.
    return `Booked ${passengers} passenger(s) on flight ${flightId}.`;
  },
});

Araçların kaydını silme

İsteğe bağlı bir parametre olarak iletildiğinde AbortSignal ile bir aracı kaldırabilirsiniz.

const addTodoTool = {
  name: "addTodo",
  description: "Add a new item to the to-do list",
  inputSchema: {
    type: "object",
    properties: { text: { type: "string" } },
  },
  execute: async ({ text }) => {
    // You should handle the persistence logic here (omitted for demo)
    return `Added to-do: ${text}`;
  },
  annotations: {
    readOnlyHint: false,
    untrustedContentHint: true
  },
};
const controller = new AbortController();
await document.modelContext.registerTool(addTodoTool, { signal: controller.signal });

// Unregister the tool later...
controller.abort();

Chrome 153'ten itibaren, devam eden yürütmeleri iptal etmeden ve kesintiye uğratmadan bir aracın kaydını silebilirsiniz. Bu, bileşen çerçevelerinde araç yaşam döngüleri yönetilirken beklenmedik yan etkilerin oluşmasını önler.

Araç iptalini işleme

execute işlevi, kullanıcı veya aracı tarafından başlatılan yürütme iptallerini düzgün bir şekilde işlemek için ikinci bağımsız değişken olarak signal adlı bir AbortSignal parametresi alır. Bu sinyali uzun süren asenkron görevlere veya ağ işlemlerine (ör. fetch()) iletmek gereksiz işleri önlemeye, genel kaynak yönetimini iyileştirmeye ve olası sızıntıları engellemeye yardımcı olur.

await document.modelContext.registerTool({
  name: 'fetch_tool',
  description: 'Fetch the text content of a URL and stream the response.',
  inputSchema: {
    type: 'object',
    properties: {
      url: { type: 'string', description: 'The URL to fetch' },
      priority: { type: 'string', enum: ['high', 'low', 'auto'] },
    },
    required: ['url'],
  },
  execute: async ({ url, priority }, { signal }) => {
    // Abort the fetch request when tool execution is aborted.
    const response = await fetch(url, { priority, signal });
    const stream = response.body.pipeThrough(new TextDecoderStream());
    for await (const chunk of stream) {
      document.querySelector('pre').textContent += chunk;
    }
    return 'Success';
  },
});

Araçları keşfetme

Kullanılabilir araçları almak için document.modelContext.getTools() kullanın. Bu eşzamansız yöntem, çağıran dokümanın erişmesine izin verilen araçların alfabetik olarak sıralanmış bir listesini döndürür.

const [tool] = await document.modelContext.getTools();
console.log(tool);

// {
//   annotations: { consequentialHint: false, debugging: false, readOnlyHint: false, untrustedContentHint: true }, // Optional hints
//   description: "Add a new item to the to-do list",
//   inputSchema: {"type":"object","properties":{…}},
//   name: "addTodo",
//   origin: "https://example.com",
//   title: ""
//   window: Window {window: Window, self: Window, …},
// }

Varsayılan olarak getTools() yalnızca çağıran belge veya çerçeve ağacındaki diğer aynı kaynaklı belgeler tarafından kaydedilen aynı kaynaklı araçları döndürür. Kaynaklar arası araçları almak için kaynaklarını fromOrigins seçeneğinde açıkça listelemeniz gerekir. Bu dizi yalnızca güvenli kaynakları destekler.

Kaynaklar arası dokümanlardaki araçlar yalnızca şu durumlarda dahil edilir:

Barındırma kaynağı, fromOrigins seçeneğinde listelenir.
Araç, kaynağınıza açıkça maruz kalmıştır.

// https://example.com

// Get same-origin tools only
const sameOriginTools = await document.modelContext.getTools();

// Get same-origin tools plus tools from specific cross-origin documents
const allTools = await document.modelContext.getTools({
  fromOrigins: ['https://partner.org']
});

Bir iFrame'den araçların nasıl alınacağı ve web tabanlı bir sohbet arayüzünde nasıl yürütüleceğine dair örnek için WebMCP Page Agent demosuna bakın.

Aracı yürütme

getTools() içinde keşfedilen bir aracı manuel olarak yürütmek için, giriş bağımsız değişkenleri için JSON dizesine dönüştürülebilen isteğe bağlı bir JavaScript nesnesiyle document.modelContext.executeTool() işlevini çağırın. Bu eşzamansız yöntem, araç yürütme sonucunu veya gezinme tetiklendiğinde null değerini döndürür.

const result = await document.modelContext.executeTool(tool, { text: "Buy milk" });
console.log(result);

// 'Added to-do: Buy milk'

İsteğe bağlı bir parametre olarak iletildiğinde AbortSignal ile bekleyen bir araç yürütmesini iptal edebilirsiniz.

const controller = new AbortController();
document.modelContext.executeTool(tool, { text: "Buy milk" }, { signal: controller.signal });

// Cancel tool execution later...
controller.abort();

Etkinlikler

Kullanılabilir araçların listesi değiştiğinde bildirim almak için çerçeveler, document.modelContext üzerinde toolchange etkinliğini dinleyebilir.

document.modelContext.addEventListener("toolchange", (event) => {
  // Tools have changed.
});

Çapraz kaynak iframe'ler

WebMCP, hem izin politikalarını hem de açık kaynak sınırlamayı kullanan çapraz kaynak iframe'leri destekler.

İzin politikası

Araç kaydı, kaynaklar arası iFrame'lerde varsayılan olarak devre dışıdır. Bir sayfa, tools izin politikası kullanarak erişimi temsilciye devretmelidir:

<iframe src="https://example.com" allow="tools"></iframe>

İlk çıkış görünürlüğü

Araçlar, varsayılan olarak kaynaklar arası dokümanlarda kullanılamaz. Bir aracı görüntülemesine ve yürütmesine izin verilen belirli kaynakları listelemek için registerTool içinde exposedTo dizisini kullanabilirsiniz. Bu dizi yalnızca güvenli kaynakları destekler.

// https://partner.org

await document.modelContext.registerTool({
  name: 'my_shared_tool',
  description: 'Shared across origins',
  // ...
}, {
  exposedTo: ['https://example.com']
});

Tepki desteği

React, usewebmcp paketi kullanılarak WebMCP için deneysel destek sunar. Uygulamanız React ile yazılmışsa araçları, bileşeninizin bağlama ve kaldırma yaşam döngüsüne bağlı bağımsız kancalar kullanarak kaydedebilirsiniz. useWebMCP kancası, şemaya dayalı tür çıkarımı da sağlar ve yerel yürütme durumunu kullanıma sunar.

Angular desteği

Angular, WebMCP için deneysel destek sunar. Uygulamanız Angular ile yazılmışsa uygulamanın bağımlılık ekleme yaşam döngüsüne bağlı araçları kaydedebilir ve Signal Forms'unuzu WebMCP araçlarına dönüştürebilirsiniz.

Etkileşim kurma ve geri bildirim paylaşma

WebMCP aktif olarak tartışılmaktadır ve gelecekte değişebilir. Bu API'yi denerseniz geri bildiriminizi bizimle paylaşmanızı rica ederiz.

WebMCP açıklayıcısını okuyun, soru sorun ve tartışmaya katılın.
WebMCP ile ilgili en iyi uygulamaları okuyun.
Chrome'daki uygulamayı Chrome Status'ta inceleyin.
Yeni API'leri önceden görmek ve posta listemize erişmek için erken önizleme programına katılın.
Chrome'un uygulamasıyla ilgili geri bildiriminiz varsa Chromium hatası bildirin.

Başlama

Bildirim Temelli API