Switchback

Per-turn cascade model router for AI agents. Starts cheap, climbs the tiers when the cheap one fumbles.

Don't want to wire it yourself? Switchback ships fully hosted inside VibeKit — every "Auto" turn runs through this cascade with brand-locked ladders, telemetry, and billing built in. Or hit the hosted classifier directly: POST https://vibekit.bot/api/v1/switchback/route.

Most AI agents pick one model per app and use it for every turn. A "fix this typo" turn and a "refactor the auth flow" turn both go to the same flagship — wasted spend on the trivial half, no escalation safety on the complex half.

Switchback classifies each user turn (trivial / standard / complex), starts the agent on the cheapest model in your ladder that can plausibly handle it, then escalates mid-turn — swapping to a more capable model on the next agent round — if it detects the cheap one is fumbling.

Born inside VibeKit. Extracted as a standalone library because the routing pattern is useful well beyond one product.

Install

npm install vibekit-switchback

Quick start

import {
  createCascade,
  createOpenRouterClassifier,
} from 'vibekit-switchback';

const cascade = createCascade({
  // Cheap → flagship. Brand-locked is your call: if your user has an
  // Anthropic key, hand Switchback an all-Anthropic ladder; if they're
  // on OpenAI, an all-OpenAI ladder. Switchback stays inside whatever
  // ladder you give it.
  ladder: [
    'openai/gpt-5.4-mini',
    'openai/gpt-5.4',
    'openai/gpt-5.5',
  ],
  classify: createOpenRouterClassifier({
    apiKey: process.env.OPENROUTER_API_KEY!,
  }),
});

const state = await cascade.init({
  userMessage: 'add a dark-mode toggle to the header',
  recentHistory: [], // optional: last 1-2 assistant turns for context
});

// state.initialModel === 'openai/gpt-5.4' (classifier picked tier 1)
// state.classifier.why === 'small UI feature'

// Run your agent's first round with state.initialModel:
const round0 = await runAgentRound({ model: state.initialModel, ... });
cascade.recordTokens(state, round0.totalTokens);

// After each round, check for escalation:
const decision = cascade.evaluate(state, {
  hasNoText: round0.text.trim() === '',
  endedOnToolUse: round0.endedOnToolUse,
  steps: round0.steps,           // optional — enables tool_error_spike trigger
  joinedText: round0.text,       // optional — enables refusal_signal trigger
}, /* round = */ 0);

if (decision.escalate) {
  const nextModel = cascade.escalate(state, decision.reason!, 0, round0.totalTokens);
  // ...use nextModel for the next round
}

// At end-of-turn, persist telemetry:
const telemetry = cascade.telemetry(state);
//  { initial_model, final_model, escalations, signals[], per_tier_tokens }

What makes Switchback different

• Mid-turn escalation. Other routers (NotDiamond, Martian) pick a model at request start and that's that. Switchback can hand off mid-conversation if the cheap tier gives up — requires deep agent-loop integration but catches failures other routers can't.
• Brand-locked by design. Switchback doesn't decide "use Claude or GPT" — the caller hands it one ladder per user, all within their BYOK provider. Your user's key stays your user's key, every tier.
• Agent-loop signals. Five escalation triggers built around actual agent execution: empty-tool exits, tool-error spikes, continuation exhaustion, explicit retry-sentinels, refusal phrases. Not just chat-completion patterns.
• Telemetry baked in. Every cascade.telemetry(state) returns a clean JSON record ready to write to your usage_logs / metrics sink. Five columns: initial model, final model, escalation count, signal log, per-tier tokens.

API

createCascade(config)

field	type	description
ladder	readonly string[]	Ordered list of model ids, cheap first.
classify	(userMessage, recentHistory) => Promise<ClassifierResult>	Your classifier function. See below.

Returns: { init, evaluate, escalate, recordTokens, telemetry }.

createOpenRouterClassifier(opts)

Drop-in classifier using OpenRouter. Fail-soft (returns tier 1 on any error so the cascade never blocks on classifier issues).

option	type	default	description
apiKey	string	(required)	OpenRouter API key.
model	string	openai/gpt-5.4-mini	Model slug for classification.
baseUrl	string	https://openrouter.ai/api/v1	Override for OR-compatible proxies.
timeoutMs	number	8000	Per-call timeout.

Escalation triggers (in cascade.evaluate)

trigger	fires when
empty_tool_exit	2 consecutive rounds end on tool_use with no text output.
tool_error_spike	≥3 tool-error entries in this round's steps[].
continuation_exhaust	Round index ≥5 with still no text accumulated.
sentinel_after_retry	Your agent loop hit its empty-response retry and the retry was also empty.
refusal_signal	First ~200 chars of the assistant reply start with "I can't" etc.

Each escalation bumps tier by 1 (capped at ladder top).

When NOT to use this

• You only have one model. Save yourself the classifier latency. Switchback is for cascades.
• You don't run an agent loop. The mid-turn escalation only helps if you have multiple rounds per user turn. For one-shot chat-completion routing, you want NotDiamond / Martian / OpenRouter's auto instead.
• Latency-critical chat. The classifier adds ~200-500ms before the first token of round 0. If your UX needs sub-200ms first-token-latency, skip it.

License

MIT — see LICENSE.

Credits

Built by VibeKit. The approach is heavily inspired by Factory.ai's Factory Router — same thesis, different implementation. Switchback's contributions are the brand-locked ladders, mid-turn escalation, and agent-loop-signal triggers.