Agent Completions input: JSON data the agent reads from a file

When you call Sume's Agent Completions API with a list of SKUs, a product feed or a transcript, you have two places to put it: inside the instruction string, or in the input object. Use input. Sume writes everything in it to /workspace/inputs/sume-action-input.json in the agent's sandbox, and the prompt carries only a bounded pointer to that file. The agent is told to read the file as data, never as instructions.

Why a file beats a long prompt

The instruction field accepts up to 100,000 characters, but a prompt packed with rows is a poor way to give an agent a dataset. A file can be parsed, filtered and re-read. The prompt stays short, so your actual instruction is the first thing the model sees, and the data does not drown it.

The shape is yours. input must be a JSON object, and any keys are allowed. The Formats docs cap input at 64 top-level keys and 2 MiB, and say Sume never truncates it. Those caps are written for Format runs; stay inside them for completions too, and group keys inside one object when you have many.

A request that runs

generation_spend_cap_usd is required, has no default, and 0 is rejected. Send the Idempotency-Key header, which this route reads. The reply is a 202 receipt with an agrun_ id; poll GET /v1/agent-runs/{id} until next_action is no longer poll_status.

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: feed-2026-10-05-batch-1" \
  -d '{
    "instruction": "Read the input file. For each sku write a one line product caption.",
    "input": { "skus": [ {"sku": "A1", "name": "Trail mug"}, {"sku": "B2", "name": "Desk lamp"} ] },
    "generation_spend_cap_usd": 1
  }'

What to put where

Keep the task in instruction: what to do, the tone, the output you want. Keep facts in input: rows, URLs, ids, text you did not write. If you also bind a result shape with output_schema, the agent output is parsed against it after the run completes, and the data file feeds it with no change.

The docs name one more reason: Sume uses the value only as data. That matters for text you scraped or got from a user, which may contain sentences that read like orders. Putting it in input marks it as material to be processed, but it is not a guarantee, so still keep the spend cap tight.