script_run or bulk runs: where to fan out 20 ad variants

Use script_run when an agent needs many small Sume tool calls in one turn, such as 20 tts_create or generate_image submits, and use a bulk run when each unit is a whole Format run that takes minutes. script_run is bounded by one request of at most 55 seconds, so it submits jobs and returns their ids. A bulk queue holds up to 100 Format runs on the server.

Both are programmatic fan-out, but they sit at different layers, and mixing them up is the usual reason a batch dies halfway.

What each one is

script_run is programmatic tool calling on the Sume MCP server. The agent writes a short JavaScript body that calls other Sume tools in a loop and returns one value, and the intermediate results stay out of the conversation. A bulk run is POST /v1/formats/{handle}/{slug}/bulk-runs, a server-side queue of ordinary Format runs.

The script_run rules that bite

• A budget stop ends the run with script_timeout, script_call_budget_exceeded, script_paid_budget_exceeded or script_tool_forbidden, and the journal is still complete.
• Paid creates inside a script still need their own distinct idempotency_key, for example one per loop index.
• Do not wait for long jobs inside the script. Submit, return the job ids, then jobs_wait and jobs_result outside it.
• Discovery tools and script_run itself are refused inside a script.

The bulk rules that bite

• The queue has no webhook. Put communication.webhook_url on each item, or poll status_url.
• Queue completed means every item is terminal, not that every item succeeded. Check counts.failed.
• A bad item fails the create with 400 and details.index before any queue exists.
• Mint a fresh Idempotency-Key per batch, because a replayed key returns the old queue.

A rule of thumb for 20 variants

If the 20 variants are 20 stills or 20 voice lines, fan out inside one script_run and wait for the jobs afterwards. If each variant is a finished video from a saved Format, queue them as 20 bulk items with concurrency at 3 or 4, and give every item a cap. The second path is the one that survives a closed laptop.

Mixed designs work too. An agent can use script_run to submit twenty cheap stills, wait for them outside the script, pick six, and then hand those six to a Format run or a bulk queue for motion. The two limits then protect different things: the script budget bounds the fan-out of the first step, and the per-item cap bounds the cost of the second.