Child runs

Split work into runs of your agent’s other capabilities.

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:

Python

for n, file_id in enumerate(inv.input["files"]):
    inv.start("read_page", {"file_id": file_id}, key=f"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.