Agents and runs

Agent specs, the three ways to use an agent, pauses for people, and how a run ends.

Next release

The runtime operations (sessions, messages, runs and approvals) are defined in the contract and answer 501 not_implemented until the agent runtime ships. The shapes below are final for contract 0.5.0.

Agent specs

An agent is data, not code: a spec stored in Sparq and published in a Release. Required fields are name, version, job, who_can_use, model (a model class) and instructions. Optional fields include:

mode: react (default), deep, research, workflow or loop;
tools and skills: what the agent may call, and know-how loaded only when relevant (a skill never grants a tool);
knowledge: the collections the agent may search;
limits: model calls, tool calls, delegation depth and run time;
approvals: which actions wait for a person;
tests: what a new version must pass before it can be published.

loop mode runs Discover, Plan, Execute, Verify, Iterate, and the verifier is never the agent that did the work.

Three ways to use an agent

Pattern	Calls	You get
Chat panel	`POST /v1/sessions`, then `POST /v1/sessions/{id}/messages`	A stream of events per message
Action button	`POST /v1/runs` with `"wait": true`	One typed result matching the agent's output
Background job	`POST /v1/runs`, then `GET /v1/runs/{id}/stream`	The run's stream, from any process

curl -X POST "$SPARQ_API_URL/v1/runs" \
  -H "Authorization: Bearer $USER_TOKEN" -H "Content-Type: application/json" \
  -d '{ "agent": "ticket-triage", "input": { "ticket_id": "T-1042" }, "wait": true,
        "idempotency_key": "triage-T-1042-1" }'

Send an idempotency_key (8 to 128 characters) with runs and messages so a retried request does not start a second run.

Pauses

A run can stop to ask a question or to request an approval, then resume later, in any process. Writes and destructive actions always wait for a person.

# Answer a question
curl -X POST "$SPARQ_API_URL/v1/runs/$RUN_ID/resume" \
  -H "Authorization: Bearer $USER_TOKEN" -H "Content-Type: application/json" \
  -d '{ "question_id": "'$QUESTION_ID'", "choice": "annual" }'

# Decide an approval: approve, reject, or edit the arguments first
curl -X POST "$SPARQ_API_URL/v1/approvals/$APPROVAL_ID" \
  -H "Authorization: Bearer $USER_TOKEN" -H "Content-Type: application/json" \
  -d '{ "decision": "approve", "comment": "Refund confirmed with the customer" }'

How a run ends

RunStatus is a closed set. queued, running and awaiting_input are in progress; the rest are terminal:

Status	Meaning
`completed`	Finished with an output
`cancelled`	Cancelled by a caller
`limit_hit`	Reached a run limit (model calls, tool calls, depth or time)
`budget_exceeded`	A hard budget stopped it
`tool_unavailable`	A required tool could not be reached
`verify_failed`	The verify step rejected the result
`awaiting_input_expired`	Nobody answered a question or approval in time
`error`	Failed for another reason; the `error` field holds a problem object

Agent specsCopy Anchor Link

Three ways to use an agentCopy Anchor Link

PausesCopy Anchor Link

How a run endsCopy Anchor Link

On this page

Agent specs

Three ways to use an agent

Pauses

How a run ends