> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.runtype.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.runtype.com/_mcp/server.

# Surface orchestration modes

Orchestration controls how a Surface picks the Capability that handles a request. Chat and
Agent-to-Agent (A2A) Surfaces have orchestration modes. On API and MCP Surfaces, the caller
picks the Capability.

## Choose a mode

A Chat Surface has two modes:

* **One capability**: one Flow or Agent handles every message, with no extra model call.
  This is the default.
* **Route between capabilities**: a lightweight model reads each message and sends it to the
  matching Capability. Use it when several Capabilities cover different topics, such as an
  order-status Agent and an FAQ Flow.

An A2A Surface has two modes:

* **Delegate mode**: the Agent Card lists each visible Capability skill, and the calling Agent
  picks the skill. This is the default.
* **Managed mode**: the Agent Card also lists an orchestrator skill. When a request names no
  skill, Runtype uses the orchestrator to pick one of the visible skills.

Other Surfaces route without these modes:

* An API Surface exposes a separate endpoint for each Capability.
* An MCP Surface exposes each Capability as a tool.
* Messaging Surfaces, such as Slack, Telegram, iMessage, and SMS, use the entry point or the
  only enabled Capability. When a messaging Surface has several enabled Capabilities and no
  entry point, a judgment model chooses one for each conversation. For more information, see
  [Surfaces with several Capabilities](/user-guide/products-surfaces/setting-up-a-slack-surface#surfaces-with-several-capabilities).

## Configure chat routing

The **Orchestration** tab shows the **Message handling** section when the Chat Surface has at
least two Capabilities. An active Chat Surface needs exactly one enabled entry point in both
modes.

To configure routing for a Chat Surface, follow these steps:

1. Open your Product and the Chat Surface that you want to configure.
2. Open the **Orchestration** tab.
3. Configure the mode that you want to use, as described in the following tabs.

#### One capability

1. In the **Message handling** section, select **One capability**.
2. Select the Capability that handles every message.
3. Click **Save**.

If a Capability on the Surface is marked as the entry point, the entry point handles
every message and overrides this selection. The first Capability that you add to a Chat
Surface becomes its entry point. To change the entry point, send a `PUT` request to
`/v1/products/PRODUCT_ID/surfaces/SURFACE_ID/entry-point` with the `capabilityId` of the
new entry point.

#### Route between capabilities

1. In the **Message handling** section, select **Route between capabilities**.
2. Select a **Router Model**. Pick a small, fast model, because routing makes one
   extra model call for each message.
3. Optional: Enter a **Routing Prompt**. For more information, see
   [Write a routing prompt](#write-a-routing-prompt).
4. Select a **Fallback Capability**. The router uses it when the reply matches no
   Capability or the routing call fails. If you select **Use first capability**, the
   first Capability on the Surface is the fallback.
5. Click **Save**.

The router reads only the most recent user message, and it routes each message again. Nothing keeps
a conversation on one Capability, so a short follow-up such as "thanks" can go to the fallback
Capability.

The router picks a Capability from each Surface item's exposed name and description. When an
item has none, the router uses the Capability's own name and description. A Capability with no
description reaches the router as "No description". The **Routable Capabilities** list shows
each item's name and exposed description. Write a distinct description for each item.

The routing call is billed as model usage. If you reach a usage limit, the Surface rejects the
message before it routes it.

### Write a routing prompt

Leave **Routing Prompt** empty to use the default prompt. To start from the default, click
**Use default**. A custom prompt can use the following placeholders:

| Placeholder        | Replaced with                                                     |
| ------------------ | ----------------------------------------------------------------- |
| `{{capabilities}}` | A numbered list of Capabilities, such as `[1] Name: Description`. |
| `{{message}}`      | The text of the most recent user message.                         |
| `{{fallback}}`     | The number of the fallback Capability.                            |

Runtype replaces only the first occurrence of each placeholder, so use each one once.
Your prompt must include `{{message}}`, or the router never sees the user's text. Tell the model
to reply with only the Capability number. The router also accepts a reply that matches a
Capability name. Any other reply sends the message to the fallback Capability.

### Verify routing

When the Surface routes between Capabilities, the streamed chat response includes a `routing`
event that names the Capability that handled the message. Use it to check routing decisions, or to show the selected Capability
in a custom client.

### Configure chat routing with the API

To configure routing without the dashboard, update the Surface's `behavior` with
`PUT /v1/products/PRODUCT_ID/surfaces/SURFACE_ID`. The following table maps each dashboard
control to its field.

| Dashboard control                                    | `behavior` field                                    |
| ---------------------------------------------------- | --------------------------------------------------- |
| **One capability** or **Route between capabilities** | `mode`: `single_orchestrator` or `multi_capability` |
| Capability for **One capability**                    | `orchestratorCapabilityId`                          |
| **Router Model**                                     | `router.model`                                      |
| **Routing Prompt**                                   | `router.prompt`                                     |
| **Fallback Capability**                              | `fallbackCapabilityId`                              |

The following request body switches a Chat Surface to routing between Capabilities:

```json
{
  "behavior": {
    "mode": "multi_capability",
    "router": { "model": "gpt-5-nano" },
    "fallbackCapabilityId": "FALLBACK_CAPABILITY_ID"
  }
}
```

Replace `FALLBACK_CAPABILITY_ID` with the ID of the Capability that handles unmatched messages.

### Configure skill orchestration for an external Agent

When a Chat Surface uses an external A2A Agent, the **Orchestration** tab also shows the
**Skill orchestration** section. The tab appears even when the Surface has only one Capability.
Select one of these options:

* **Agent Default**: use the Agent's own skill coordination mode.
* **Agent Decides**: let the remote Agent decide how to use its skills.
* **Managed**: let Runtype's model call the Agent's skills as tools, together with tools from
  other Capabilities. Select a **Model** and, optionally, enter a **System prompt**.

## Configure A2A skill orchestration

The **Orchestration** tab on an A2A Surface has two cards. The **Skills** card lists the
Capability skills and shows how many skills are on the Agent Card. The **Orchestrator Skill**
card turns Managed mode on or off.

To choose the skills on the Agent Card, follow these steps:

1. Open your Product and the A2A Surface that you want to configure.
2. Open the **Orchestration** tab.
3. On the **Skills** card, turn each skill's switch on or off.

Skill switches apply right away. For an external Agent with several skills, expand the Agent
and turn individual skills on or off. A skill marked **Stale** is no longer offered by the
remote Agent, and you can't turn it on.

To choose the orchestration mode, follow these steps:

#### Delegate mode

1. On the **Orchestrator Skill** card, turn off the switch.
2. Click **Save**.

#### Managed mode

1. On the **Orchestrator Skill** card, turn on the switch.
2. Optional: Change the **Skill name**. The default is `assistant`.
3. Optional: Enter a **Description**.
4. Select a **Model**.
5. Optional: Enter a **System prompt**.
6. Click **Save**.

Managed mode keeps the visible skills on the Agent Card and adds the orchestrator skill. A
caller can still name a visible skill directly. If the orchestrator skill name matches another
skill, Runtype appends `_orchestrator` to it. Keep at least one skill visible, because the
orchestrator has nothing to call without one.

## Troubleshooting

The following table lists common orchestration errors and their fixes.

| Error                                                  | Fix                                                           |
| ------------------------------------------------------ | ------------------------------------------------------------- |
| `Routed chat needs at least one enabled capability`    | Keep at least one Capability enabled on the Surface.          |
| `Active chat needs exactly one enabled entry point`    | Mark one enabled Flow or Agent Capability as the entry point. |
| `Choose another entry point before disabling this one` | Make another Capability the entry point first.                |
| `Choose another entry point before removing this one`  | Make another Capability the entry point first.                |
| `No tools available for the orchestrator` (A2A)        | Turn on at least one skill on the **Skills** card.            |

## Next steps

Continue with one of these guides:

* [Setting up a Chat Surface](/user-guide/products-surfaces/setting-up-a-chat-surface): configure a Chat Surface
* [Setting up an A2A Surface](/user-guide/products-surfaces/setting-up-an-a2a-surface): configure Delegate and Managed modes
* [Adding Capabilities to a Product](/user-guide/products-surfaces/adding-capabilities-to-a-product): connect Flows and Agents to Surfaces
* [Calling your API endpoints](/user-guide/products-surfaces/calling-your-api-endpoints): invoke a selected Capability endpoint