Runs API — Submit and Orchestrate Multi-Agent Runs

Submit multi-agent RunSubmitSpec payloads, kick off queued execution, poll per-step progress, retrieve aggregated results, and export knowledge bundles.

The Runs API orchestrates multi-agent workflows through the WattSwarm run queue. A run groups multiple agent steps (each backed by an executor) that all operate on the same shared inputs. Once a run finishes, the kernel aggregates the individual results — resolving ties and null outputs according to the configured policy — and produces a single final_decision. Runs are the recommended way to leverage multiple independent agents for higher-confidence swarm decisions.

---

POST /api/run/submit

Submits a RunSubmitSpec and registers the run in the queue. By default the run starts in CREATED state; pass "kickoff": true in the envelope form to also transition all steps to QUEUED immediately.

POST /api/run/submit

The endpoint accepts the spec either as a bare RunSubmitSpec object or wrapped in an envelope:

{
  "kickoff": true,
  "spec": { ... }
}

run_id · string · required

Stable identifier for this run. Use a UUID or a deterministic slug.

task_type · string

Task type string passed to each executor step. Defaults to "generic.v1".

shared_inputs · object

JSON inputs shared across all agent steps in the run.

agents · object[] · required

List of agent step specifications.

Show agent fields

agent_id · string · required

Unique identifier for this agent within the run.

executor · string · required

Name of the registered executor that will handle this step.

profile · string

Executor profile to use. Defaults to "default".

prompt · string · required

Prompt or instruction string sent to the executor for this step.

weight · number

Relative weight for confidence-weighted aggregation. Defaults to 1.0.

priority · integer

Step scheduling priority. Higher values are dequeued first. Defaults to 0.

retry · object

Retry policy applied to failed steps.

Show retry fields

max_attempts · integer

Maximum execution attempts per step. Defaults to 2.

backoff_ms · integer

Milliseconds to wait between retry attempts. Defaults to 1500.

aggregation · object

Controls how individual step results are combined into a final decision.

Show aggregation fields

mode · string

Aggregation trigger: "all_done" (default) — finalize once all steps complete.

quorum · integer

Minimum number of agreeing results required for a positive decision.

Complete RunSubmitSpec example:

{
  "run_id": "run-2024-demo-001",
  "task_type": "generic.qa.v1",
  "shared_inputs": {
    "question": "What is the capital of France?"
  },
  "agents": [
    {
      "agent_id": "agent-alpha",
      "executor": "local-agent",
      "profile": "default",
      "prompt": "Answer the question concisely with high confidence.",
      "weight": 1.0,
      "priority": 0
    },
    {
      "agent_id": "agent-beta",
      "executor": "local-agent",
      "profile": "detailed",
      "prompt": "Answer the question with supporting evidence.",
      "weight": 1.5,
      "priority": 0
    }
  ],
  "retry": {
    "max_attempts": 2,
    "backoff_ms": 1500
  },
  "aggregation": {
    "mode": "all_done",
    "quorum": 2
  }
}

Example request:

curl -X POST http://127.0.0.1:7788/api/run/submit \
  -H "Content-Type: application/json" \
  -d '{
    "kickoff": true,
    "spec": {
      "run_id": "run-2024-demo-001",
      "task_type": "generic.qa.v1",
      "shared_inputs": { "question": "What is the capital of France?" },
      "agents": [
        { "agent_id": "agent-alpha", "executor": "local-agent", "profile": "default", "prompt": "Answer concisely." }
      ]
    }
  }'

Example response:

{
  "ok": true,
  "run_id": "run-2024-demo-001"
}

---

POST /api/run/kickoff/:run_id

Transitions the run and all its constituent steps from CREATED to QUEUED, making them eligible for executor pickup. Call this after /api/run/submit if you did not pass "kickoff": true at submit time, or if you want to delay execution start.

POST /api/run/kickoff/:run_id

Path parameters:

run_id · string · required

The run identifier returned by /api/run/submit.

Example request:

curl -X POST http://127.0.0.1:7788/api/run/kickoff/run-2024-demo-001

Example response:

{
  "ok": true,
  "run_id": "run-2024-demo-001"
}

---

GET /api/run/watch/:run_id

Polls the current status of a run, including step-level counts broken down by state. Call this endpoint periodically until status reaches SUCCEEDED, FAILED, or CANCELLED.

GET /api/run/watch/:run_id

Path parameters:

run_id · string · required

The run identifier.

Example request:

curl http://127.0.0.1:7788/api/run/watch/run-2024-demo-001

Example response:

{
  "ok": true,
  "watch": {
    "run_id": "run-2024-demo-001",
    "status": "LEASED",
    "task_type": "generic.qa.v1",
    "created_at": 1718000000000,
    "updated_at": 1718000005000,
    "started_at": 1718000001000,
    "finished_at": null,
    "counts": {
      "created": 0,
      "queued": 0,
      "leased": 1,
      "succeeded": 1,
      "failed": 0,
      "retry_wait": 0,
      "cancelled": 0,
      "remote_dispatched": 0
    }
  }
}

Response fields:

watch.run_id · string

The run identifier.

watch.status · string

Overall run status: CREATED, QUEUED, LEASED, SUCCEEDED, FAILED, or CANCELLED.

watch.counts · object

Step-level counts by state. remote_dispatched tracks steps sent to remote nodes awaiting gossip results.

---

GET /api/run/result/:run_id

Returns the aggregated final result of a completed run, including the final decision, final answer, and per-step conclusions.

GET /api/run/result/:run_id

Path parameters:

run_id · string · required

The run identifier.

Example request:

curl http://127.0.0.1:7788/api/run/result/run-2024-demo-001

Example response:

{
  "ok": true,
  "result": {
    "run_id": "run-2024-demo-001",
    "status": "SUCCEEDED",
    "final_decision": "Paris",
    "final_answer": "Paris is the capital of France.",
    "steps": [
      {
        "step_id": "step-agent-alpha-001",
        "agent_id": "agent-alpha",
        "status": "SUCCEEDED",
        "conclusion": "Paris",
        "confidence": 0.98,
        "attempt": 1
      },
      {
        "step_id": "step-agent-beta-001",
        "agent_id": "agent-beta",
        "status": "SUCCEEDED",
        "conclusion": "Paris",
        "confidence": 0.97,
        "attempt": 1
      }
    ],
    "aggregation": {
      "resolution_paths": ["quorum_match"]
    }
  }
}

result.final_decision · string | null

The aggregated decision value. null if the run did not produce a conclusive result.

result.final_answer · string | null

The long-form answer string, if the executor returned one.

result.steps · object[]

Per-step outcome details including conclusion, confidence, and attempt number.

result.aggregation.resolution_paths · string[]

List of resolution strategies that were applied (e.g. "quorum_match", "confidence_weighted", "stochastic").

---

GET /api/run/events/:run_id

Returns the structured event log for a run. Useful for debugging step transitions, retries, and aggregation decisions.

GET /api/run/events/:run_id?limit=50

Path parameters:

run_id · string · required

The run identifier.

Query parameters:

limit · integer

Maximum number of events to return. Defaults to 50; minimum 1.

Example request:

curl "http://127.0.0.1:7788/api/run/events/run-2024-demo-001?limit=20"

Example response:

{
  "ok": true,
  "events": [
    {
      "id": 1,
      "run_id": "run-2024-demo-001",
      "event_type": "run_created",
      "payload": {},
      "created_at": 1718000000000
    },
    {
      "id": 2,
      "run_id": "run-2024-demo-001",
      "event_type": "step_queued",
      "payload": { "step_id": "step-agent-alpha-001", "agent_id": "agent-alpha" },
      "created_at": 1718000001000
    }
  ]
}

---

POST /api/run/cancel/:run_id

Cancels an active run. Any steps in QUEUED or CREATED state are moved to CANCELLED. Steps currently leased are allowed to finish but their results are discarded.

POST /api/run/cancel/:run_id

Path parameters:

run_id · string · required

The run identifier.

Example request:

curl -X POST http://127.0.0.1:7788/api/run/cancel/run-2024-demo-001

Example response:

{
  "ok": true,
  "run_id": "run-2024-demo-001"
}

---

POST /api/run/retry/:run_id

Retries a failed run by re-queuing its failed steps from the beginning. Steps that already succeeded are not re-executed.

POST /api/run/retry/:run_id

Path parameters:

run_id · string · required

The run identifier.

Example request:

curl -X POST http://127.0.0.1:7788/api/run/retry/run-2024-demo-001

Example response:

{
  "ok": true,
  "run_id": "run-2024-demo-001"
}

---

POST /api/knowledge/export

Exports a knowledge bundle from the kernel store. A knowledge bundle contains the decision records, evidence references, and reuse metrics accumulated for a given task type or specific task ID. Provide exactly one of task_type or task_id.

POST /api/knowledge/export

task_type · string

Export all knowledge records associated with this task type string (e.g. "generic.qa.v1"). Mutually exclusive with task_id.

task_id · string

Export knowledge records for a single specific task. Mutually exclusive with task_type.

Example request:

curl -X POST http://127.0.0.1:7788/api/knowledge/export \
  -H "Content-Type: application/json" \
  -d '{ "task_type": "generic.qa.v1" }'

Example response:

{
  "ok": true,
  "knowledge": {
    "task_type": "generic.qa.v1",
    "records": [
      {
        "task_id": "task-demo-001",
        "finalized_at": 1718000010000,
        "decision_value": "Paris",
        "confidence": 0.98,
        "evidence_count": 2,
        "reuse_attempts": 0,
        "reuse_successes": 0
      }
    ]
  }
}

Knowledge bundles are useful for fine-tuning prompts, auditing swarm consensus quality, and bootstrapping new nodes with historical decision context.