> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orcapods.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Orchestration Tools

> Profile-scoped tools for delegation, run monitoring, and DAG plan control.

<Warning>
  Orchestration tools can spawn or control other runs. They are not selected by `@default`; a profile must include `@orchestration` or exact tool names. Operators can remove the tools from the registry with `AGENT_ORC_ORCHESTRATION_TOOLS=off`.
</Warning>

## Enabling

```json theme={null}
{
  "name": "coordinator",
  "runtime": "general",
  "tools": ["@default", "@orchestration"]
}
```

Useful runner environment:

```bash theme={null}
CONDUCTOR_BASE_URL=https://api.orcapods.ai
AGENT_ORC_MAX_DELEGATION_DEPTH=3
# Optional hard disable:
AGENT_ORC_ORCHESTRATION_TOOLS=off
```

The conductor-backed tools return "conductor not reachable" when `CONDUCTOR_BASE_URL` is unset or unavailable.

Before calling `delegate_run` or `submit_workflow_run`, use `list_profiles` and pass a profile name from the response. Profile names are tenant-specific; guessed names such as `default`, `assistant`, or `researcher` can fail with `unknown_profile`.

***

## delegate\_run

Spawns a child run through the conductor.

| Field         | Type    | Required | Description                           |
| ------------- | ------- | -------- | ------------------------------------- |
| `profileName` | string  | Yes      | Target profile                        |
| `prompt`      | string  | Yes      | Child task prompt                     |
| `sessionId`   | string  | No       | Existing child session to reuse       |
| `wait`        | boolean | No       | Poll until terminal status            |
| `timeoutSec`  | integer | No       | Wait timeout, default `60`, max `600` |

Output:

```json theme={null}
{
  "runId": "run-child-abc123",
  "sessionId": "sess-a1b2c3d4-zzyyxxww",
  "status": "pending"
}
```

When `wait` is true, terminal statuses are `ok`, `error`, `cancelled`, or `interrupted`, with `result` populated when available.

***

## get\_run

Fetches run status and event counts.

```json theme={null}
{ "runId": "run-f3a9b72c" }
```

Output:

```json theme={null}
{
  "runId": "run-f3a9b72c",
  "status": "ok",
  "startedAt": "2026-04-25T10:00:00Z",
  "parentRunId": "run-parent",
  "eventCounts": { "assistant": 3, "tool_call": 1, "result": 1 },
  "resultText": "Final answer..."
}
```

***

## stream\_run\_events

Polling variant for run events since a cursor.

| Field    | Type   | Required | Description           |
| -------- | ------ | -------- | --------------------- |
| `runId`  | string | Yes      | Run to inspect        |
| `cursor` | string | No       | Previous `nextCursor` |

Output:

```json theme={null}
{
  "events": [{ "type": "assistant", "message": "..." }],
  "nextCursor": "4"
}
```

***

## cancel\_run

Cancels a child run when the caller's current run is an ancestor in the parent chain.

```json theme={null}
{ "runId": "run-child-abc123" }
```

***

## submit\_workflow\_run

Submits an executable workflow run to the conductor. Submitting a workflow run counts against the same delegation depth cap as `delegate_run`.

```json theme={null}
{
  "userPrompt": "Compare LangGraph and AutoGen",
  "nodes": [
    {
      "id": "research",
      "title": "Research",
      "profile": "researcher",
      "promptTemplate": "Summarize LangGraph."
    },
    {
      "id": "review",
      "title": "Review",
      "profile": "reviewer",
      "promptTemplate": "Review {{research.output}}",
      "dependsOn": ["research"]
    }
  ],
  "autoStart": true
}
```

Output:

```json theme={null}
{ "workflowRunId": "workflow-8b2a9c4f", "status": "pending" }
```

***

## get\_workflow\_run

Returns the full workflow run snapshot.

```json theme={null}
{ "workflowRunId": "workflow-8b2a9c4f" }
```

Workflow run snapshots use numeric enum statuses:

| Workflow run | Value |
| ------------ | ----- |
| pending      | `0`   |
| running      | `1`   |
| paused       | `2`   |
| completed    | `3`   |
| failed       | `4`   |
| cancelled    | `5`   |

Node statuses: `0=pending`, `1=ready`, `2=running`, `3=ok`, `4=error`, `5=skipped`, `6=cancelled`.

***

## wait\_workflow\_run

Polls until the workflow run reaches a terminal status, pauses for repair, or times out.

| Field           | Type    | Required | Description              |
| --------------- | ------- | -------- | ------------------------ |
| `workflowRunId` | string  | Yes      | Workflow run to wait on  |
| `timeoutSec`    | integer | No       | Default `120`, max `300` |

When the workflow run pauses, output includes `repairContext` for the failed node.

***

## repair\_workflow\_run

Applies a repair action to a paused workflow run.

```json theme={null}
{
  "workflowRunId": "workflow-8b2a9c4f",
  "action": {
    "type": "retry_node",
    "nodeId": "research"
  }
}
```

Supported action types are `retry_node`, `replace_node`, `add_dependency`, and `abort`.

***

## cancel\_workflow\_run

Cancels pending and running nodes in a workflow run.

```json theme={null}
{ "workflowRunId": "workflow-8b2a9c4f" }
```

***

## Limits

| Env Var                             | Default | Effect                                                      |
| ----------------------------------- | ------- | ----------------------------------------------------------- |
| `AGENT_ORC_MAX_DELEGATION_DEPTH`    | `3`     | Caps recursive delegation and workflow run submission depth |
| `AGENT_ORC_PLAN_NODE_PARALLELISM`   | `8`     | Max in-flight nodes per workflow run                        |
| `AGENT_ORC_PLAN_GLOBAL_PARALLELISM` | `64`    | Max in-flight workflow nodes process-wide                   |
| `AGENT_ORC_PLAN_NODE_RETRIES`       | `0`     | Transport-error retry budget per node                       |
| `AGENT_ORC_PLAN_MAX_NODES`          | `64`    | Max nodes per workflow run                                  |
| `AGENT_ORC_PLAN_MAX_REPAIRS`        | `5`     | Repair budget before auto-fail                              |