Choose Provider

Choose Provider

Contract

By the end of this skill the consumer knows:

• Whether auto-detection covers them (the common case) or they need an explicit model argument.
• The exact env var and adapter package for their chosen provider.
• That "bring your own adapter" is supported for providers outside the built-in registry (Ollama, Azure, AWS Bedrock, etc.).
• The Vercel AI Gateway fallback option: no adapter package, one key.

Iron Law: one env var per provider

The server handler resolves strings through a fixed registry (see PROVIDER_ADAPTERS in packages/agentickit/src/server/handler.ts lines 56-71). Each prefix maps to exactly one env var and one adapter package. Auto-detection walks AUTO_DETECT_ORDER (lines 150-160) and stops on the first env var present. Setting multiple direct-provider keys will work, but auto-detect becomes deterministic and non-obvious; the first in priority order wins. Be explicit if the order matters for your case.

Phases

Phase 1: the happy path, let it auto-detect

Set one env var, install the matching adapter, omit model:

// app/api/pilot/route.ts
import { createPilotHandler } from "@hec-ovi/agentickit/server";
export const POST = createPilotHandler({});

Auto-detection walks this order (from AUTO_DETECT_ORDER):

If no key is set, the handler factory throws immediately with a message listing every supported env var (see noProviderConfiguredError() at lines 206-215).

Phase 2: the explicit path, pass a model string

When you want a specific model:

createPilotHandler({ model: "anthropic/claude-sonnet-4-5" });
createPilotHandler({ model: "openrouter/qwen/qwen3-coder:free" });
createPilotHandler({ model: "groq/llama-3.3-70b-versatile" });

Supported prefixes (from SUPPORTED_PROVIDER_PREFIXES, line 29-36): openai, anthropic, groq, openrouter, google, mistral.

The handler resolves in this order:

1. Direct provider key present (OPENAI_API_KEY for openai/*, etc.)
   • the matching @ai-sdk/* adapter installed → direct adapter.
2. No direct key but AI_GATEWAY_API_KEY set → raw string passed to streamText, resolved by the Vercel AI Gateway at call time.
3. Neither → throw at handler creation (lines 581-583) with a message telling the consumer exactly which env var or package is missing.

Phase 3: the Gateway-only path

Set AI_GATEWAY_API_KEY (or run on Vercel with VERCEL_OIDC_TOKEN). Install NO adapter packages. Pass any supported prefix string:

createPilotHandler({ model: "openai/gpt-4o" });

The Gateway handles provider routing and billing. Works for every supported prefix. See Vercel's docs for Gateway setup; agentickit has no Gateway- specific configuration.

Phase 4: the bring-your-own-adapter path

For providers NOT in the built-in list (Ollama, Azure OpenAI, AWS Bedrock, Groq through a different SDK, custom gateways):

import { createOllama } from "ai-sdk-ollama";
const ollama = createOllama();
export const POST = createPilotHandler({ model: ollama("llama3.3") });

Any object that's a valid AI SDK v2 or v3 LanguageModel instance is accepted. It's sniffed via isLanguageModelInstance (lines 380-392), which checks for the specificationVersion + provider + modelId triad every adapter exposes. Prefix validation is skipped for instances.

You can also pass a thunk for lazy / async setup:

createPilotHandler({
  model: async () => {
    const creds = await fetchCreds();
    return customAdapter(creds, "model-x");
  },
});

The thunk runs exactly once at handler creation (lines 710-722).

Phase 5: per-request override from the client

<Pilot model="openai/gpt-4o-mini"> forwards the string into every request's body. The server handler re-validates the prefix against the same allow-list (lines 841-853), so a compromised client cannot inject an arbitrary string. Overrides are only honored when the handler's default model is also a string (lines 854-860); if you passed a LanguageModel instance or thunk server-side, the client override is a 400.

Anti-Patterns

• Installing every adapter "to be safe". Peer deps are optional; shipping all of them bloats the consumer's bundle.
• Hard-coding the API key in the model string. Keys always come from process.env.
• Mixing model on <Pilot> and on createPilotHandler. The client value wins when both are strings; when they disagree, debugging is harder than it needs to be.
• Using model: "auto" as a magic string. It's supported (treated as equivalent to omitting model, lines 788-801) but less clear than just leaving the option out.

Output Format

After the choice is made, report:

• The chosen provider (by name: "OpenRouter", "Groq", etc.).
• The env var the consumer needs to set.
• The adapter package the consumer needs to install (or "none, using the Vercel AI Gateway").
• The model argument in createPilotHandler (or "omitted, using auto-detection").

Tools Used

• Read the consumer's .env.local to see what's already configured.
• Edit app/api/pilot/route.ts to pass the model option.
• Edit package.json / run npm install <adapter> as needed.