Defining chains

A chain is the model configuration an agent uses for each turn. A single-tier chain is valid; add more tiers when you want another configured model to handle a failure.

Declare the order

Keep the chain beside the agent, in src/agents/assistant/assistant.chain.ts. This helper accepts adapters you configure in your application's composition root:

import { defineChain, type ModelAdapter } from "@keel-dev/core";

export function assistantChain(
  primary: ModelAdapter,
  fallback: ModelAdapter,
) {
  return defineChain({
    id: "assistant-chain",
    tiers: [primary, fallback],
  });
}

The tiers can use different providers. Each should be suitable for the same agent's job; fallback preserves the request interface, not identical model quality or behavior.

Connect it to an agent

Pass the returned chain to defineAgent with the rest of your agent's configuration:

chain: assistantChain(primary, fallback),

primary and fallback are configured adapters, not provider names. The provider guide shows how to construct them.

Follow selection across a turn

A new turn starts at the first tier. When that tier fails under the retry policy, the chain advances. Later steps in the same turn continue from the selected tier; they do not automatically probe the primary again.

A later turn starts with a fresh chain selection. Provider adapters may also retain short-lived state of their own: after the API refuses a configured model ID, the shipped adapters fail that tier fast for 60 seconds before probing the API again. Fix the configuration error rather than waiting out the re-probe window.

Check configuration early

defineChain rejects an empty tier list, invalid limits, and context allocations that exceed any tier. It also warns when an adapter reports an unconfigured credential, but that warning does not remove the tier or fail chain construction. At execution, an unconfigured shipped provider adapter reports unavailable and the chain falls through.

For an agent declaring tools, defineAgent also requires every tier to support tool calls. A text-only fallback is a configuration error. See Tool capabilities for TypeScript checks and dynamic configuration validation.

The chain window uses the smallest tier window. Output uses the declared context reserve, or the smallest output ceiling when no allocation is supplied. See Limits and usage before adding a smaller fallback.

Inspect in Studio

Run a turn in Studio and inspect MODEL for the tier used. With a deterministic failing tier as the primary (see Custom adapters), verify that the fallback serves subsequent steps. Inspect the chain events for the reason it changed.

Next: Connecting providers.