Migrate to AI Gateway Using Your Coding Agent

AI Gateway puts one endpoint and one API key in front of 400+ models, and layers on automatic provider fallbacks, per-request observability, spend limits, and pricing with no token markup. It speaks the AI SDK natively and treats every model as a creator/model string, so it stays provider-neutral: switching providers becomes a one-line string change instead of an integration rewrite.

Rather than make those edits by hand, you hand the job to your coding agent. It reads the whole project, finds every place you call a model, including the background jobs and summary generators that you might overlook, and reroutes each one through AI Gateway without changing what your app does. Your framework, streaming, tool schemas, and response shapes all stay put.

Coverage differs by modality, because AI Gateway exposes some of them only through the AI SDK:

If your app calls video or realtime models from Python, the agent reports it rather than attempting the migration.

1. Open your coding agent in the repository

   Launch your agent (Claude Code, Cursor, Codex CLI, or similar) at the root of the project you want to migrate so it can read and edit every file. Start from a fresh branch with a clean working tree, so the whole migration arrives as a single diff you can review before merging.

2. Authenticate with AI Gateway

   Give the agent a credential so it can validate model IDs and run a verification request. Create a key on the AI Gateway API Keys page, then store it locally:

   .env.local

   AI_GATEWAY_API_KEY=your_ai_gateway_api_key

   The prompt only confirms this variable is present and that it works; it never prints the value.

   Already deploying on Vercel? Skip the key and run vercel env pull to pull an OIDC token that authenticates automatically in both local development and production. If your models fall outside the free tier, add credits or connect your own provider keys with BYOK.

3. Paste the prompt and review the plan

   Drop the prompt into your agent. It runs read-only first: it takes inventory of your model calls and lays out a migration plan before touching anything. Approve the plan, then follow the diff as it works. The agent keeps your framework in place and edits only the model-call boundary. It stops to ask when a call site has no supported path for its language, and it leaves embeddings on their current provider unless you tell it otherwise.

   Agent Prompt

   Migrate this app's AI integrations to **Vercel AI Gateway**. Use the AI Gateway skill for this task. If it is unavailable, run `npx skills add vercel/vercel-plugin --skill ai-gateway`, then find and read its `SKILL.md` before continuing. Do not add the skill as an application dependency. Replace direct providers, gateways, proxies, and hand-written HTTP integrations, including OpenAI, Anthropic, Gemini, Vertex AI, Bedrock, Azure OpenAI, SpaceXAI, Mistral, Cohere, Groq, Together, Fireworks, DeepSeek, and Perplexity, as well as OpenRouter, LiteLLM, Portkey, Cloudflare AI Gateway, Helicone, and custom proxies. ## 1. Inventory first, then stop Do not edit anything yet. Search the repository for AI integration code: `openai`, `@ai-sdk/`, `@anthropic-ai/sdk`, the Google Gen AI SDK package, `generateText`, `streamText`, `generateObject`, `embed`, `embedMany`, `rerank`, `useChat`, `baseURL`, `base_url`, `apiKey`, `api_key`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GOOGLE_API_KEY`, `GEMINI_API_KEY`, `MISTRAL_API_KEY`, `GROQ_API_KEY`, `COHERE_API_KEY`, `OPENROUTER_API_KEY`, `openrouter`, `litellm`, `portkey`, `helicone`, and direct `fetch` calls to model APIs. Include the call sites that you might overlook: title and summary generators, classification, extraction, moderation, autocomplete, command palettes, background jobs, and cron tasks. Do not limit the inventory to obvious `/api/chat/*` routes. For each call site, record the language, SDK, endpoint, model, modality, streaming behavior, tool use, and credential. Then count the blast radius. If components, tests, database rows, or public APIs depend on a protocol such as AI SDK `UIMessage`, tool UI parts, persisted message shapes, or vector dimensions, preserve that protocol and migrate only the model-execution boundary behind it. Present the inventory and a migration plan, then wait for approval before editing. If the run is non-interactive, take the least disruptive path and say in the final report that you proceeded without approval. ## 2. Check credentials before migrating Confirm that `AI_GATEWAY_API_KEY` is present, or that Vercel OIDC is configured. Check for presence only and never print the value. Confirm the credential works before you change any code: ```bash curl -s -H "Authorization: Bearer $AI_GATEWAY_API_KEY" https://ai-gateway.vercel.sh/v1/models ``` If that fails, stop and tell the user. Never expose credentials in browser code. ## 3. Route each call site Keep the format the app already speaks. Migrating a format to itself is the smallest possible change: the base URL, the API key, and the model ID. Request and response shapes stay identical, so streaming, tool schemas, and response parsing do not move. | Current integration | Migrate to | Base URL | | --- | --- | --- | | OpenAI Chat Completions | Chat Completions | `https://ai-gateway.vercel.sh/v1` | | OpenAI Responses | Responses | `https://ai-gateway.vercel.sh/v1` | | OpenResponses | OpenResponses | `https://ai-gateway.vercel.sh/v1` | | Anthropic Messages | Messages | `https://ai-gateway.vercel.sh` | | Cohere Rerank | Cohere Rerank | `https://ai-gateway.vercel.sh` | | AI SDK without AI Gateway | AI SDK with AI Gateway | model IDs become `creator/model` | In every case the model ID becomes a `creator/model` slug and the credential becomes `AI_GATEWAY_API_KEY`. The Anthropic Messages surface also accepts the key in `x-api-key`, so the Anthropic SDK's own auth convention keeps working. The wire format is independent of which provider serves the request. AI Gateway maps parameters across formats, so an Anthropic-format request can be served by an OpenAI model and the reverse. Never rewrite a working integration into a different format to reach a different model. Change format only when the app needs a capability its current surface does not expose: embeddings and image generation are only on the OpenAI-compatible Chat Completions surface (including its `/v1/embeddings` and `/v1/images/generations` endpoints), and reranking is on the Cohere surface only. Support also differs by modality. Do not assume an OpenAI-compatible base URL works for everything. | Modality | Supported paths | | --- | --- | | Text, tools, structured output | AI SDK `creator/model` IDs; `https://ai-gateway.vercel.sh/v1` for `/v1/chat/completions` and `/v1/responses`; `https://ai-gateway.vercel.sh` for `/v1/messages` | | Image | AI SDK; `/v1/chat/completions` for multimodal models; `/v1/images/generations` for image-only models | | Reranking | AI SDK `rerank`, or `/v1/rerank` and `/v2/rerank`. Not available on the OpenAI-compatible or Anthropic surfaces. | | Text to speech | AI SDK `experimental_generateSpeech`, or POST `/v4/ai/speech-model` with an `ai-model-id` header | | Speech to text | AI SDK `experimental_transcribe`, or POST `/v4/ai/transcription-model` with an `ai-model-id` header | | Video | AI SDK `experimental_generateVideo` only. Requires AI SDK 6 or later. TypeScript only. | | Realtime | AI SDK `gateway.experimental_realtime` only. TypeScript only. | | Embeddings | See step 4 | If a call site has no supported path for its modality and language, such as video or realtime from Python, stop and report it. Do not force it through a different endpoint. Treat `experimental_` APIs as unstable and say so in your report when you use one. ## 4. Leave embeddings alone unless asked Changing an embedding model changes the vector space, and often the dimension count. An existing index keeps returning results that are silently wrong, and no test catches it. Leave embedding calls on their current provider and list them in your report. Migrate them only if the user explicitly asks and you have a reindexing plan. Apply the same caution to anything else with a persisted data contract, including vector columns, completions cached by model ID, and stored tool schemas. ## 5. Resolve model IDs against the catalog Fetch the catalog. Unlike `/v1/models`, it maps every gateway slug to the provider-native names it is served under, which is what makes translation possible: ```bash curl -s https://ai-gateway.vercel.sh/v1/models/catalog ``` Each entry is `{ slug, providers: [{ provider, providerModelId }] }`. Resolve every model string the app uses today, in this order: 1. If the string is already an exact `slug`, keep it. Model strings from OpenRouter and other `creator/model` gateways usually match directly, so treat the catalog as a validity check rather than a translation. 2. Otherwise match it case-insensitively against `providerModelId` and take that entry's `slug`. Casing is inconsistent in the data, so `Qwen/Qwen3-14B` and `qwen/qwen3-14b` both need to resolve. 3. If more than one slug matches, prefer the unsuffixed one. A `-fast` slug is Fast Mode: the same model on a faster serving path at a higher per-token cost, equivalent to setting `providerOptions.gateway.speed: 'fast'` on the base slug. Both slugs therefore share a `providerModelId`, which is why the lookup returns two. Fast Mode is a deliberate opt-in, so migrate to the base slug and mention Fast Mode in your report instead of changing tiers on the app's behalf. A provider model ID can match more than one distinct catalog entry. If filtering by provider still leaves multiple candidates, stop and ask which one is intended. Do not assume that a newer version is an equivalent replacement. Do not extrapolate variants by analogy. If a model in use has no entry at all, stop and ask rather than substituting one. ## 6. Make the changes Preserve existing behavior, including streaming, tool calls, schemas, reasoning, multimodal inputs, retries, error handling, fallbacks, and provider-specific options. Update environment examples and documentation, then remove provider dependencies that are no longer used. ## 7. Verify * Add a no-network test proving the base URL, auth variable, model slug, tool definitions, and streaming are wired correctly. It has to run under the project's existing test setup. * Run the project's formatter, linter, type check, tests, and production build. * Search again for stale provider keys, base URLs, model IDs, and imports left behind. * Exercise one real route per modality you migrated. ## 8. Report 1. Call sites migrated, grouped by modality 2. Models and endpoints changed 3. Files and dependencies changed 4. Environment or Vercel configuration required 5. Verification results 6. Anything left on its original provider, and why Do the migration now. Do not stop after giving advice.

   Show more

4. Verify the migration

   When the agent finishes, confirm your app behaves exactly as before, both in the code and in your Vercel dashboard.

   Exercise the real paths:

   • Trigger a streaming response, a tool call, and a structured-output request, and confirm each one still completes end to end.
   • Run the project's own gates: formatting, linting, type checking, tests, and a production build.

   Confirm the wiring:

   • Traffic now reaches https://ai-gateway.vercel.sh and authenticates with AI_GATEWAY_API_KEY or your OIDC token.
   • Every model reference uses the creator/model slug form and resolves against the model catalog.

   Watch it live:

   • Open AI Gateway in your Vercel dashboard and confirm each request appears with its model, latency, token usage, and cost. See Observability and spend for what the views cover.
   • Set a spend limit so an unexpected loop can't run up a bill, and confirm any provider fallbacks trigger in the order you configured.

AI coding agents are transforming how developers write, debug, and refactor code. Route these agents through AI Gateway to get a single dashboard for spend tracking, access to any model, and automatic fallbacks, all while using the familiar interfaces of your favorite tools.

See Coding agents to set it up.

• Compare model pricing and capabilities in the model catalog.
• Add provider fallbacks so a single provider outage doesn't take your app down.
• Set spend limits and budgets before you send production traffic.