Child runs

A run can start child runs: runs of a capability of the same agent, on the same version. Use them to fan out work (one child per document), or to make independent decisions independent — each child can ask a person on its own, while one run can only have one open hold at a time.

Start a child run

POST {api_url}/v0/capabilities/{capability}/runs
x-agentos-run-token: <context.token>
Idempotency-Key: r_501:split:0

{"input": {"document": "f_9"}, "metadata": {"page": 1}}

It answers 202 {"run_id": "r_502", "parent_run_id": "r_501", "status": "queued"}. The input is checked against the capability’s input schema, as for any run.

The child runs on the parent’s version, with the parent’s caller.
The parent doesn’t wait for it. Follow it, or have the child do its part on its own.
The child has no session, but keeps the parent’s end user (user).
A child can only be started while the invocation is running (401 once it has answered).
The request takes no query parameters (422).

The Idempotency-Key

An Idempotency-Key is required and must be unique per parent run. Derive it from run_id and a stable step name, such as r_501:split:0.

Never derive it from invocation.id. That changes on every resume, so a resumed run would start its children again.

Code before an ask runs again on the resume; with a stable key, the same request returns the child that already exists.

With the SDKs

The SDKs build the key for you from run_id and the key you pass (<run_id>:<key>), so a resumed run gets the same child:

for n, file_id in enumerate(inv.input["files"]):
    inv.start("read_page", {"file_id": file_id}, key=f"split:{n}")

for (const [n, fileId] of inv.input.files.entries()) {
  await inv.start("read_page", { file_id: fileId }, { key: `split:${n}` });
}

Limits

Limit	Value	Error
Depth	5 levels	`409 too_deep`
Children of one run	100	`too_many_children`
Runs in one run tree	1,000	`too_many_runs`

Cancelling

Cancelling a run cancels its unfinished child runs at every depth too — queued, running or held — each with a run.cancelled event saying because: "parent r_N was cancelled". A parent that completes or fails leaves its children running.

In experiments

Child runs started from an experiment run get the same config override and context.eval, and share the item’s temporary memory.

GET STARTED

BUILD AGENTS

SDKS & TOOLS

FRAMEWORK EXAMPLES

PLATFORM

API REFERENCE

Start a child run

The Idempotency-Key

With the SDKs

Limits

Cancelling

In experiments

​Start a child run

​The Idempotency-Key

​With the SDKs

​Limits

​Cancelling

​In experiments

Start a child run

The Idempotency-Key

With the SDKs

Limits

Cancelling

In experiments