API Tools

Give an agent an HTTP API by uploading its OpenAPI or Swagger file. You write no tool code: the agent finds the endpoint it needs and calls it, and you decide which endpoints it may use.

Add an API

Upload an OpenAPI 3.0 / 3.1 or Swagger 2.0 file (YAML or JSON, up to 5 MB) on Studio's Tools page, APIs tab. Give it a name, and pick the vault record that holds its base URL (when the file has none, or to call another server) and its sign-in rows. The record itself is made on the Infrastructure page — an Add custom record with service type 'API tools'.

Then name the API on any LLM agent:

agents:
  orders_agent:
    agent_type: llm
    model: gemini-2.5-flash
    api_tools: [shop]          # the name you gave it on the Tools page

One upload serves every agent that names it.

You decide what is called

Every endpoint has an on/off switch.

Reads start on, writes start off. Turn on only what the agent should do.
An endpoint that is off is never offered to the agent and is refused if called.
When a request needs an endpoint that is off, the agent tells the person it isn't available and that it can be switched on in Tools. It does not quietly use a different endpoint instead.
Switches take effect on the next call. No restart.

Filters on the endpoint list (words, group, reads / writes, on / off) and "turn on / turn off all shown" let you set many at once.

Sign-in

The file says how the API signs in: API key, bearer token, basic, or OAuth2. Studio asks only for what that method needs, and the secret is kept in the API's vault record, never in the configuration. For OAuth2, Connect opens the API's own consent page; the token is renewed for you.

An API whose switched-on endpoints need no sign-in is ready without one. 2.4.509: a record that holds only the address of such an open API is complete, and nothing warns that its sign-in is missing. The API's sign-in view says whether the endpoints that are on need it: none, optional or required.
An endpoint that needs a sign-in method the mesh cannot use stays off.
Many files ask for a key the API does not actually check. Mark such endpoints needs no sign-in and they are called without one, and can be switched on.

What the agent gets

A short list of the endpoints that are on, and two tools:

Tool	What it does
`api_find`	Finds the endpoints that match what the agent needs, with their exact inputs.
`api_call`	Calls one endpoint.

You do not list these under tools:.

How calls behave

Values are checked before anything is sent. A wrong call comes back to the agent with the endpoint's inputs so it can fix it. A parameter written another way (pet_id for petId) is matched to the endpoint's own when only one fits.
The API's own answer reaches the person. "Not found", "conflict" and similar answers are passed on plainly, and the agent carries on with the rest of the task.
A read that fails on the API's side (500, 502, 503, 504) is tried again. Writes are never repeated. An API that stays down is told to the person in plain words.
Big answers arrive as whole items, with what the agent needs to ask for the next page.
Calls go only to the API's base URL. A base URL may not carry a password or point at a cloud-metadata address.

Webhooks

2.4.486+. A webhook is a single call to one of your own systems, set up on Studio's Tools page, Webhooks. An LLM agent uses it like an API, and notify (below) can post an agent's output to it.

Field	Meaning
Name	How agents refer to it
Vault record	Chosen from your Outbound webhook records
Method	`POST`, `PUT` or `PATCH`
Path	Optional; added to the record's address
Description	What the call is for
Body fields	Each with a name, a type (`string`, `number`, `integer`, `boolean`, `object` or `array`), required or not, a description and allowed values
Query values	Sent on every call, never overridden

The record is made on the Infrastructure page: Add custom → service type Outbound webhook. It holds the address as its base URL, plus header rows (for example Authorization as a secret row).

An LLM agent names the webhook the same way it names an API:

agents:
  account_manager:
    agent_type: llm
    model: gpt-4o-mini
    api_tools: [crm_update]

API entries also take fixed query values on their own page, and so do models you run on your own server (see Providers → Local Models).

Tell your systems when work is done

2.4.486+. Any agent can post its output to a webhook when it hands its work on, or when it fails:

agents:
  quote_issuer:
    notify:
      webhook: crm_update   # a webhook made on Tools → Webhooks (by its name), never a URL
      when: done            # done (default) | failed | both

notify takes only these two keys; anything else is refused at load, and so is an address in webhook.

When it is sent. At the moment the agent hands its work on (or fails). A person's seat that is still waiting for its human has no output yet, so nothing is posted.

What is sent. The webhook's method, its record's address plus the path, its fixed query values and its record's header rows (sign-in). The body is the agent's output as JSON: the agent's output fields, without the mesh's own _… keys. A plain-text output is sent as a JSON string. The webhook's body fields are not used here; they are for an LLM calling the webhook as a tool.

Headers added:

Header	Value
`X-LeafMesh-Agent`	The agent
`X-LeafMesh-Session`	The session
`X-LeafMesh-Execution`	The execution
`X-LeafMesh-Status`	`done` or `failed`

Retries. Any 2xx answer is accepted. Otherwise the call is tried again: 4 attempts in total, waiting 5 s, 10 s and 20 s between them, each attempt timing out after 30 s.

If it fails (or the webhook or its record is missing), the failure is logged and marked on the trace step notify:<webhook>. The run itself is not affected, and nothing is retried later. The mesh sends it, so no model turn is paid for it.

Connections & the Infra Page — where API keys and tokens live
Zapier, Composio & n8n — other tool sources added once on the Tools page
Shared Board — how an agent closes the ticket for the work it did