Agents
The Sume video agent from code: Agent Completions, scheduled runs, MCP tools and timeouts, programmatic tool calling, and guardrails for paid APIs.
Start with What is a video agent? How Sume defines and runs one
How to use Sume 2.0
Sume 2.0 in the app itself: how you get into Sume, Chat and Studio from the first window, and what to press in each, one scenario at a time.
Planlock in front of Sume MCP: approve the plan, then the calls
Planlock is an MCP proxy that enforces a human-approved plan. Where it fits in front of Sume's hosted MCP, and which Sume gates still do work behind it.
Send product photos to the Sume agent API, get edited images back
Agent Completions takes up to 30 image attachments and a required spend cap, then returns generated images in output.images. When to use it over /v1/images.
Scheduled run cost cap: a per-run cap can only lower it
A scheduled Sume run defaults to a $1.00 cap. A per-run cap can only lower the schedule cap, never raise it. Here is how that differs from a direct Format call.
Can I create a Sume schedule over the API? Not today
Sume schedules are created in the dashboard with a cron and timezone or an API-only trigger. The API cannot create or edit them, but it can fire and read runs.
Guardrails for an AI agent that calls paid media APIs
Five guardrails for an agent that spends money: required cap, read before paying, idempotency keys, no secrets in logs, and a cancel path. Drawn from Sume docs.
Porting chat-completions code to Sume Agent Completions
Agent Completions takes system and user messages, rejects assistant turns, returns a 202 receipt, and does not stream. Here is what to change when porting.
Copilot Studio hooks fail open: cap paid media spend server-side
Copilot Studio hooks can block a tool call, but a failed hook lets the agent continue. Put the media spend limit where it can't fail open: the Sume run cap.
Gemini agent keeps memory for days; Sume API runs start fresh
Google's Gemini agent keeps one memory across devices and days. Sume's API runs start in a new thread, so state travels as input, files and previous_run_id.
Agent SDK verbatim_prompts vs Sume Agent Completions input
The Claude Agent SDK verbatim_prompts option stops @path and slash expansion of user text. Sume Agent Completions keeps input as data in a file. Compare them.
How to cap an AI video agent's spend: five limits, in order
A video agent has five separate limits: model budget, turns, per-call max_spend_usd, run cap and plan queue. Which stops a runaway Sume job, and which does not.
Codex worktrees run agents in parallel: one Sume queue
Codex CLI 0.162.0 adds managed worktree tools. Parallel agents in worktrees still share one Sume workspace: plan concurrency, queue and 429 queue_full apply.
Stopped a Sume MCP call in Claude Code? The job still runs
Stopping a long Sume MCP wait in Claude Code does not stop the render. The job keeps running and billing; find the job id, then wait again, read or cancel.
claude --fallback-model when overloaded: Sume paid calls
--fallback-model switches Claude Code to another model when the main one is overloaded. Sume's spend caps and idempotency keys are independent of the model.
Sume schedule run: communication.mode webhook alone sends nothing
On a Sume schedule run, communication.mode is descriptive only. Delivery starts when communication.webhook_url is set, an HTTPS URL up to 2,048 characters.
Sume API key with actions:read only: list schedules, not start runs
A Sume key with actions:read can list and read schedules and runs. Starting or canceling a run needs actions:write; keys made before the trigger lack both.
Should an agent tool take a workspace_id argument for Sume calls?
No. Sume's safe-automation guidance says the API key or app session selects the workspace and tools must not take a workspace id from the user.
Agent Completion: a 15 s MiniMax H3 clip plus voiceover, cap 1.50
A 15-second MiniMax H3 clip at 768p ($1.125) plus a 750-character voiceover ($0.035625) comes to $1.160625, so a cap of 1.5 is enough. Table and body.
Agent run log allowlist: which Sume fields are safe to keep
Log request ids, job ids, status and sanitized media metadata from Sume agent runs; never log API keys, signed URLs, raw private media URLs or full transcripts.
Canceled and skipped Sume agent runs send no webhook: what to poll
A Sume run webhook fires only when a run completes or fails. Canceled and skipped runs send nothing, so your scheduler must read status_url for them.
Agent Completion attachments: 16 full-size images fit the 500 MB cap
An Agent Completion takes up to 30 images, each up to 30 MB, in a set up to 500 MB. At full size only 16 fit; for 30 images the average must be under 16.7 MB.
Your agent calls generate_video, or Sume's agent does: two meters
With hosted MCP your model client runs the loop and you pay its provider; with an Agent Completion Sume's agent runs it and you set generation_spend_cap_usd.
Five gates between a Sume MCP write session and your wallet
A hosted Sume MCP write session has five gates before money moves: scope, idempotency_key, dry_run, an optional max_spend_usd, and wallet admission.
Unattended agent: stop or retry on Sume 402, 409, 429, 503?
An unattended Sume agent should stop on 402, fix on 400, retry 429 and 503 with the same idempotency key, and never reuse a key after a 409.
script_run limits: timeout 5-55 s, max_calls and max_paid_calls
Sume's script_run runs a short script of MCP tool calls with a 5 to 55 second timeout and caps on calls and paid calls. What it returns and cannot call.
Scheduled run spend cap: a request can lower it, never raise it
A Sume schedule's per-run cap is min(request, schedule cap). A $3 request on a $1 schedule runs at $1; null removes the ceiling; 0 is a 400.
Agent Completions rejects assistant turns: how to carry chat history
Sume Agent Completions return 400 on any assistant message in messages[] and start a fresh thread each time. Here is what that means for multi-turn history.
Claude Motion makes MP4s from code: when a Sume Agent run fits instead
Claude Motion (beta, 2026-10-08) animates text and charts as code. Sume Agent Completions generate footage and return media URLs. Which fits which job.
Daily Sume schedule: skipped and canceled runs send no webhook
A Sume run webhook fires only on completed or failed. For a daily schedule, a skipped or canceled run is silent, so add a list-runs check each morning.
Which Sume MCP tools to leave undeferred when Claude searches tools
Anthropic says to keep 3 to 5 frequently used tools non-deferred. Which Sume hosted MCP tools to pin and which to defer.
Haiku 5.5 effort for an agent that polls Sume jobs
Claude Haiku 5.5 defaults to medium effort. What that means for a loop that calls Sume jobs_wait, and when to move to low or high.
Use a low-effort Haiku 5.5 subagent for Sume dry_run previews
Anthropic recommends low effort for subagents, and warns it can skip checks. Where a Haiku 5.5 subagent fits in front of a paid Sume call.
Sume MCP avatar tools: 5 read-only and the paid create set
Hosted Sume MCP lists five read tools for avatars and avatar videos and a paid group for creates and previews. What OAuth mcp:read sees and the dry_run flow.
Scheduled run spend cap: a per-call number can only lower it
A Sume schedule's default generation cap is $1.00. A per-run number is clamped to the lower of the request and the schedule cap, and 0 is rejected.
What an agent should log when it calls Sume: ids yes, signed URLs no
Safe log fields for agents using the Sume API, CLI and MCP: request ids, job ids, status, sanitized media metadata. Never keys, signed URLs or transcripts.
Claude Code prompt hook: 30 s default, a model checks a Sume render
A prompt hook asks a model to review a tool call, with a 30-second default timeout. When that suits a Sume render and when a script check is the better gate.
Codex 0.161 defaults to GPT-6.1 Sol: recheck how it calls Sume tools
Codex 0.161.0 makes GPT-6.1 Sol the default model in bundled and Amazon Bedrock catalogs. Re-run a free Sume read and a dry run before trusting paid calls.
Resume a Gemini CLI session after a Sume render: keep the job ids
Gemini CLI 0.64 preview stops deleting resumed session history. How to pick a Sume video job back up after a restart with jobs_list and jobs_wait.
Codex background tasks keep their turn's permissions: paid Sume calls
Codex 0.161.0 background tasks retain the permissions of the turn that started them. What that means for a Sume render started from a background task.
Keep untrusted text out of the prompt: Sume run input is data only
Sume writes a run's input object to a file and treats it as data, not instructions. Schedule runs allow 64 properties and 2 MiB. Use it as a guardrail.
Swap the LLM behind your MCP client: do Sume's gates change?
No. Hosted MCP gates sit in scopes, idempotency_key and max_spend_usd, not in the client model. What each session type can see, whatever model it runs.
Nightly Sume schedule: model choice and the 30-day cap math
A nightly Scheduled run caps generation at $1.00 by default, so 30 nights is at most $30. How the model's token cost sits beside that cap, with the arithmetic.
Schedule fires while the last run is active: skip or reject?
Sume schedule API runs default to on_active_run skip, which returns 200 with a skipped receipt. reject returns 409 action_run_in_progress. When to pick each.
One Sume webhook endpoint for three run types: verify, route
Format, action and agent runs share one signature scheme. Verify HMAC-SHA256 over timestamp.body, refuse an empty secret, then route on the event field.
Format run input is data, not instructions: a boundary, not a sandbox
Format runs write input to a file as data, not as instructions. That helps against prompt injection but is not a sandbox. The spend cap bounds the damage.
Agent turns a product page into a clip: crawl_scrape, generate_video
On Sume MCP, crawl_scrape is a read tool that works with Write off. generate_video is paid and needs Write or a key. Split the job in two sessions to cap spend.
Backend job that needs an agent: Agent Completions or hosted MCP?
Agent Completions runs Sume's agent and returns a 202 receipt with a required spend cap. Hosted MCP is for a client whose own model calls Sume tools.
Waiting 10 minutes for a Sume render over MCP: 11 jobs_wait calls
A remote MCP jobs_wait holds at most 55 seconds, so a 10-minute render takes up to 11 calls at the cap, 12 at the default 50. Re-issue the wait; never resubmit.