Providers

Use your existing model provider account. Register a provider with a name, adapter type, and credential; an agent's model.provider refers to that name. Cereal sends model requests using the stored credential, and your provider bills your account.

The supported adapter types are anthropic, openai, openai-compatible, and vercel-ai-gateway. An OpenAI-compatible endpoint also needs baseUrl: this is the model provider's endpoint, not the Cereal API URL.

await client.providers.upsert({
  slug: "openrouter",
  name: "OpenRouter",
  type: "openai-compatible",
  baseUrl: "https://openrouter.ai/api/v1",
  secret: process.env.OPENROUTER_API_KEY!
})

Reuse a provider in TypeScript

defineProvider keeps provider configuration beside your agent code. Pass the returned object as model.provider; the agent initializes it on first use. Its serialized agent definition contains the provider slug, without the credential.

import { defineAgent, defineProvider } from "@trycereal/sdk"

export const primary = defineProvider({
  slug: "primary",
  type: "anthropic",
  secret: process.env.ANTHROPIC_API_KEY
})

export const assistant = defineAgent({
  agent: {
    slug: "assistant",
    model: { provider: primary, model: "claude-sonnet-4.6" },
    system: "Help the customer."
  }
})

Call await primary.init() to register it early. The same adapter types and baseUrl settings apply as in client.providers.upsert.

Known hosts

In Settings → Providers, choose a preset to fill in its adapter type and endpoint, then enter your key. You can also register a provider through the API:

Ramp Router's model ids are specific to your key: list them with providers.test({ name }) or in the Router dashboard rather than guessing one.

Model endpoints must be reachable from Cereal over the public internet. Loopback and private-network addresses are not supported.

Custom gateways

For a publicly reachable gateway implementing the OpenAI-compatible protocol:

await client.providers.upsert({
  slug: "acme",
  type: "openai-compatible",
  baseUrl: "https://gateway.example.com/v1",
  secret: process.env.ACME_KEY!
})

For a provider whose authentication or protocol does not match an adapter, use a supported gateway that exposes its models. Check gateway support and model access before registering it.

Checking one

await client.providers.test({ name: "openrouter" })   // reads the catalogue, spends no tokens
await client.providers.models({ name: "vercel" })     // what it publishes, for a picker

test checks access using the provider's catalogue endpoint. models answers with a list for the Vercel AI Gateway and for Anthropic. A native OpenAI provider and any openai-compatible host answer with an empty array, which means "no catalogue Cereal reads, type the model id yourself" rather than an error.

Omitting secret on a later upsert keeps whatever Cereal already stores, so a deploy script can describe a provider without holding its credential.