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: 15 Ekim 2026

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

WebMCP Imperative API'yi kullanarak standart JavaScript ile birçok araç türü tanımlayabilirsiniz. Araçlarınız form girişi, sitede gezinme ve durum yönetimi gibi farklı işlevleri yürütebilir.

Bu API'yi kullanmadan önce örnek kullanım alanları 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 ilgili ö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 öğrenme

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, temsilcilerin ve tarayıcıların bir aracın güvenlik özelliklerini, beklenen yan etkilerini, çıkış güvenilirliğini ve hedef kitlesini anlamasına yardımcı olur:

readOnlyHint (Boole, varsayılan olarak false): true olduğunda, aracın yalnızca bilgileri okuduğunu ve uygulamanın veya sistemin durumunu değiştirmediğini (ör. ü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 (Boole, varsayılan olarak false): true olduğunda, aracın çıkışının, araç yazarının bakış açısından güvenilir olmayan veriler (ör. kullanıcı tarafından oluşturulan içerik, yorumlar veya harici web verileri) içerdiğini gösterir. Bu, temsilciye ve istemciye, döndürülen yükün dolaylı istem enjeksiyonunu azaltmak için temizleme veya sınırlandırma gibi daha yüksek güvenlik önlemleri gerektirdiğini bildirir.
consequentialHint (Boole, varsayılan olarak false): true olduğunda, aracın yürütülmesinin önemli, gerçek dünyada veya geri alınamaz eylemlerle (ör. uçuş rezervasyonu yapma, para transferi yapma veya veri silme) sonuçlandığını gösterir. Bu sayede temsilciler ve tarayıcılar, yüksek riskli araçları çalıştırmadan önce zorunlu kullanıcı onayı istemlerini uygulayarak kullanıcı niyetinin yanlışlıkla veya kötü niyetle yanlış beyan edilmesi riskini azaltabilir.
debugging (Boole, varsayılan olarak false, Chrome 156'dan itibaren kullanılabilir): true olduğunda, aracın son kullanıcı etkileşimleri yerine özellikle inceleme ve geliştirici araçları (ör. test çerçeveleri veya Chrome Geliştirici Araçları Yapay Zeka Desteği) 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}.`;
  },
});

Ek açıklamaların temsilci davranışını nasıl etkileyebileceğine dair örnekler için Örnek WebMCP uzantısı bölümüne bakın.

Araçların kaydını iptal etme

İ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 bozmadan bir aracın kaydını silebilirsiniz. Bu sayede, bileşen çerçevelerinde araç yaşam döngülerini yönetirken beklenmedik yan etkiler önlenir.

Araç iptalini işleme

execute işlevi, kullanıcı veya aracı tarafından başlatılan yürütme iptallerini sorunsuz 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 eşzamansız 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şfedin

Kullanılabilir araçları almak için document.modelContext.getTools() kullanın. Bu eşzamansız yöntem, çağıran dokümanın erişim yetkisine sahip olduğu araçların alfabetik 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. Çapraz kaynak araçlarını almak için kaynaklarını fromOrigins seçeneğinde açıkça listelemeniz gerekir. Bu dizi yalnızca güvenli kaynakları destekler.

Çapraz kaynak dokümanlarındaki araçlar yalnızca şu durumlarda dahil edilir:

Barındırma kaynağı, fromOrigins seçeneğinde listelenir.
Araç, açıkça kaynağınıza gösterilmiştir.

// 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ı alıp web tabanlı bir sohbet arayüzünde yürütme örneği için WebMCP Page Agent demosuna bakın. Bir tarayıcı uzantısındaki temsilcinin, aynı kaynaklı ve çapraz kaynaklı iframe'lerde araçları nasıl bulup çalıştırdığını görmek için Örnek WebMCP uzantısı'na bakın.

Aracı yürüt

getTools() içinde keşfedilen bir aracı manuel olarak yürütmek için document.modelContext.executeTool() işlevini, giriş bağımsız değişkenleri için JSON dizesine dönüştürülebilen isteğe bağlı bir JavaScript nesnesiyle birlikte ç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'

Beklemedeki bir araç yürütme işlemini, isteğe bağlı parametre olarak iletilen AbortSignal ile 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 geçitlerini 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>

Kaynak risk

Araçlar, varsayılan olarak çapraz kaynak dokümanlarda kullanılamaz. registerTool içindeki exposedTo dizisini kullanarak bir aracı görüntülemesine ve yürütmesine izin verilen belirli kaynakları listeleyebilirsiniz. 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']
});

React desteği

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

Angular desteği

Angular, WebMCP için deneysel desteğe sahiptir. Uygulamanız zaten Angular ile yazılmışsa uygulamanın bağımlılık ekleme yaşam döngüsüne bağlı araçları kaydedebilir ve sinyal formlarınızı WebMCP araçlarına dönüştürebilirsiniz.

Vue desteği

Vue, @vueuse/core paketini kullanarak WebMCP için deneysel destek sunar. Uygulamanız zaten Vue ile yazılmışsa araçları, mevcut Vue kapsamı yaşam döngüsüne bağlı useWebMCP composable'ı kullanarak kaydedebilirsiniz. Ayrıca, reaktif ve koşullu araç kaydını destekler ve yürütme sonuçlarını otomatik olarak normalleştirir.

Etkileşim kurma ve geri bildirim paylaşma

WebMCP aktif olarak tartışılmaktadır ve gelecekte değişebilir. Bu API'yi denerseniz ve geri bildiriminiz olursa bizimle paylaşabilirsiniz.

WebMCP açıklayıcısını okuyun, soru sorun ve tartışmaya katılın.
Etkili WebMCP araçları oluşturma ve WebMCP ile ilgili en iyi uygulamalar hakkında bilgi edinin.
Chrome Durumu'nda Chrome için uygulamayı 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 hata kaydı oluşturun.

Başlama

Bildirim Temelli API