feat(agents): AI Gateway dynamic routes in createAI

[mattzcarey]

createAI now takes AI Gateway dynamic routes as ai("dynamic/<route>"), in both agents/models/ai-sdk and agents/models/pi-ai. The route runs on env.AI.run under the configured gateway, and it can also be a fallback leg, per model or per call.

const ai = createAI({ binding: env.AI, id: "prod" });
await generateText({ model: ai("dynamic/support"), prompt: "Hi" });
ai("@cf/zai-org/glm-4.7-flash", { fallback: ["dynamic/support"] });

workers-ai-provider supports dynamic routes, and createAI rejected anything that wasn't @cf/ (#2569, cloudflare/ai#675).

• The gateway serves dynamic/ ids from /run (DynamicRoutesModel). It accepts OpenAI chat-completions input with no model, passes streams through, and answers a non-streaming call in chat-completions shape. That's what the existing Workers AI language model sends and reads, so a route reuses it. The id isn't @cf/, so it gets the strict-OpenAI request profile: chatTemplateKwargs is dropped with a warning, because the route may not land on Workers AI.
• A route is a language model only. ai.embedding and the other modality methods still accept only @cf/ legs, including per-call legs from providerOptions.cloudflare, and a dynamic/ leg there gets an error that says so.
• DynamicRouteId, isDynamicRouteId and isRunPathLanguageModelId live in core/catalog.ts, so both frameworks share one gate.

pnpm run check and the model tests (src/tests/models) pass.

[changeset-bot]

🦋 Changeset detected

Latest commit: fe09d29

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

This PR includes changesets to release 2 packages

Name	Type
agents	Patch
@cloudflare/agent-think	Patch

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

[devin-ai-integration]

Devin Review found 2 potential issues.

[devin-ai-integration]

🔍 Dynamic routes need explicit registry registration

ai("dynamic/support") works directly, but ai.provider does not list arbitrary routes. Sessions that resolve { provider, modelId } through Models need the route registered separately.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[devin-ai-integration]

🔍 Pi-ai fallback route remains untested

The direct-call test does not cover legModel, which rebuilds route fallback legs and inherits gateway options. A failed-primary test would cover that path.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[agent-think]

🟡 agents import sizes: 2 entry points grew

	Entry point	Exports	Largest gzip change	Size now
🟡	agents/mcp	15 resized	up to +1.9 KiB (+0.49%)	398.8 KiB
🟡	agents	2 resized	up to +1 KiB (+0.38%)	266.2 KiB

Changed exports (17)

	Import	Gzip change	Size now
🟡	agents/mcp#createMcpHandler	+1.9 KiB (+0.49%)	398.8 KiB
🟡	agents/mcp#createLegacyMcpHandler	+1.7 KiB (+0.45%)	384.7 KiB
🟡	agents/mcp#experimental_createMcpHandler	+1.7 KiB (+0.44%)	384.8 KiB
🟡	agents/mcp#ElicitRequestSchema	+1.4 KiB (+0.41%)	350.5 KiB
🟡	agents/mcp#RPC_DO_PREFIX	+1.4 KiB (+0.4%)	350.5 KiB
🟡	agents/mcp#RPCClientTransport	+1.4 KiB (+0.4%)	350.5 KiB
🟡	agents/mcp#normalizeServerId	+1.4 KiB (+0.4%)	350.5 KiB
🟡	agents/mcp#RPCServerTransport	+1.4 KiB (+0.4%)	350.5 KiB
🟡	agents/mcp#DurableObjectEventStore	+1.4 KiB (+0.4%)	350.5 KiB
🟡	agents/mcp#McpAgent	+1.4 KiB (+0.39%)	350.5 KiB
🟡	agents/mcp#MCP_SERVER_ID_MAX_LENGTH	+1.4 KiB (+0.39%)	350.5 KiB
🟡	agents/mcp#getMcpAuthContext	+1.4 KiB (+0.39%)	350.5 KiB
🟡	agents/mcp#StreamableHTTPEdgeClientTransport	+1.4 KiB (+0.39%)	350.6 KiB
🟡	agents/mcp#SSEEdgeClientTransport	+1.3 KiB (+0.38%)	350.6 KiB
🟡	agents/mcp#WorkerTransport	+1.3 KiB (+0.37%)	354.2 KiB
🟡	agents#buildAgentUrl	+1 KiB (+0.38%)	266.2 KiB
🟡	agents#routeSubAgentRequest	+1 KiB (+0.38%)	265.7 KiB

How this works

Each runtime export is bundled on its own, minified, and gzipped. Changes smaller than 100 B, or smaller than 1% and 1 KiB, are ignored. Growth over 10% or 5 KiB is marked 🔴. This report is informational and does not fail CI. The workflow artifact contains every measurement.

_{Compared 46570f53 → fe09d291 · workflow run · reported by agent-think[bot]}

[pkg-pr-new]

Open in StackBlitz

agents

npm i https://pkg.pr.new/agents@2572

@cloudflare/ai-chat

npm i https://pkg.pr.new/@cloudflare/ai-chat@2572

@cloudflare/codemode

npm i https://pkg.pr.new/@cloudflare/codemode@2572

hono-agents

npm i https://pkg.pr.new/hono-agents@2572

@cloudflare/shell

npm i https://pkg.pr.new/@cloudflare/shell@2572

@cloudflare/think

npm i https://pkg.pr.new/@cloudflare/think@2572

@cloudflare/voice

npm i https://pkg.pr.new/@cloudflare/voice@2572

@cloudflare/worker-bundler

npm i https://pkg.pr.new/@cloudflare/worker-bundler@2572

commit: fe09d29