feat(ai-gateway-provider): add createProviderRouter for native SDK routing

[ryanskidmore]

Summary

• Adds createProviderRouter() to ai-gateway-provider that routes model IDs by prefix to native AI SDK provider instances
• Enables consumers to use provider-specific features (like Anthropic prompt caching) that are lost when using the unified provider, while maintaining a single provider interface
• Exports via @cloudflare/ai-gateway-provider/providers/router

Problem

The unified provider (createUnified()) intercepts all fetch calls and normalizes them through a common interface. This works well for most use cases, but provider-specific features like Anthropic's cache_control fields are not preserved because the unified provider doesn't pass through non-standard fields.

Consumers who need these features currently have to manually instantiate and switch between different native SDK providers, losing the convenience of a single provider.

Solution

createProviderRouter() accepts a configuration mapping model ID prefixes to native AI SDK provider instances and returns a standard AI SDK provider. It:

1. Matches the requested model ID against configured prefixes (longest match wins)
2. Routes to the corresponding native SDK provider (which preserves all provider-specific features)
3. Falls back to a configurable default provider when no prefix matches

import { createProviderRouter, createAnthropic, createOpenAI } from "@cloudflare/ai-gateway-provider/providers";

const provider = createProviderRouter({
  providers: {
    "claude-": createAnthropic({ gateway: { ... } }),
    "gpt-": createOpenAI({ gateway: { ... } }),
  },
  defaultProvider: createOpenAI({ gateway: { ... } }),
});

// Routes to native Anthropic SDK (preserves cache_control, etc.)
const result = await generateText({
  model: provider.languageModel("claude-sonnet-4-20250514"),
  prompt: "Hello",
});

Test Coverage

7 test cases covering:

• Basic prefix routing to correct provider
• Fallback to default provider for unknown models
• Longest prefix match precedence
• Error when no default provider and no match
• textEmbeddingModel() routing
• Empty provider map handling
• Exact prefix matching (no partial word matches needed — model IDs are prefix-matched by design)

[changeset-bot]

🦋 Changeset detected

Latest commit: 3aca672

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
ai-gateway-provider	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[mattzcarey]

/bonk review this

[mattzcarey]

LGTM but gonna let @threepointone to look at it. Where will this be documented?

[pkg-pr-new]

Open in StackBlitz

npx https://pkg.pr.new/cloudflare/ai/ai-gateway-provider@439

npx https://pkg.pr.new/cloudflare/ai/@cloudflare/tanstack-ai@439

npx https://pkg.pr.new/cloudflare/ai/workers-ai-provider@439

commit: 3aca672

[ryanskidmore]

LGTM but gonna let @threepointone to look at it. Where will this be documented?

Where's best to document it?

[mattzcarey]

Where's best to document it?

Maybe here? https://developers.cloudflare.com/ai-gateway/integrations/vercel-ai-sdk/

[threepointone]

need to think about this a little more, I'll come to it early next week.

[ArshVermaGit]

This PR introduces createProviderRouter() to the ai-gateway-provider, enabling routing of model IDs to native AI SDK providers based on prefix matching. This is a thoughtful solution to a real limitation of the unified provider approach, restoring access to provider-specific capabilities (e.g., Anthropic prompt caching) while preserving a single, consistent provider interface.
The design strikes a strong balance between flexibility and usability, particularly for advanced use cases requiring provider-specific features.