Own agent loop vs one Sume Agent Completion request

An Agent Completion lets your backend start the Sume Agent with a single POST /v1/agent/completions, instead of running your own tool-calling loop against the generation APIs. It returns a 202 and an agent.run receipt you poll, and generation_spend_cap_usd is required with no default (Agent Completions).

What it covers

A request

Send exactly one of instruction or messages. Assistant turns are rejected; each completion runs in a new thread.

curl -sS -X POST "https://api.sume.com/v1/agent/completions" \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ac-001" \
  -d '{
    "instruction": "Write one caption for the attached product shot.",
    "attachments": [{"type":"input_image","image_url":"https://cdn.example.com/shot.jpg"}],
    "generation_spend_cap_usd": 2
  }'

What it does not do

There is no streaming and no synchronous OpenAI-style choices[] response. Non-image attachments, continuing a prior thread with thread_id and team-owned threads are listed as not available yet.

Choosing among three surfaces

A Format stores how to do a job and takes inputs per call. A schedule stores what to do on a cadence. A completion stores nothing and fits a task that changes on each call. All three run the same agent and return the same receipt shape.

Polling the receipt

Poll GET /v1/agent-runs/{id} (or the receipt's status_url) until next_action is no longer poll_status. Statuses are queued, processing, completed, failed and canceled. A completed run fills output, with the last text in output.text and generated media in output.images, output.videos, output.audio and output.files. POST /v1/agent-runs/{id}/cancel stops a run in progress.

Keys created before Agent Completions shipped lack the agent_completions:* scopes and get 403 insufficient_scope; create a new key. Service-account keys cannot create completions.