Which Sume API should a workflow agent step call?
A workflow agent step needs a fixed recipe, a clock, or an open task. Pick Format run, Scheduled action or Agent Completion by what you know up front.
A workflow agent that calls a video step has three Sume surfaces to choose from, and the right one depends on how much of the job you already know. If the recipe is fixed, call a Format run. If a clock should start it, create a Scheduled action. If the task is open-ended and you only have a brief, send an Agent Completion. All three take a spend cap, but they differ in what the cap defaults to.
Parameters are from Sume's docs for Calling a Format, Scheduled and Agent Completions.
How do the three compare?
A Format run is POST /v1/formats/{handle}/{slug}/runs. It takes an input object of at most 64 keys and 2 MiB, supports an Idempotency-Key, and accepts generation_spend_cap_usd up to $500. A scheduled action uses a 5-field cron and an IANA time zone, and its default spend cap is $1.00, which a per-run override can only lower. An Agent Completion is POST /v1/agent/completions, returns 202, and requires generation_spend_cap_usd with no default.
| Surface | Use when | Cap default |
|---|---|---|
| Format run | The recipe is fixed and inputs vary | Up to $500; null runs at $500 |
| Scheduled action | A clock starts the work | $1.00; overrides only lower it |
| Agent Completion | The task is a brief | None; field is required |
What should I ask first?
- Do I know the steps? Use a Format and pass only the inputs.
- Does time trigger it? Use a Scheduled action; schedules are authored in the Agents dashboard or by asking the Agent in chat.
- Do I only have a goal in words? Use an Agent Completion, and put customer data in
input. - Do I need many items? Format bulk runs take 1 to 100 items and a concurrency of 1 to 16.
What do all three share?
Runs are tracked by receipt, and terminal events can arrive by webhook: action.run.terminal, format.run.terminal, or agent.run.terminal. Admission rules apply to all: a plan's concurrency is Free 1, Pro 4, Startup 8 and Scale 20, with queue_full and rate_limited returning 429 and insufficient_credits returning 402.
What is the most common mistake?
Using an open task where a recipe exists. An Agent Completion decides its own steps, so cost and output vary run to run. A Format run with the same inputs is easier to cap, test and compare. Reach for the agent only when the task cannot be written as a recipe.
A last check on cost: null on a Format run's cap runs at the $500 ceiling and 0 is rejected, while a scheduled action's null runs without the automation ceiling. Treat null as a decision you make on purpose, never a default your workflow inherits.
Sources
Related posts
More in Developers
- Which Timeline warnings does the free plan call show before rendering?
Timeline plan reports gaps, tail holds, frame snaps and ignored motion, but not short sources, downgraded fades, fps resampling or soundtrack length.
- Windmill run_wait_result vs a Sume async submit: pick one per job
Windmill advises async mode and offers run_wait_result for short jobs. Sume mirrors that split: async submit plus polling for long work, sync only for short.
- Windmill sync returns 200 on error: check Sume's failed flag too
Windmill's sync webhook returns HTTP 200 with the error as JSON by default. Do not trust the status code alone for Sume jobs: read terminal, failed and sync.
- Crash-safe Sume submit: write the intent row and key first
If your process dies after a Sume submit but before storing the job id, a pre-written intent row and Idempotency-Key let the retry return the original job.
Written by Sume