# `Pixir.Tools.RunWorkflow`
[🔗](https://github.com/Ranvier-Technologies/pixir/blob/main/lib/pixir/tools/run_workflow.ex#L1)

Run a deterministic Workflow over supervised Subagents.

# `__tool__`

```elixir
@spec __tool__() :: map()
```

Defines the `run_workflow` tool specification including its name, description, and input JSON schema.

The returned map describes a tool named "run_workflow" and a provider-compatible
parameters schema for workflow inputs. The schema accepts either a concrete `steps`
array (each step requires `id` and `task`), a Skill-backed `template_id` plus
optional `template_args`, or separate `skill` and `template` fields. Optional
workflow-level fields include: `id`, `name`, `max_concurrency`, and `timeout_ms`.
Each concrete step object may include `agent`, `depends_on`, `permission_mode`,
`workspace_mode`, `read_set`, `write_set`, `virtual_commands`, `limits`, and an
optional per-step `timeout_ms`.

Keep shape alternatives in descriptions and runtime validation rather than top-level
JSON Schema composition keywords; the OpenAI Responses API rejects those at the tool
schema root.

# `dry_run`

```elixir
@spec dry_run(map(), map()) :: {:ok, map()} | {:error, any()}
```

Validates and plans a workflow without executing its steps.

Performs a dry-run of the provided workflow arguments and returns a human-readable summary plus the planner's raw workflow result.

## Parameters

  - args: Map representing the workflow specification (steps, optional id/name, concurrency/timeout settings, etc.).
  - context: Execution context used to build planner options (workspace, provider, permission and agent/skill options, depth).

@returns
`{:ok, response}` where `response` is a map containing:
  - `"dry_run" => true`
  - `"output"`: a summary string describing the validation/plan
  - `"workflow"`: the planner's raw result map.
On failure, returns `{:error, reason}` as returned by the workflow planner.

# `execute`

```elixir
@spec execute(map(), map()) :: {:ok, map()} | {:error, term()}
```

Runs a workflow described by `args` under the provided `context` and returns a human-readable summary together with the raw workflow result.

On success returns `{:ok, %{"output" => summary, "workflow" => result}}` where `summary` is a formatted completion string and `result` is the workflow result map. On failure returns `{:error, reason}` propagated from the workflow runner.

---

*Consult [api-reference.md](api-reference.md) for complete listing*