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.

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 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.

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.

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 and to 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.

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.

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.

Every one of these doors costs 0 credits. Refer to Brand.

Scopes

Next