Sutram documentation

Sutram lets a web app expose what it can do as commands. You register a command once: a name, a JSON Schema for its input, and a function. Agents can then call it as a WebMCP tool, from JavaScript in a headless browser, or by typing into the page's console, and people can use the same console. WebMCP is how a page hands tools to an agent; Sutram decides what those tools are, so every part of the app exposes its commands the same way. See Why not just WebMCP?.

Sutram.register({
  name: "cart add",
  provider: "cart",
  description: "Add a product to the cart",
  input: {
    type: "object",
    properties: { sku: { type: "string" }, qty: { type: "integer", default: 1 } },
    required: ["sku"],
  },
  annotations: {},
  run: ({ sku, qty }) => cart.add(sku, qty),
});

That is all most apps need to write. Help pages, the console, the WebMCP tools and input checking come from the definition.

Your path #

1. Quick start: one command, in an HTML file, in five minutes.
2. Install: a script tag or npm. On Drupal, use the module.
3. Write a provider: a real set of commands for one part of your app, with a checklist at the end.
4. Write descriptions agents can use and errors that help agents: the two things that make the biggest difference to how well agents do.

When you want the details of a definition, read Commands and providers. To decide which commands ask the person first, read Annotations and the policy.

How agents reach your commands #

You don't set these up one by one; loading Sutram does. Read these to see what agents get.

• WebMCP: tools in browsers that support it.
• The console: for people, and for agents that type.
• Hand a task to a browser agent: agentPrompt().
• Discovery: help, man, status.
• Test with Playwright: call your commands the way a headless browser does.

Going further #

Only when you need it:

Reference #

• API, generated from the TypeScript declarations
• The command line: grammar, options, exit codes, reserved words

About #

• Why commands: why small commands beat reading the page, with measurements.
• Design notes, for contributors.
• For agents: llms.txt, and the skills in the package's skills/ folder.

This page as MarkdownEdit on GitHub