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

# Routing

> Control which deployment of an agent receives new conversations, with latest or weighted routing, conversation pinning, and sidecar failure policies.

An agent can have several deployments at once, such as the current release and the one you are rolling out. Routing decides which deployment receives each conversation.

Configure routing in the agent's **Deployment** tab, or through the management API.

## Routing modes

| Mode | New conversations go to | Use it for |
| - | - | - |
| **Latest** | The serving deployment. By default, that is the newest release. | Ordinary releases. |
| **Weighted** | A deployment chosen at random, in proportion to the traffic weights you set. | Canary releases and A/B comparisons. |

In weighted mode, you set a percentage for each deployment. A deployment with a weight of 0 receives no new conversations.

You can mix deployment types freely. Weighted routing can split conversations between a sidecar release and a Lambda release of the same agent.

## Conversations stay pinned

Tilde pins each conversation to the deployment that first handled it. Later messages in that conversation go to the same deployment, even after you change the routing mode or the weights.

This keeps a conversation's behaviour consistent while you roll out a new release. It also means an old release keeps receiving traffic until its conversations end, so keep it running until they drain.

## Which deployments can receive traffic

A deployment is routable only while it is healthy:

* A gateway or sidecar deployment needs at least one connected instance that reports ready. Instances send heartbeats, so Tilde stops routing to a failed instance within seconds.
* A Lambda deployment is routable as soon as you register it.

The **Deployment** tab shows each deployment as **serving** when it is both selected by your routing mode and routable. A new release therefore takes no traffic until its replicas connect and report ready.

Your agent can report its own readiness. Pass a readiness check to the SDK, and Tilde routes work only to instances where it passes.

## Promote and retire deployments

* **Promote** makes a deployment the serving deployment in latest mode. Use it to roll back to an earlier release.
* **Retire** takes a deployment out of service for good. Its token stops authenticating at once.

Tilde refuses a retire that would leave an agent with no serving deployment. In latest mode, register another deployment first. In weighted mode, set the deployment's weight to 0 first.

## Sidecar failure policy

Sidecar agents hold warm conversation state in memory, so you choose what happens when a replica fails mid-conversation.

| Policy | Behaviour |
| - | - |
| **Reassign** | Tilde moves the conversation to another live replica of the same deployment. The interrupted run continues there. |
| **Stop** | Tilde fails the interrupted run in place. Use this when a run must not execute twice. |

With either policy, make your agent's external effects idempotent.