Three ways to run the Sume video agent from code

There are three public ways to start the Sume agent from your own backend, and you choose by how often the task changes. A saved workflow with changing inputs is a Format. A saved task on a clock is Scheduled. A task that is different every time is an Agent Completion. All three use the same runtime and return the same receipt shape.

The three entry points

The Agents docs list them next to the situation each one fits.

What an Agent Completion looks like

The request takes the OpenAI messages[] shape, so existing chat code fits at the edges. The response is not choices[]. It is an asynchronous run receipt, and you poll it or take a webhook. Streaming and a synchronous OpenAI-compatible reply are not available at this time (Agent Completions).

The run gets a full sandbox, tools, the MCP bridge and media generation, which is why one request can take minutes. Do not hold an HTTP connection open for it.

Keys and scopes

Each surface has its own scope: agent_completions:read and agent_completions:write for completions, and formats:read and formats:write for Formats. Keys created before a surface shipped do not carry its scopes and fail with 403 insufficient_scope. You cannot add scopes to an existing key, so mint a new one. Service-account keys cannot create Format runs or Agent Completions.

A practical rule

• Prototype with Agent Completions. You write the whole task in the request and see what the agent does.
• When the same instruction shows up three times with different values, move the fixed part into a Format.
• When a Format should also run on a calendar, save a schedule for that part.

What stays the same

Terminal states, spend caps, idempotency keys and signed webhooks work in the same manner across the three. That means one receipt parser and one webhook verifier cover all of them. Partner integrations should use runs, not chat threads, because a run does not stop to ask a person questions.