webagents-md.mp4
This is a proposed spec and Python SDK that lets websites expose tools for AI agents to call directly in the browser. A site publishes a Markdown file describing its tools, and any agent can discover and use them.
If adopted broadly, webagents.md is how AI agents navigate the web autonomously--not by clicking through interfaces built for humans, but by calling functions that websites explicitly provide to them.
How it works: A website publishes a webagents.md file listing its tools and adds a <meta> tag for discovery. The SDK detects the tag, parses the manifest, and converts the tools into TypeScript declarations. The LLM gets those declarations as context plus a single execute_js tool.
The agent writes code like await global.searchProducts("red shoes"), and the runtime executes it in the browser via Playwright. Multiple calls can be chained in one shot.
What the SDK provides:
- For builders of AI agents, it detects a site's manifest, parses the tools, generates TypeScript declarations for the LLM, and executes LLM-written code in the browser.
- For website developers, it lets them build and validate manifests programmatically.
Most web agents today behave in one of two ways:
- They view websites and simulate clicks and keystrokes, pretending to be a human. This is not deterministic and can be time-consuming, token-intensive, and prone to failure.
- They rely on backend-only integrations (MCP servers, custom APIs, OpenAPI specs) that are fragmented and require configuration.
At the same time, we've learned a few key things about LLMs:
- LLMs are much better at writing code than at making tool calls. They've seen millions of TypeScript APIs in training, but only a smaller set of contrived tool-calling examples.
- When an LLM can write code, it can chain multiple calls in one shot. It can also branch on results, looping over items, transforming data, handling errors, etc.
webagents.md is a simple answer to this:
- It's framework-agnostic: one Markdown file works with any LLM that can write TypeScript.
- It's code-first: the SDK converts tool declarations into TypeScript interfaces that LLMs write code against.
- It's website-owned: the site itself declares what tools exist and how they should be used.
It's like a robots.txt for AI tools: instead of telling crawlers which URLs to avoid, it tells agents which functions they can call.
There are two audiences:
-
Agent developers
- Detect
webagents.mdon any site. - Parse the tools into TypeScript declarations.
- Pass them to an LLM, which writes code that calls the tools directly in the browser.
- Detect
-
Website developers
- Define tools in a Markdown file (
webagents.md). - Optionally generate and validate that file using this SDK.
- Implement the corresponding JavaScript functions on their site.
- Define tools in a Markdown file (
At a high level:
- A site adds
webagents.mdand a<meta>tag. - An agent runtime detects it.
- The SDK converts the manifest into TypeScript declarations.
- The LLM writes code like
const results = await global.searchProducts("red shoes");. - The runtime executes that code in the browser, where the
global.*functions already exist.
A website publishes a webagents.md file listing tools AI agents can use, and adds a <meta> tag to <head> for discovery:
<meta name="webagents-md" content="/webagents.md">Here's what that file looks like:
# Example Store
Simple online store for shoes and accessories.
## Important
- User must be logged in for cart operations.
- searchProducts is rate-limited to 10 calls/minute.
## searchProducts
Search the product catalog by keyword.
### Params
- `query` (string, required): Search query text.
- `limit` (number, optional, default=20): Maximum results.
### Output
```typescript
{ products: Array<{ id: string; name: string; price: number }>; total: number }
```
### Sample Code
```js
const results = await global.searchProducts(query);
```
## addToCart
Add a product to the shopping cart.
### Params
- `productId` (string, required): Unique product ID.
- `quantity` (number, optional, default=1): Quantity to add.
### Output
```typescript
{ cartId: string; items: Array<{ productId: string; quantity: number }> }
```
### Sample Code
```js
await global.addToCart(productId, quantity);
```That's it.
The SDK converts this into TypeScript declarations the LLM writes code against:
declare const global: {
/** Search the product catalog by keyword. */
searchProducts(query: string, limit?: number): Promise<{
products: Array<{ id: string; name: string; price: number }>;
total: number;
}>;
/** Add a product to the shopping cart. */
addToCart(productId: string, quantity?: number): Promise<{
cartId: string;
items: Array<{ productId: string; quantity: number }>;
}>;
};The LLM then writes code like:
const results = await global.searchProducts("red shoes");
const top = results.products[0];
await global.addToCart(top.id, 2);
console.log(`Added ${top.name} to cart`);Everything in webagents.md is context for the LLM:
- Tool declarations → converted to TypeScript declarations the LLM writes code against.
### Outputblocks → become return types in the TypeScript, so the LLM knows what it gets back.### Sample Codeblocks → documentation showing calling conventions.- Everything else (instructions, rate limits, workflows, resources) → passed as-is to the LLM alongside the TypeScript.
The manifest serves as documentation, prompt, and tool definition all at once.
pip install webagents-mdimport asyncio
from webagent import AgentClient
async def main():
async with AgentClient() as agent:
# Detect webagents.md on a website (via <meta name="webagents-md">)
await agent.detect("https://shop.example.com")
# Get TypeScript declarations — pass this to your LLM
ts = agent.typescript()
# => 'declare const global: { searchProducts(...): Promise<...>; ... };'
# Or get full LLM context (TypeScript + raw markdown instructions)
context = agent.context_for_llm()
asyncio.run(main())AgentClient provides everything needed for a full agent loop — system prompt, tool schema, and browser execution:
import asyncio
from webagent import AgentClient
async def main():
async with AgentClient() as agent:
await agent.detect("https://shop.example.com")
# List available tools
print(agent.list_tools()) # ['searchProducts', 'addToCart', ...]
# Get a complete system prompt (TypeScript API + instructions for the LLM)
prompt = agent.system_prompt(task="Find red shoes and add them to cart")
# Get the generic execute_js tool schema (OpenAI function-calling format)
tool = agent.execute_tool()
# Execute LLM-generated JavaScript in the browser (via a Playwright page)
result = await agent.execute(page, 'return await global.searchProducts("red shoes")')
asyncio.run(main())You can also load a manifest directly from a known URL (skipping <meta> tag detection):
await agent.load("https://shop.example.com/webagents.md")You can build and validate a webagents.md manifest programmatically:
from webagent import Param, build_manifest, build_tool, meta_tag, to_markdown, validate, write_file
# Define tools
search = build_tool(
name="searchProducts",
description="Search the product catalog.",
params=[
("query", "string", "Search query text."),
],
sample_code="const results = await global.searchProducts(query);",
)
# For optional params, use Param directly
snapshot = build_tool(
name="getPageSnapshot",
description="Return a structured snapshot of current page state.",
params=[],
sample_code="const snapshot = await global.getPageSnapshot(mode);",
)
snapshot.params = [
Param(name="mode", type="string", description='Snapshot mode.', required=False, default="full"),
]
# Build a manifest
manifest = build_manifest("My Store", tools=[search, snapshot])
# Validate it (checks names, descriptions, params, duplicates)
warnings = validate(manifest)
if warnings:
print("Warnings:", warnings)
# Serialize to Markdown
md = to_markdown(manifest)
print(md)
# Or write directly to a file
write_file(manifest, "./webagents.md")
# Generate the HTML meta tag for discovery
print(meta_tag()) # <meta name="webagents-md" content="/webagents.md">Note:
build_toolcreates all params as required by default. For optional params with defaults, use theParamclass directly as shown above.
And then:
- Save
mdas/webagents.mdon your site. - Add the
<meta name="webagents-md" content="/webagents.md">tag to<head>. - Implement the corresponding JavaScript functions:
// On the website:
global.searchProducts = async (query, limit = 20) => {
const resp = await fetch(`/api/search?q=${encodeURIComponent(query)}&limit=${limit}`);
if (!resp.ok) throw new Error("Search failed");
return await resp.json();
};The SDK can parse two formats. Both are valid Markdown, and both produce the same internal Tool objects.
This is the format shown throughout this README. Tools are ## headings, with ### Params, ### Output, and ### Sample Code subsections. It's designed to be written by hand and read like documentation. The ### Output section is optional. When present, it becomes the return type in the TypeScript declaration, and when absent the return type defaults to Promise<any>.
Any ## section that isn't a tool (like ## Important with instructions or rate limits) is preserved in manifest.content and included when you call context_for_llm(), so the LLM sees it as context alongside the TypeScript declarations.
An alternative format that's closer to a config file. Instead of headings, each tool starts with tool: followed by its signature, with indented description, params, output, and sample_code fields:
tool: searchProducts(query, limit=20)
description: |
Search products by keyword.
params:
query: string
limit: number?
output:
```typescript
{ products: Array<{ id: string; name: string; price: number }>; total: number }
```
sample_code:
```js
const results = await global.searchProducts(query, limit);
```
tool: addToCart(productId, quantity=1)
description: |
Add a product to the cart.
params:
productId: string
quantity: number?
sample_code:
```js
await global.addToCart(productId, quantity);
```
Default values and optional params are expressed in the signature (limit=20) and type (number?) rather than in prose.
webagents.md does not define authentication; it assumes:
- Tools run in the context of the browser,
- Which means they can use:
- the current user’s logged-in session (cookies/tokens),
- or any existing API keys/headers the site already uses.
A typical pattern:
global.getUserProfile = async () => {
const resp = await fetch("/api/user/me"); // browser sends cookies/headers as usual
if (resp.status === 401) throw new Error("Not logged in");
return await resp.json();
};From the agent’s perspective, calling getUserProfile() is just:
const profile = await global.getUserProfile();If the user isn’t authenticated, the tool fails like it would for any other unauthenticated request. No secrets or tokens need to be embedded in webagents.md.
For cases where the agent isn't riding on an existing user session, websites can expose authentication tools in the manifest itself. For example, a login or getAgentToken tool could issue a scoped token for the agent to use in subsequent calls.
Everything is importable from webagent:
| Function / Class | Description |
|---|---|
AgentClient |
High-level async client: detect, load, get TypeScript, execute JS in browser |
parse(markdown) |
Parse a webagents.md string into a Manifest |
parse_file(path) |
Parse a webagents.md file from disk |
generate_typescript(manifest) |
Generate declare const global: { ... } TypeScript declarations |
discover(url) |
Discover and parse a manifest from a web page |
discover_manifest_url(url) |
Get the manifest URL from a page's <meta> tag |
fetch_manifest(url) |
Fetch and parse a manifest from a direct URL |
build_manifest(name, ...) |
Build a Manifest programmatically |
build_tool(name, ...) |
Build a Tool from simple arguments |
validate(manifest) |
Validate a manifest, returns list of warnings |
to_markdown(manifest) |
Serialize a Manifest back to markdown |
write_file(manifest, path) |
Write a manifest to disk as markdown |
meta_tag(path) |
Generate the HTML <meta> discovery tag |
Manifest, Tool, Param |
Pydantic models |
Internally, webagent is:
src/webagent/
├── __init__.py
├── types.py # Pydantic models: Param, Tool, Manifest
├── parser.py # Parse webagents.md → Manifest
├── discovery.py # Discover webagents.md via <meta name="webagents-md">
├── client.py # AgentClient (agent developer API)
├── codegen.py # Generate TypeScript declarations from tools
├── serializer.py # Manifest → webagents.md Markdown
└── site.py # Website developer helpers (build, validate, meta_tag)
You can use just the building blocks you need:
- Only
parser.py+types.pyif you're writing your own runtime. - Or
client.pyif you want an all-in-one agent-side helper.
The demo/ directory contains a working end-to-end example: a bookstore website ("Books to Browse") that declares tools via webagents.md, and a Python script that runs an AI agent against it.
cd demo
pip install -r requirements.txt
playwright install chromium
python run_agent.pyThe script starts a local server, discovers the site's tools, and runs an AI agent that writes and executes JavaScript in the browser. See demo/README.md for details.
pip install -e ".[dev]"
pytest
ruff check src/ tests/MIT