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.

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:

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

One capability

Route between capabilities

In the Message handling section, select One capability.
Select the Capability that handles every message.
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.

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:

{
  "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:

Open your Product and the A2A Surface that you want to configure.
Open the Orchestration tab.
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

Managed mode

On the Orchestrator Skill card, turn off the switch.
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: configure a Chat Surface
Setting up an A2A Surface: configure Delegate and Managed modes
Adding Capabilities to a Product: connect Flows and Agents to Surfaces
Calling your API endpoints: invoke a selected Capability endpoint