> For the complete documentation index, see [llms.txt](https://docs.agenticflow.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.agenticflow.ai/reference/nodes/ai_switch.md).

# AI Switch

**Action IDs:** `ai_switch`, `typesafe_ai_switch`, `agenticflow_ai_switch`

## Description

Use a typed decision to select exactly one configured workflow, run that workflow, and continue the parent workflow with its result. AI Switch is useful when the same intake or classification step can lead to different reusable processes.

Only the selected destination runs. The other destinations are reported as skipped and do not run in the background.

## Connections

Select the provider variant shown by the builder. PixelML and TypeSafe variants use workspace connections. `agenticflow_ai_switch` uses built-in AgenticFlow access and does not require a connection.

## Input Parameters

| Name                                                                             | Type                 |        Required        | Description                                                                       |
| -------------------------------------------------------------------------------- | -------------------- | :--------------------: | --------------------------------------------------------------------------------- |
| decision source                                                                  | embedded or existing |           Yes          | Create a decision inside the switch, or use the result of an earlier AI Decision. |
| decision configuration                                                           | object               | For embedded decisions | State and questions used to select a branch.                                      |
| mode                                                                             | selection mode       |           Yes          | `best_match`, `ordered_conditions`, or `score_threshold`.                         |
| branches                                                                         | list                 |           Yes          | The allowed destinations and the rule that selects each one.                      |
| fallback                                                                         | workflow or skip     |           Yes          | What to do when no branch matches or the result is uncertain.                     |
| timeout                                                                          | number               |           No           | Maximum time to wait for the selected child workflow.                             |
| Each branch has an ID, a question ID, and a routing rule. A destination can be a |                      |                        |                                                                                   |
| saved workflow that the current user can access, or an inline sequence when that |                      |                        |                                                                                   |
| option is available in the builder. Branch-specific input and output mappings    |                      |                        |                                                                                   |
| let each child use the fields it needs while the parent keeps a common result.   |                      |                        |                                                                                   |

## Selection Modes

### Best match

Use a Choice question. Map each option ID to one destination. The option with the highest probability is selected, subject to the configured confidence rule.

Example: `billing` → Billing workflow, `technical` → Technical Support workflow.

### Ordered conditions

Use Yes/No questions as ordered rules. The first rule above its threshold wins. This is useful when rules have a deliberate priority order, such as:

1. Escalate regulated requests.
2. Escalate payment disputes.
3. Send all remaining requests to standard support.

Reordering the branches changes the evaluation order.

### Score threshold

Use a Score question and compare the result with the rubric scale configured in the decision. For example, a score of `2` on a `0`–`2` urgency rubric can select an urgent-response workflow.

## Fallbacks

Configure one explicit fallback:

* **Run a workflow**: send the request to a safe review or manual-triage workflow.
* **Skip**: return to the parent without running a child workflow.

Fallbacks are used for a valid no-match or uncertainty result. Provider errors, invalid answers, missing permissions, and timeouts remain errors so they can be seen and handled by the workflow run.

## Output Parameters

| Name                     | Type                   | Description                                            |
| ------------------------ | ---------------------- | ------------------------------------------------------ |
| selected\_branch\_id     | string                 | ID of the branch that was selected.                    |
| child\_workflow\_run\_id | string or null         | Run ID of the selected child workflow.                 |
| status                   | `success` or `skipped` | Whether a child ran or the fallback skipped execution. |
| child\_output            | object                 | Output returned by the selected child workflow.        |
| mapped\_output           | object                 | Common fields mapped from the selected destination.    |
| decision                 | object                 | The typed decision used for routing.                   |
| skipped\_branch\_ids     | array                  | IDs of destinations that were not selected.            |

Example output:

```json
{
  "selected_branch_id": "technical",
  "child_workflow_run_id": "run_123",
  "status": "success",
  "child_output": {
    "reply": "Try resetting the API token and run the request again."
  },
  "mapped_output": {
    "reply": "Try resetting the API token and run the request again."
  },
  "skipped_branch_ids": ["billing", "fallback"]
}
```

## Example: Route a New Document

Build three reusable workflows:

* **Invoice processing**: extract totals, validate the supplier, and save the invoice.
* **Contract review**: extract parties and dates, then create a review task.
* **Document review**: send an unknown document to a human review queue.

Then build the parent workflow:

1. Receive or extract the document text.
2. Add **AI Switch** with an embedded Choice question named `document_type`.
3. Map `invoice` to Invoice processing and `contract` to Contract review.
4. Set Document review as the workflow fallback.
5. Map a common field such as `record_id` from each child output.
6. Continue with a notification or save node after the switch.

The parent waits for the selected child and then exposes its mapped result to the next node.

## Using an Existing AI Decision

If a previous node already made the decision, choose **Existing decision** instead of embedding another one. Reference that earlier AI Decision in the builder. AI Switch then routes using the recorded answer without making a second inference request.

## Limits and behavior

* Configure at least one branch and one explicit fallback.
* The embedded decision supports the same budget fields as [AI Decision](/reference/nodes/ai_decision.md).
* Only one branch executes for a switch run.
* Branch destinations must be accessible to the workflow's workspace and project.
* The parent continues only after the selected child succeeds, or after an explicit Skip fallback.
* A child failure, timeout, or permission error is visible in the run result and does not become a successful fallback decision.
* Use common output mappings when the parent needs the same fields regardless of which branch ran.

## Troubleshooting

| Problem                              | What to check                                                                               |
| ------------------------------------ | ------------------------------------------------------------------------------------------- |
| No branch matches                    | Check the question ID, option IDs, thresholds, and fallback configuration.                  |
| A child workflow cannot be selected  | Confirm that the workflow is saved and that you have access to its project.                 |
| The parent cannot find a child field | Add a common output mapping for every destination.                                          |
| A decision ran twice                 | Use Existing decision and reference the earlier AI Decision instead of embedding a new one. |
| The switch stops with an error       | Open the child run and verify its inputs, permissions, and timeout.                         |