Agent Completions: input is data, messages are the prompt

On POST /v1/agent/completions, put the task in instruction or messages and put your data in input. The first two become the prompt: messages turns are joined, in order, into one prompt, and you send exactly one of instruction or messages. input is different. Sume writes it whole to /workspace/inputs/sume-action-input.json, the prompt carries a bounded pointer at that file, and the content is treated as data, never as instructions.

That split is a safety feature as much as a convenience. If part of your payload comes from a user, a scraped page or a spreadsheet, it belongs in input, where it cannot rewrite the task. Everything on this page is from the Agent Completions docs.

Which field holds what

Agent Completions borrows OpenAI's messages[] shape so existing plumbing fits, but the response is an agent.run receipt rather than choices[], and the create call returns 202.

Why assistant turns are refused

Accepting an assistant turn would imply Sume replays a prior conversation, which this endpoint does not do yet. Every completion runs in a fresh thread, and the receipt's thread_id tells you which one. So a chat history is not a valid input here. If earlier results matter, summarize them into the instruction or pass them as input data.

Text parts also accept input_text as an alias for text, and input_image parts are merged with top-level attachments into one list.

Where the data goes wrong

The most common mistake is splicing data into the prompt string, for example pasting a customer's free-text brief after the words "Follow this brief". That makes the brief part of the instructions. Put the brief in input and say in the instruction how to use it: what to extract, which fields to read, what to produce. The Agent then reads the file as data, and the instruction stays yours.

Sizing is the other thing to check. The docs give input limits for schedules (64 properties and 2 MiB), but for Agent Completions they state only that input is written whole to the workspace file, so keep payloads modest and send large media as attachments or URLs instead of inline text.

A request that uses all three

This asks for a caption and passes the product facts as data. The spend cap is mandatory and bounds generation spend on the run.

``bash 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: caption-001" \ -d '{ "instruction": "Write a one-line caption for the product described in the input file.", "input": { "product_name": "Aurora Headphones", "tone": "calm" }, "generation_spend_cap_usd": 1 }' ``

Poll status_url from the receipt until next_action stops being poll_status; the closing text lands in output.text. Keep in mind that Sume's safe automation notes say to keep instructions authoritative, so do not design a task where the data in input is supposed to redirect what the Agent does. The related guide on prompt order covers the Format version of this.