Format run input extra keys: context only, not echoed in output

If you put your own reference key, such as sheet_no, in a Format run's input, the run receives it as context but it does not come back in output. So you cannot rely on the result to carry your row number. Store the key beside the data.id and data.thread_id the 202 returns, and join on those.

What the recipe reads

The cookbook's live-commerce recipe names the keys it reads: product_url, host_image_url, vo_language, script and price. Other keys go to the run as context. That is useful (the agent can see a campaign label) and it is a trap if you assume the receipt echoes them.

The output object is shaped by output_schema alone. A strict schema with additionalProperties: false forbids extra fields by design.

The join pattern

Write your row id and the run id to your own table when the 202 comes back. When the webhook lands or you poll the receipt, look up by run id. If you need the value inside the output, add a property for it to your output_schema and tell the instruction to copy it, then check it on the way back.

For a bulk queue, use the item index instead, as the spreadsheet mapping post explains.

import os, sqlite3, requests
db = sqlite3.connect("runs.db")
db.execute("create table if not exists runs(sheet_no int, run_id text, thread_id text)")
r = requests.post(
    "https://api.sume.com/v1/formats/acme/live-commerce/runs",
    headers={"Authorization": "Bearer " + os.environ["SUME_API_KEY"],
             "Idempotency-Key": "sheet-45-v1"},
    json={"instruction": "Use the script as written.",
          "input": {"sheet_no": 45}, "generation_spend_cap_usd": 20},
    timeout=30,
)
d = r.json()["data"]
db.execute("insert into runs values (?,?,?)", (45, d["id"], d.get("thread_id")))
db.commit()

Why the output is strict

The cookbook's schema marks every property as required and sets additionalProperties to false. Each property is necessary, and an optional property is expressed as a nullable one. That strictness is what makes a receipt trustworthy: a run that fills scenes but not full_video is marked failed rather than a false success.

It also explains the behavior in this post. The output is not a mirror of the input. It is whatever the schema describes, produced by the agent, and anything you want echoed has to be requested through the schema.

A practical consequence for batches: if you later join results to a spreadsheet by a value that only exists in input, you will find the join key missing exactly when you need it. Decide the join key before the first run, not after.

Checklist before a first batch

• Write the run id and thread id to your own store at the moment of the 202.
• Use a deterministic Idempotency-Key built from your row id, so a retry of the submit is safe.
• Add any value you need inside the output to the schema, and verify it in a small test.
• Keep context keys short and factual.

Limits

The input object has its own bounds: an object only, at most 64 top-level properties, at most 2 MiB. Keep references short. And a context key can still steer the agent, so do not put text there that you would not want in the instructions.