Swap providers without rewriting the agent

Provider choice should be configuration, not application architecture. This recipe keeps the task, runtime, and result handling unchanged while the adapter boundary moves between six hosted and local providers.

#Install

npm install @agentskit/adapters @agentskit/core @agentskit/runtime tsx

#Copy the verified fixture

The complete runnable source is committed at apps/docs-next/fixtures/provider-swap/agent.ts.

The application path has no provider-specific branch:

const adapter = selectAdapter(provider)
const result = await runTask(adapter, 'Explain why provider portability matters')

Only selectAdapter knows which provider factory, credential, and default model to use.

#Provider compatibility

Set AGENT_MODEL to override any default. Set OLLAMA_BASE_URL when Ollama is not listening at http://localhost:11434. For streaming, tools, multimodal, reasoning, usage, and self-hosting details, use the canonical adapter compatibility matrix.

#Run without credentials

The fixture defaults to a deterministic demo adapter so you can verify installation and the runtime path without network access:

npx tsx agent.ts

Expected prefix:

[demo] Demo model received:

#Switch providers

Hosted providers require only their documented environment variable:

OPENAI_API_KEY=your-key AGENT_PROVIDER=openai npx tsx agent.ts
ANTHROPIC_API_KEY=your-key AGENT_PROVIDER=anthropic npx tsx agent.ts
GOOGLE_API_KEY=your-key AGENT_PROVIDER=gemini npx tsx agent.ts
OPENROUTER_API_KEY=your-key AGENT_PROVIDER=openrouter npx tsx agent.ts
GROQ_API_KEY=your-key AGENT_PROVIDER=groq npx tsx agent.ts

For local Ollama:

ollama pull llama3.2
AGENT_PROVIDER=ollama npx tsx agent.ts

The task, runtime construction, and result handling remain identical for every command.

#What the automated proof covers

• all six adapters execute the same runTask function;
• provider-native SSE or NDJSON is parsed through a deterministic HTTP mock, with no live API call;
• hosted credentials are validated before transport work;
• Ollama needs no API key and accepts model/base URL overrides;
• OpenRouter uses the explicit openrouter/free model;
• unknown provider names fail before adapter construction;
• the credential-free demo remains executable in CI.

Live calls remain optional because provider availability, accounts, rate limits, and local model installation are external state. Tests never inspect or print credential values.

#See also

• Choosing an adapter
• More provider adapters
• Fallback chain
• Adapter router