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

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

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 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 araç 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 sayede temsilciler, aracın yan etkiler olmadan güvenli bir şekilde çağrılıp çağrılamayacağını belirleyebilir.
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ı, geliştirici odaklı araçları filtreleyebilir.

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 kesintiye uğratmadan bir aracın kaydını iptal edebilirsiniz. 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 temsilci tarafından başlatılan yürütme iptallerini düzgün bir şekilde işlemek için ikinci bağımsız değişkeni 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şlemleri önlemeye yardımcı olur, genel kaynak yönetimini iyileştirir ve olası sızıntıları önler.

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 doküman veya çerçeve ağacındaki diğer aynı kaynaklı dokümanlar 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']
});

Araçları bir iFrame'den alma ve 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 bulunan bir aracı manuel olarak çalıştırmak için document.modelContext.executeTool() işlevini, JSON dizesine dönüştürülebilen giriş bağımsız değişkenleri için isteğe bağlı bir JavaScript nesnesiyle çağırın. Bu asenkron yöntem, aracın yürütülmesinin sonucunu veya bir 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ı, çapraz kaynaklı iFrame'lerde varsayılan olarak devre dışıdır. Sayfalar, tools İzin Politikası'nı kullanarak erişim yetkisi vermelidir:

<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, use-webmcp-tool paketini kullanarak WebMCP için deneysel destek sunar. Uygulamanız React ile yazılmışsa bileşeninizin bağlama ve bağlantıyı kesme yaşam döngüsüne bağlı useWebMCP kancasını kullanarak araçları kaydedebilirsiniz. Ayrıca koşullu araç kaydını destekler ve yürütme sonuçlarını otomatik olarak normalleştirir.

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 Signal Forms'u 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 mevcut Vue kapsam yaşam döngüsüne bağlı useWebMCP composable'ını kullanarak araçları 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 erkenden incelemek ve posta listemize erişmek için erken erişim programına katılın.
Chrome'un uygulamasıyla ilgili geri bildiriminiz varsa Chromium hata kaydı oluşturun.

Başlama

Bildirim Temelli API