Weekly content plan from an Agent Completion: output_schema in Python

To get a week of content ideas from the Sume agent as typed JSON, POST /v1/agent/completions with an instruction, a required generation_spend_cap_usd, and an output_schema, then poll GET /v1/agent-runs/{id} until the run is terminal. The call returns 202 with a receipt, not a chat reply, so the Python below has a loop.

Use a completion when the task changes each week. If the same recipe repeats and only the inputs change, a Format run is the saved version of it; if only the clock decides, a schedule is.

The request

The cap has no default: omit it and the call fails with 400 invalid_request. The schema follows the strict rules: object root, additionalProperties: false, every property in required.

import json, os, time, urllib.request

H = {"Authorization": "Bearer " + os.environ["SUME_API_KEY"], "Content-Type": "application/json"}

def call(path, body=None):
    req = urllib.request.Request("https://api.sume.com" + path, headers=H,
                                 data=json.dumps(body).encode() if body else None)
    with urllib.request.urlopen(req) as r:
        return json.load(r)["data"]

schema = {"name": "weekly-plan", "schema": {"type": "object", "additionalProperties": False,
  "required": ["posts"], "properties": {"posts": {"type": "array", "items": {
    "type": "object", "additionalProperties": False, "required": ["day", "idea"],
    "properties": {"day": {"type": "string"}, "idea": {"type": "string"}}}}}}}

run = call("/v1/agent/completions", {"instruction": "Plan five short video posts for next week.",
    "generation_spend_cap_usd": 2, "output_schema": schema})
while run["status"] in ("queued", "processing"):
    time.sleep(10)
    run = call("/v1/agent-runs/" + run["id"])
print(run["status"], json.dumps(run["output"])[:200])

Reading the result

• Statuses are queued, processing, completed, failed, canceled.
• A completed run fills output against your schema; artifacts and usage come with it. If the output could not satisfy the schema, output is null and output_error says why.
• Media URLs inside output are durable media.sume.com HTTPS URLs.
• Cancel with POST /v1/agent-runs/{id}/cancel.

Limits worth knowing

Does and does not

Sume runs the agent and returns the plan. It does not post for you, and it does not remember last week's plan unless you send it in instruction or input. input is written whole to /workspace/inputs/sume-action-input.json and treated as data, never as instructions, so put the prior week's topics there.