primary_output_key: which output key is a Sume agent run's headline

An agent run can return text, several images, a video and files. Your backend usually wants one of them. primary_output_key names it, and the receipt resolves it for you.

Where the field lives

On Agent Completions, primary_output_key is an optional request field: the output key that holds the headline result. On a schedule you bind it in the dashboard together with an output schema, as described in Create a schedule. The receipt then carries primary_output_key and primary_output_url, which are null unless status is completed (Runs and results).

A worked example

The docs give an image schema named sume/action-image-v1 with caption and image properties, where image is a SumeMediaFile reference, and primary output key image. The run then returns output.image.url as a durable media.sume.com URL. Clearing the schema name and key returns you to the default shape, sume/action-run-output/v1, with text, images[], videos[], audio[] and files[].

{
  "type": "object",
  "additionalProperties": false,
  "required": ["caption", "image"],
  "properties": {
    "caption": { "type": ["string", "null"] },
    "image": { "$ref": "SumeMediaFile#" }
  }
}

Why not just take the first video

Picking output.videos[0] works until the agent makes a draft and a final, or an intro and an outro. Naming the key moves that decision into the schema, where it is versioned with the run, and gives your code a single field to read when next_action says there is nothing more to fetch.

If projection fails, the receipt carries output_error and the run's error.code is that code; read both before you retry. Retrying a failed projection by starting a new run starts a new spend, so check the cap first.