Skip to content

Commit f303c45

Browse files
authored
Spec the executeTool() API (#226)
1 parent 7aa8235 commit f303c45

2 files changed

Lines changed: 494 additions & 16 deletions

File tree

‎README.md‎

Lines changed: 70 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -326,7 +326,7 @@ By default, WebMCP is enabled in top-level `Window`s and its same-origin iframes
326326

327327
Calls to `document.modelContext.registerTool()` will return a promise rejected with `NotAllowedError` DOMException when the permission is disabled, whether by the `allow` attribute or the `Permissions-Policy: tools=()` header. Handling of declarative tool registration errors, including when the permission is disabled is TBD; see [Issue #182](https://github.com/webmachinelearning/webmcp/issues/182).
328328

329-
#### Cross-origin iframe exposure: `exposedTo`
329+
#### Cross-origin iframe exposure: `registerTool() and `exposedTo`
330330

331331
By default, tools registered by a document are only exposed to itself, same-origin documents in the same tree, and built-in browser agents (see this <a href=#built-in-agent-default-exposure>discussion</a>). To support author-provided agents running in frames, developers can selectively share tools with secure origins of their choice, `exposedTo` option during registration:
332332

@@ -343,9 +343,76 @@ Any document in the tree matching these origins (and allowed to use `tools` perm
343343
- Receive the `toolchange` event on its `document.modelContext` when the tool is registered or unregistered.
344344
- Be able to discover and run the tools
345345

346-
#### Discovering and running tools
346+
#### Discovering and running tools: `getTools()` and `executeTool()`
347347

348-
TODO: Spec and describe the `modelContext.getTools()` and `modelContext.executeTool()` APIs.
348+
Once tools are registered, in-page agents can discover and invoke them using `getTools()` and `executeTool()`.
349+
350+
Calling `document.modelContext.getTools()` returns a promise that resolves with an array of `RegisteredTool` dictionary objects. Each object contains the tool's `name`, `description`, `inputSchema`, `origin`, and owner `window`:
351+
352+
```js
353+
// Discover tools exposed by same-origin frames in the tree (default)
354+
const tools = await document.modelContext.getTools();
355+
356+
for (const tool of tools) {
357+
console.log(`Tool: ${tool.name} (from ${tool.origin})`);
358+
console.log(`Description: ${tool.description}`);
359+
console.log(`Parameters schema:`, tool.inputSchema);
360+
}
361+
362+
// Or discover tools exposed by specific cross-origin partner frames:
363+
const crossOriginTools = await document.modelContext.getTools({
364+
fromOrigins: ["https://trusted-partner.example"]
365+
});
366+
```
367+
368+
An agent executes a discovered `RegisteredTool` by passing the tool dictionary and input arguments along to `document.modelContext.executeTool()`. The browser securely mediates the execution, ensuring the [`exposedTo`](https://webmachinelearning.github.io/webmcp/#dom-modelcontextregistertooloptions-exposedto) and [`fromOrigins`](https://webmachinelearning.github.io/webmcp/#dom-modelcontextgettooloptions-fromorigins) agree, and the tool runs in the tool owner's execution context:
369+
370+
```js
371+
const tools = await document.modelContext.getTools();
372+
const addTodoTool = tools.find(t => t.name === "add-todo");
373+
374+
if (addTodoTool) {
375+
try {
376+
const result = await document.modelContext.executeTool(
377+
addTodoTool,
378+
{ text: "Buy groceries" }
379+
);
380+
console.log("Tool result:", result);
381+
} catch (error) {
382+
console.error("Tool execution failed:", error);
383+
}
384+
}
385+
```
386+
387+
##### Cancelling execution with `AbortSignal`
388+
389+
Tool invocations can be cancelled mid-execution (e.g., if the user aborts an ongoing request, as they might with the "stop button" that's present in most agent UIs) by passing an `AbortSignal`:
390+
391+
```js
392+
const controller = new AbortController();
393+
394+
const executionPromise = document.modelContext.executeTool(
395+
addTodoTool,
396+
{ text: "Buy groceries" },
397+
{ signal: controller.signal }
398+
);
399+
400+
// If the user cancels the interaction:
401+
stopButton.addEventListener('click', e => controller.abort());
402+
```
403+
404+
The tool's [execution callback](https://webmachinelearning.github.io/webmcp/#callbackdef-toolexecutecallback) receives this signal via its [`options.signal`](https://webmachinelearning.github.io/webmcp/#dom-modelcontextexecutetooloptions-signal) parameter, allowing it to abort underlying network requests or asynchronous tasks cleanly.
405+
406+
##### Responding to dynamic tool updates: the `toolchange` event
407+
408+
When tools are added, removed, or updated dynamically (such as when user interactions result in new tools being registered), `document.modelContext` fires a `toolchange` event:
409+
410+
```js
411+
document.modelContext.addEventListener("toolchange", async () => {
412+
const currentTools = await document.modelContext.getTools();
413+
updateAgentToolRegistry(currentTools);
414+
});
415+
```
349416

350417

351418
## Alternatives Considered

0 commit comments

Comments
 (0)