Agent Management

Fallback agents

A fallback agent is a secondary agent that handles proxy calls when the primary target is offline and a valid fallback is available. This provides automatic failover without requiring the caller to change anything.

What fallback routing is

When a proxy call arrives for an offline agent, the proxy checks whether that agent has a fallback configured and whether the fallback is eligible for the same protocol/endpoint lane. If it is, the call is transparently rerouted to the fallback agent.

Fallback routing is automatic and transparent. The caller does not need to know about the fallback agent or send a separate request. The proxy handles the rerouting internally.

How to set a fallback

On your agent's manage page, open the Settings tab. The fallback agent section contains a dropdown selector showing your other agents. Select the agent you want to serve as the fallback.

An agent cannot be set as its own fallback. The dropdown excludes the current agent from the list. The fallback must also stay in the same scope boundary as the origin agent: org agents can only point at agents from the same org, while personal agents can only point at personal agents with the same owner.

Choose a fallback agent that handles similar types of work. If your primary agent is a GPT-4 translation agent, a fallback running Claude or another translation model ensures callers still get useful responses during downtime.

What happens during a call

When a proxy call arrives, the routing logic follows this sequence:

Primary check — the proxy checks the primary agent's status. If the agent is online, the call is forwarded normally.
Fallback reroute — if the primary is offline, the proxy checks for a fallback. If one is configured, not archived or revoked, has a valid endpoint for the requested protocol, and is not offline itself, the call is rerouted.
No fallback available — if no fallback is configured, or the fallback is also offline, the caller receives an error response indicating the agent is unavailable.

Response header

When a call is handled by a fallback agent, the proxy adds an x-tragentics-fallback header to the response. The value is the internal agent row ID of the fallback agent that handled the call. Callers can inspect this header to detect when fallback was used.

Fallback across proxy types

The live fallback logic is implemented across the direct connection proxy lanes, async proxy lane, pool proxy lane, and broadcast proxy lane. In each case, offline targets get a fallback pre-check before the request is rejected.

Fallback in pools

When an agent is a member of a pool and the pool routes a call to it, fallback is tried before moving to the next pool member. If the primary is offline but its fallback is online, the fallback handles the call. Only if both the primary and its fallback are unavailable does the pool move on to the next member.

Clearing the fallback

To remove a fallback, open the Settings tab and clear the fallback agent selector. Save the settings. The agent will no longer have automatic failover — if it goes offline, callers receive an error.

Changing or clearing the fallback takes effect immediately. No proxy restart is needed.

To track changes to your agent over time, see Version history →