Agent Completions

An Agent Completion runs the Sume Agent on an ad-hoc prompt. Same runtime as the Agents chat UI — full sandbox, tools, MCP bridge, media generation — reachable from your own backend with an API key, with nobody watching.

Where a schedule stores what to do and a Format stores how to do it, an Agent Completion stores nothing. You send the task on every call.

Which one do I want?

Surface	Use it when	Start with
Format	You have a saved packaged workflow and only the inputs change.	POST /v1/formats/{handle}/{slug}/runs
Scheduled	You need a schedule or a trigger on a saved automation.	POST /v1/actions/{handle}/{slug}/runs
Agent Completions	The task itself varies per call — you just want the Agent to do this thing.	POST /v1/agent/completions

All three run the same agent and return the same receipt shape. They differ only in where the instruction comes from and what Sume has saved on your behalf.

Async, not a chat drop-in

An Agent Completion is not a synchronous chat completion. A real agent turn opens a sandbox, calls tools, and may generate media, which takes far longer than an HTTP request should stay open. So the create call returns 202 with a receipt and you poll it.

The request borrows OpenAI's messages[] shape so existing plumbing fits, but the response is a run receipt, not choices[]. Streaming and a sync OpenAI-compatible wire are not available yet.

Scopes

Scope	Needed for
agent_completions:read	Read and list runs.
agent_completions:write	Create a completion, cancel a run.

Keys created before Agent Completions shipped do not carry these scopes. An older key fails every request with 403 insufficient_scope, and scopes cannot be added to an existing key. Create a new key at API Keys and rotate to it — see Authentication.

Service-account keys cannot create Agent Completions. They fail with 403 insufficient_scope and details.reason of service_account_agent_completions_unsupported.

Create a completion

Fill in the required fields to rewrite the example. generation_spend_cap_usd has no default — omit it and the request fails.

An accepted completion returns 202 with a receipt:

Request fields

Field	Required	Notes
instruction	one of	The task, as a plain string.
messages	one of	system and user turns. Send exactly one of instruction or messages, never both.
generation_spend_cap_usd	yes	Ceiling for generation spend on this run. See below.
model	no	Only sume-agent. Omit it and you get the same agent.
input	no	Caller data, written whole to /workspace/inputs/sume-action-input.json; the prompt carries a bounded pointer at it. Treated as data, never as instructions.
attachments	no	Up to 30 images the agent can see and use. See Attachments.
output_schema	no	Bind the run's output to your own schema. Same contract as Action runs.
primary_output_key	no	Which output key holds the headline result.
communication.webhook_url	no	Public HTTPS URL notified when the run reaches a terminal status. See Run webhooks — accepted, stored, and delivered on api.dev.sume.com and api.sume.com.

Idempotency-Key behaves as it does on Action runs: replaying a key returns the original receipt with idempotency_hit: true, and reusing it with a different payload returns 409 idempotency_conflict.

messages[]

content accepts a string or an OpenAI-style [{ "type": "text", "text": "..." }] array. Turns are joined, in order, into one prompt.

content also accepts { "type": "input_text", "text": "..." } as an alias for text, and { "type": "input_image", ... } parts — see Attachments.

assistant turns are rejected, not ignored. Accepting them would imply Sume replays a prior conversation, which this endpoint does not do yet — every completion runs in a fresh thread. The receipt's thread_id tells you which one.

Attachments

Send images the agent can actually look at, either at the top level or as input_image content parts. Both forms take the same item shape, and the two sources are merged into one list.

An image-only turn is fine — omit the text part and the agent is told to use the attached files.

Attachments and output_schema compose: the images reach the agent, and the run's output is still parsed against your schema after the run completes.

See Format runs for the item shape, limits, upload path, and error codes — they are identical on both surfaces.

The spend cap is required

generation_spend_cap_usd has no default. Omit it and the request fails with 400 invalid_request.

This is deliberate. An Agent Completion is an unattended agent with tools and access to your generation wallet, and the interactive spend-approval prompt that protects you in the chat UI is not available to a backend caller. The cap is the substitute. Set it to the most you are willing to spend on a single run, per run.

To size a cap, read the metered rates the run will draw against on the API pricing page.

Poll for the result

Statuses match Action runs: queued, processing, completed, failed, canceled. Poll status_url until next_action stops being poll_status.

A completed run fills output — by default the sume/action-run-output/v1 shape, with the Agent's closing text in output.text and any generated media in output.images, output.videos, output.audio, and output.files — plus artifacts and the spend recorded in usage. Media URLs are durable media.sume.com HTTPS URLs.

To stop a run in flight:

GET /v1/agent-runs lists your completions, newest first.

Errors

Status	Code	Cause
400	invalid_request	Missing generation_spend_cap_usd, neither or both of instruction/messages, an assistant turn, or a malformed input.
400	invalid_attachment	Bad attachment item — wrong type, missing or non-HTTPS URL, both image_url and asset_id, or a source that is not an allowed image.
400	attachment_not_found	asset_id is unknown in this workspace.
413	attachment_too_large	An image is over 30 MB, or the set is over 500 MB total.
502	attachment_fetch_failed	Sume could not fetch the image — unreachable host, hotlink protection, or a non-2xx response.
400	model_not_supported	model was something other than sume-agent.
403	insufficient_scope	Key lacks agent_completions:*, or is a service-account key.
404	agent_run_not_found	Unknown run id, or a run belonging to another account. An Action or Format run id will not resolve here.
409	idempotency_conflict	Idempotency-Key reused with a different payload.

Not available yet

• Non-image attachments. input_image is the only type today; PDFs and other files follow later.
• Streaming, and a synchronous OpenAI-compatible choices[] response.
• Continuing a prior thread with thread_id, and assistant turns in messages[].
• Team-owned threads. Completions are user-owned.