Actions

Your API, callable by the agent. The interesting part is not the calling — it is the four guards that decide whether a call is allowed to happen at all.

Defining an action

An action is an HTTP endpoint plus a description the model reads to decide when it applies. The description is the most important field you will write: it is the whole basis for the model choosing this action over another.

Field	Meaning
`name`	Short, imperative. “Get order status”, not “order_status_v2”.
`description`	When to use it and what it returns. Written for a reader who has never seen your API.
`accessType`	`READ` or `WRITE`. Writes take the confirmation path.
`method`	GET, POST, PATCH, DELETE.
`urlTemplate`	The endpoint, with `{placeholders}` the agent fills in.
`secret`	Bearer token or API key. Encrypted at rest, never returned by the API.
`requiresIdentity`	Refuse unless the visitor is verified.
`requiresConfirmation`	Refuse until the customer has explicitly agreed.

example

name         Get order status
description  Look up the current status, carrier and delivery estimate for
             one order belonging to the signed-in customer. Use when they
             ask where an order is or whether it has shipped.
accessType   READ
method       GET
urlTemplate  https://api.yourshop.com/v1/orders/{orderId}
requiresIdentity      true
requiresConfirmation  false

The four guards

These are checks in the execution path. They are not sentences in a system prompt, which means a prompt injection that convinces the model still fails at the point of the call.

1. Untested actions do not exist

An action that has never passed a test call is never shown to the model. You run the test from the dashboard with sample arguments; it records the HTTP status, duration and response body. Change the URL or method and the action reverts to untested, because the thing that passed is no longer the thing that would run.

2. Disabled actions do not exist

Toggling an action off removes it from the model’s options immediately. This is the fastest lever you have during an incident — no deploy, no prompt edit.

3. Identity, where required

With requiresIdentity, an anonymous visitor never sees the action offered. The trace records IDENTITY_REQUIRED if the situation arises. See Identity & signing.

4. Writes never auto-execute

This is the one that matters most. When the model proposes a write, it is not executed. The customer is told what will happen and asked to confirm; only on the next turn, after an explicit yes, does the call go out.

Secrets

Action secrets are encrypted at rest with AES-256-GCM and never returned by any read endpoint — the dashboard shows a masked value. Rotating a secret does not re-test the action; run the test again to confirm your new credential works before relying on it.

Writing descriptions the model uses well

Say when, not just what. “Use when the customer asks where an order is” beats “returns order data”.
Name the boundary. If it only covers orders from the last 90 days, write that. The model will otherwise offer it for a two-year-old order and return nothing useful.
Disambiguate siblings. If you have both “Cancel order” and “Cancel subscription”, each description should say what it is not for.

Debugging a call

Open the conversation in the Inbox. Each proposed or executed action shows on the turn, with its status:

PROPOSED — offered by the model, awaiting confirmation
AWAITING_CONFIRMATION — the customer has been asked
EXECUTED — the call went out; the response is recorded
BLOCKED — a guard refused it, with the reason on the trace
FAILED — your endpoint returned an error, which is kept verbatim

If an action is never proposed at all, it is almost always one of three things: it has not passed a test, it is disabled, or its description does not describe the situation the customer is actually in.

Defining an action#

The four guards#