Kiro Web Workflows run in the background: pairing with Sume runs

A Kiro Web Workflow step that needs Sume to do a chunk of media work should start an Agent Completion and carry on, because both are asynchronous: Sume returns a 202 receipt immediately and tells you where to poll or where to send a webhook. Kiro's changelog describes Web Workflows (2026-09-30) as background multi-step agent plans with named steps and agents, with bundled recipes investigate, feature-pipeline, and publish-pr, and controls to answer a step, steer the agent, or message a step's agent (read 2026-10-03).

The Kiro facts are on the changelog. The Sume facts are in Agent Completions and Run webhooks.

Why the shapes match

A background workflow cannot afford a step that blocks for minutes, and Sume's completions are not synchronous chat. A real agent turn opens a sandbox, calls tools, and may generate media, so the create call returns a receipt. The request borrows OpenAI's messages[] shape or takes an instruction string, but the response is a run receipt, not choices[].

The call the step makes

The step needs an API key with the agent_completions:write scope; older keys do not carry it and fail with 403 insufficient_scope, and service-account keys are refused too. generation_spend_cap_usd is required and has no default, so the step must say how much the run may spend. communication.webhook_url registers a public HTTPS URL for one signed terminal POST, so the step need not poll.

import os, httpx

key = os.environ.get("SUME_API_KEY", "")
if not key:
    raise SystemExit("SUME_API_KEY is empty")

r = httpx.post(
    "https://api.sume.com/v1/agent/completions",
    headers={"Authorization": f"Bearer {key}",
             "Idempotency-Key": "kiro-step-publish-001"},
    json={
        "instruction": "Write a 20-word caption for the attached brief.",
        "generation_spend_cap_usd": 1,
        "communication": {"webhook_url": "https://hooks.example.com/sume"},
    },
    timeout=30,
)
print(r.status_code, r.json()["data"]["status_url"])

Closing the loop

When the run reaches a terminal status Sume sends one signed POST with the same receipt the poll endpoint returns, and the event name is agent.run.terminal. Branch on outcome: ok, degraded, or error. A run can complete and bill while failing to project media into your output schema, which degraded names, so do not treat status: OK alone as usable output.

Replaying the same Idempotency-Key returns the original receipt with idempotency_hit: true, so a step that Kiro retries does not start a second run. Reusing the key with a different payload returns 409 idempotency_conflict. Verify the signature before acting on a webhook; the scheme is the same as for job webhooks, with x-sume-webhook-signature and a timestamp header. For the Cursor equivalent, see the scheduled run API post.

Failure modes to plan for

Three things go wrong with an unattended handoff. The first is a refused request: a missing spend cap returns 400 invalid_request, an older key returns 403 insufficient_scope, and an assistant turn in messages[] is rejected. These are caught at create time, so the workflow step should treat any non-202 as a failed step with the error code in the message.

The second is a lost webhook. Sume retries a failed delivery up to ten attempts, and Redeliver re-sends a stored delivery, but if your endpoint is down for the whole window you still have status_url and result_url, which remain supported as a backup. Build the step so it can fall back to polling once after a timeout.

The third is a duplicate. Sume dedupes by Idempotency-Key, and the webhook's request_id equals run_id and is stable across retries, so use it to ignore a delivery you have already processed. Pick a key that names the step and the input, so two different steps never collide, and two retries of the same step always do.

When to use a Format or a schedule instead

Agent Completions fit when the task changes each time. If the same packaged workflow runs with different inputs, Sume's docs point to a Format run, and if you need a cron schedule, to a saved schedule. Both return the same receipt shape and fire the same kind of terminal webhook, so your workflow step can treat them alike and switch later without rewriting the receiver.

Choose by who owns the instruction. A completion carries it in every request, so it is visible in your workflow definition. A Format or schedule stores it on Sume's side, so changing it is a dashboard edit rather than a code change. Pick the one that matches how often the instruction changes and who needs to change it.