Agents

An AI agent — your own, built on any model or framework — can find workflows, start runs and read their outputs through the same API as any other code. This page covers how to give an agent that access safely today, and what the assistant inside the app does.

What exists today#

• Today: the HTTP API, described as OpenAPI 3.1, and team API keys with scopes and monthly caps.
• Today: the assistant on the canvas, which helps a person design a workflow.
• Today: an MCP server with ready-made tools — search your library, price and start runs, read what they made. If your agent speaks MCP, start with Connect your AI agent (MCP); the rest of this page applies to it too.

Give your agent the contract#

The whole API is one OpenAPI document at /api/v1/openapi.json. It needs no key, so an agent or a code generator can fetch it directly. It lists every endpoint, every field, every scope and every error, and it is checked against the API's own routes, so a new endpoint cannot ship without it. For a shorter start, /llms.txt lists every endpoint and guide in one Markdown page, built from the same document.

curl "https://app.sushibelt.ai/api/v1/openapi.json"

Most agent frameworks can turn an OpenAPI document into tools. Offer the agent only the operations it needs: for most agents, List workflows, Run a workflow and Get a run.

One key per agent#

Create a key for each agent, in the app under Team settings → API keys:

• Name it after the agent, so the list shows which agent used which key, and when.
• Give it only the scopes it needs. An agent that runs workflows needs workflows:read, runs:create and runs:read. Leave out workflows:write unless the agent should create workflows. An agent that only reports on runs needs runs:read alone, and then cannot spend at all.
• Give it a monthly cap. See Cost caps.
• Keep it out of the agent's prompt. Pass the key to the tool that makes requests, from the environment, so the model never sees or repeats it.

If an agent misbehaves, revoke its key. It stops working at once, and no other agent is affected.

Avoid duplicate runs#

Agents retry. The API has no idempotency key, but three things together keep a retry from paying twice:

1. One run per workflow at a time. While a run is in progress, starting the same workflow again answers 409 and names the run in activeJobId. Tell the agent to read that run rather than start another.
2. Save the jobId first. Have the agent record the jobId before it does anything else, so a restarted agent reads the run instead of starting a new one.
3. De-duplicate webhooks. A delivery can arrive twice; jobId and event together identify it.

Once a run has ended, starting the workflow again is a new run and is charged again. Creating a workflow is not protected at all: a repeated call creates a second workflow.

Polling or webhooks#

An agent in a conversation usually polls: it starts a run, then reads it every few seconds until it completes or fails. Give it a time limit, and remember that a key's requests share one rate limit (60 a minute by default). An agent that runs in the background can pass a callbackUrl and be woken by a webhook instead. See Poll or get a webhook.

Cost caps#

An agent should not be able to spend more than you meant it to. Set these before you let it run:

• A monthly cap on its key. Once the key has spent its cap this month, it cannot start runs. The cap is checked when a run starts, so the last run can take it a little past.
• A per-step credit ceiling for your team, so no single step can be expensive.
• Draft runs while the agent is still learning a workflow: "mode": "draft".
• The estimate. Every run answers with estimatedCredits. Have the agent report it, or check it against a budget of its own.

Every limit answers 402 with a body that says which one. Tell the agent to stop and report a 402, never to work around it. See Cap your spend.

Example instructions for an agent#

A starting point for the part of your agent's instructions that covers Sushibelt. Adapt it to the tools your framework gives the agent.

You can generate game assets with the Sushibelt API.
The API is described at https://app.sushibelt.ai/api/v1/openapi.json.
Authenticate every request with the header: Authorization: Bearer <key from the environment>.

Rules:
- Run only workflows listed by GET /workflows. Never create workflows unless asked.
- Start a run with POST /workflows/{id}/runs. Save the jobId before anything else.
- If the answer is 409, a run of that workflow is already in progress: read the run named
  in activeJobId instead of starting another.
- Read a run with GET /runs/{jobId} no more than once every 5 seconds. Stop waiting after
  15 minutes and report the run as unfinished.
- If a run fails, report each failed step's error. Do not start the run again without asking.
- If the answer is 402, stop and report the error field. Never try to work around a limit.
- Report estimatedCredits for every run you start.

The assistant in the app#

On the canvas, the Assistant tab lets a person describe what they want in words. The assistant is an AI model (Claude, made by Anthropic). It reads your brief and the workflow on the canvas, suggests models that suit the job, and proposes changes to the workflow, or options to choose from.

• You decide. A proposal changes nothing until you apply it: to this workflow, or as a new version. A new version becomes the one the agent runs, including when you call Run an agent.
• It spends credits. Each message is charged to your team's credits when the assistant answers, and needs a balance to start.
• It is for people. The assistant has no API of its own; your agent works through the API above.

Two meanings of agent#

In the app, an agent is also a container for versions of one workflow, inside a project. Run an agent runs that container's active workflow. It is not an AI model. See Workflows.