| 1 | ### parallel |
| 2 | run independent tool calls concurrently, or await/cancel background parallel jobs. |
| 3 | |
| 4 | Use only for independent work. Each `tool_calls` item is a normal tool request object using the same `tool_name` and `tool_args` shape as a top-level reply: `{ "tool_name": "...", "tool_args": { ... } }`. |
| 5 | Only `tool_name` and `tool_args` are used; if an item is copied from a full reply object, planning fields like `thoughts` or `headline` are ignored. |
| 6 | Batch all independent calls that are ready now into one `tool_calls` list, even when they use different tools. Do not split by tool type. |
| 7 | |
| 8 | Rules: |
| 9 | - do not use for one simple call, dependent steps, ordered steps, shared mutable state, or state/tool-availability changes that must happen in the parent context |
| 10 | - never nest `parallel` |
| 11 | - Never include `document_query` in `tool_calls`; it is too heavy for parallel workers, so call it sequentially. |
| 12 | - Call `response` only as a top-level tool so it ends the message loop; never wrap it inside `parallel.tool_calls`. |
| 13 | - `call_subordinate` uses the same child lifecycle here as it does top-level; fresh siblings are next-level agents, and each job's `context_id` can be continued later with `reset: false` |
| 14 | - use `wait: false` only when you will collect results later with `job_ids` |
| 15 | - if extras list running or ready parallel jobs, collect them before final synthesis |
| 16 | - `timeout` only limits how long this call waits; running jobs continue and can be awaited again by `job_ids` |
| 17 | |
| 18 | Args: `tool_calls`, `job_ids`, `wait` default `true`, `action` as `start|await|collect|cancel`, `timeout`. |
| 19 | |
| 20 | Start and wait: |
| 21 | ~~~json |
| 22 | { |
| 23 | "tool_name": "parallel", |
| 24 | "tool_args": { |
| 25 | "tool_calls": [ |
| 26 | {"tool_name": "call_subordinate", "tool_args": {"message": "Review option A and return key risks.", "reset": true}}, |
| 27 | {"tool_name": "search_engine", "tool_args": {"query": "official API changelog release notes"}} |
| 28 | ], |
| 29 | "wait": true |
| 30 | } |
| 31 | } |
| 32 | ~~~ |
| 33 | |
| 34 | Collect existing jobs: |
| 35 | ~~~json |
| 36 | {"tool_name": "parallel", "tool_args": {"action": "await", "job_ids": ["job-id"], "timeout": 300}} |
| 37 | ~~~ |