---
title: "Agent"
description: "Give the roasOS agent one instruction. It plans, calls the tools, and spends only up to the caps that you set."
url: https://docs.roasos.com/agent
---

# Agent

The roasOS agent is the agent that answers in the roasOS chat. It reads an ad, plans a storyboard, chooses the models, and starts the generations. An API key runs that same agent without a browser.

You give one instruction. roasOS starts one **agent run**.

## What the agent can make

Name the result that you want. The agent picks the format, the look and the models.

* **A finished video ad.** A storyboard with one cast person renders a frame for each shot first. You approve or regenerate each frame. Then roasOS animates the frames, joins the clips, adds a music bed and captions, and gives you one file.
* **A script.** The agent writes the hook, the lines for each shot and three alternate hooks, each on a different angle. It checks each draft first: a hook in the first 3 seconds, the product on screen by 3 seconds, a clear call to action, speech that fits the time, and no claim that your product facts do not support.
* **A named format.** Product review, how-to, unboxing, product showcase, try-on, TV spot, before and after, duo UGC, green-screen reaction, reply to a comment, gift reaction, podcast clip, street interview and song ad. Each format has its own beat structure.
* **A product effect.** Giant product, bullet time, macro splash or pour, packshot closer, ASMR and levitation. No person appears, and the label stays readable through the motion.
* **A look.** Phone UGC, cinematic, studio, claymation, 3D animation, needle-felt, and four faceless looks: paper diorama, whiteboard doodle, flat 2D and mannequin.
* **Static ads.** A set of statics with your copy and brand kit, headline variants of a winning static, and a resize pack for 1:1, 4:5 and 9:16.
* **A TikTok photo slideshow.** 5 to 8 slides at 9:16 with the text drawn in and one soft product plug, ready for TikTok photo mode.

`GET /v1/formats` lists every format, effect, slideshow and static pack, with its beats, what it needs and the skill that runs it. The agent reads the same list.

roasOS checks each frame and each finished clip for a wrong person, a warped or misspelled label, garbled text, morphing hands and broken lip-sync. A failed check is advice. A new render is a new approval, never automatic.

The agent chooses models by job. The roster and the default model for each job come from `GET /v1/catalog` (`roles`). When a new model is better at a job, the agent uses it. When you name a model, the agent uses your model.

## One run for every trigger

An ask, a saved skill, a typed workflow, a schedule, and a chat turn are the same run. They use one status vocabulary, one meter, and one read path. There is no `/v1/skill-runs` and no `/v1/routine-runs`.

| `trigger`  | What starts the run                                                        | Read the run at           |
| ---------- | -------------------------------------------------------------------------- | ------------------------- |
| `api`      | [`POST /v1/agent/completions`](/agent/ask-the-agent)                       | `GET /v1/agent-runs/{id}` |
| `skill`    | [`POST /v1/skills/{id}/runs`](/agent/skills)                               | `GET /v1/agent-runs/{id}` |
| `workflow` | A typed door, such as [`POST /v1/workflows/remix`](/workflows/remix-an-ad) | `GET /v1/agent-runs/{id}` |
| `routine`  | A schedule that you make in roasOS                                         | `GET /v1/agent-runs/{id}` |
| `chat`     | A message in the roasOS chat                                               | The thread in roasOS      |

These five words are the values that `trigger` publishes. A run keeps its trigger for its whole life.

A chat turn is part of your plan. A run that starts from a key uses credits. Refer to [Runs](/agent/runs) for the meter.

## The run is asynchronous

The run answers `202` with a run id. The agent then works for as long as the work needs.

1. Quote the run. A quote is free.
2. Confirm the quote. roasOS reserves the ceiling.
3. Poll `GET /v1/agent-runs/{id}/status`.
4. Read `GET /v1/agent-runs/{id}/result` when the status is terminal.

<Callout type="warn">
  An agent run sends no webhook. Poll the status. Refer to [Runs](/agent/runs).
</Callout>

## Two caps, and neither one replaces the other

Each run carries two caps. Both are in credits. Both are optional. Each one stops at 100,000 credits.

| Field                          | What it bounds                                     | Default                                                   |
| ------------------------------ | -------------------------------------------------- | --------------------------------------------------------- |
| `max_credits`                  | The tokens that the run's own thinking uses        | 25, or your key's unattended limit if that limit is lower |
| `generation_spend_cap_credits` | The paid work that the run starts without a person | 0                                                         |

The default of `generation_spend_cap_credits` is **0**. A run that says nothing about this cap can therefore never charge you for a render.

The quote is the sum of the two caps. It is a ceiling, not a guess. roasOS reserves that ceiling at the confirm step. It refunds the part that the run does not use.

Your key's spend policy bounds both caps, and the policy always wins. Refer to [Spend caps and approvals](/agent/ask-the-agent#spend-caps-and-approvals) and to [Quotes and credits](/concepts/quotes-and-credits).

## What the agent may approve, and what it may not

A paid action inside a run opens an **approval**.

* The run approves the action itself when the price is inside `generation_spend_cap_credits` **and** inside your key's unattended limit. The run continues.
* The run leaves the approval open in all other conditions. The approval waits in `pending_approvals`. The work does not start, and roasOS charges nothing for it.
* One approval card carries at most eight quotes. A storyboard render has three more conditions, because it renders several clips under one card. Refer to [Spend caps and approvals](/agent/ask-the-agent#a-storyboard-render-has-three-more-conditions).

An API caller can **approve** an open approval, and can **decline** one. A run that starts from a skill or from a workflow writes no thread. REST is the only door that such a run has. Refer to [Approve an approval](/agent/runs#approve-an-approval).

A connected model is not an API caller in this rule. An MCP client can decline an approval, and it can never approve one. This rule keeps a review step from becoming a rubber stamp.

## What the agent reads

A run reads your workspace before it writes. It takes the brand kit, the pinned memory and the intelligence documents as its facts. The answer therefore states your product and your voice. You read and write the same records over REST.

| What the run reads                        | The door you use for the same record                    |
| ----------------------------------------- | ------------------------------------------------------- |
| The brand kit                             | [`GET /v1/brand-kit`](/brand/brand-kit)                 |
| The pinned memory and the marketing brief | [`GET /v1/memory/pins`](/brand/memory)                  |
| The intelligence documents                | [`GET /v1/intelligence/documents`](/brand/intelligence) |

Every one of these doors costs 0 credits. Refer to [Brand](/brand).

## Scopes

| Operation                                                             | Scope       |
| --------------------------------------------------------------------- | ----------- |
| `POST /v1/agent/completions`, `POST /v1/skills/{id}/runs`             | `api:write` |
| `POST /v1/agent-runs/{id}/cancel`, the approve path, the decline path | `api:write` |
| Every `GET` under `/v1/agent-runs` and `/v1/skills`                   | `api:read`  |

## Next

<Cards>
  <Card title="Ask the agent" href="/agent/ask-the-agent">
    The full loop: quote, confirm, poll, read the answer.
  </Card>

  <Card title="Runs" href="/agent/runs">
    The run envelope, the events, the cost, the approvals, and cancel.
  </Card>

  <Card title="Skills" href="/agent/skills">
    Run a saved ask, or one of the nine skills in the roasOS pack.
  </Card>

  <Card title="Connect an AI agent (MCP)" href="/mcp">
    Nine of the eleven operations on these pages are also tools on `mcp.roasos.com`. Approve and cancel stay REST.
  </Card>
</Cards>