aiTools

Adds tools that an AI can call, with params and an output shape.

Details #

An AI tool is a function your extension offers to an AI: a calculation, a lookup, a small action. The AI reads the tool's title, description and params, decides when to call it, and gets your JSON back. Use it for things a model is bad at, like exact date maths, or for data only your extension can reach.

Declare it in switchboard.json under adds.aiTools. Every entry has an id (lowercase, digits and . _ -, up to 64 characters, starting with a letter), a title (1 to 80 characters) and an optional description. Ids must be unique within the list.

{
  "adds": {
    "aiTools": [
      { "id": "lookup-ticket", "title": "Look up a ticket", "params": { "type": "object", "properties": { "key": { "type": "string" } }, "required": ["key"] }, "output": { "type": "object" } }
    ]
  }
}

Gotchas #

A call that takes more than 30 seconds without answering fails.
The manifest checks the entry's shape; the handler does the work. Without a matching handler the extension doesn't load.
Anything the tool does outside the sandbox (network, files, clipboard) needs a permission in the manifest. Without it the call fails with permission denied.
Unknown keys in an entry are refused.

The sample below can be downloaded from the Full example section and edited into your own.

Where it shows up #

The engine lists the tools at GET /extensions/ai-tools and runs one with POST /extensions/<extension id>/ai-tool/<tool id>. The body is the arguments, either as the whole JSON object or inside {"arguments": {...}}. The listing gives each tool a name made from the extension's short name and the tool id, for example sample_ai_tools_slugify.

The handler #

The handler gets the arguments the caller chose, shaped by params, and the usual ctx. It returns any JSON value. To refuse bad arguments, throw an Error with a message that says what to fix; the caller sees the message and can try again.