skilld
All skills
vercel-labs avatar

/ai-gateway

@8fd4644 official
by Vercel Labsvercel-labs/vercel-plugin295 stars
64

Vercel AI Gateway guidance for setup, model discovery, authentication, routing, fallbacks, BYOK, budgets, spend reporting, observability, compatible APIs, and coding-agent configuration. Use when adding AI Gateway to an app, migrating provider calls, choosing models or providers, debugging gateway requests, or running `vercel ai-gateway` commands.

  • 5 files
  • 49.1 KB
  • Updated last week
  • GitHub

Ask your Agent

Use this Skill: https://skilld.dev/gh/vercel-labs/vercel-plugin/ai-gateway

This session only. Nothing lands on disk.

referencescoding-agents.md

≈1.1k tokens on demand. Your agent reads this file only when SKILL.md points to it.

Coding agents through AI Gateway

Use this reference when routing a coding agent's model traffic through AI Gateway.

Distinguish the two coding-agent workflows

Workflow Meaning
Ask a coding agent to make a Gateway request The agent writes and runs an application or HTTP request. The agent itself can use any model or provider; the request's provider/model is a separate target. Use the first-request guide routed from SKILL.md.
Route a coding agent through Gateway Configure the agent's own inference traffic, model picker, credentials, and spend tracking to use AI Gateway. Continue with this reference.

Do not describe the target model in a one-off Gateway request as "the coding agent." Name the controlling tool separately, such as Codex or Claude Code.

Recommended setup

One CLI command configures supported coding agents. It provisions or reuses an AI Gateway API key, detects installed agents, previews every planned config change, and asks for confirmation before writing:

vercel ai-gateway setup

Check vercel ai-gateway setup --help before documenting flags or agent support; the CLI is the source of truth for the current command shape.

Useful flags from the shipped help:

  • --agent <NAME>: configure one agent; repeatable for a subset.
  • --all: configure every supported agent.
  • --dry-run: print the planned diff without writing.
  • --key <KEY>: reuse an existing AI Gateway key instead of creating one. Do not put a literal key in a saved command or agent transcript; prefer the CLI's interactive or OS credential-store path.
  • --budget <AMOUNT> and --refresh-period <PERIOD>: set a spend limit on a newly created key.
  • --expiration <PERIOD>: expire a newly created key after a fixed period.
  • --apply prompt: emit an agent prompt instead of writing files, for setups handled by another coding agent.

Behavior worth stating to users:

  • On macOS, the key can be stored in Keychain rather than plaintext config.
  • Existing Claude Desktop and Codex Desktop sessions can be copied so history survives the provider switch.
  • Each agent gets the compatibility URL that matches its protocol, not a single generic one.

CLI docs: https://vercel.com/docs/cli/ai-gateway#setup. Coding-agents guide: https://vercel.com/docs/ai-gateway/coding-agents.

When the CLI does not cover an agent

Some agents may support AI Gateway without being configurable by the CLI. Do not infer CLI coverage from provider support or a remembered agent list.

The docs keep a per-agent setup page under https://vercel.com/docs/ai-gateway/coding-agents. Prefer the current page over remembered config keys, and use manual configuration when the current setup command does not cover an agent.

Manual configuration

Point the agent at the coding-agent surface unless it has a dedicated endpoint:

https://ai-gateway.vercel.sh/coding-agent/v1

The generic coding-agent URL forwards to the same /v1 handlers, so authentication, routing, billing, and errors are identical. A client that speaks the Anthropic protocol and appends /v1/messages itself should use https://ai-gateway.vercel.sh/coding-agent without the /v1 suffix.

Dedicated endpoints exist for Claude Code, OpenAI Codex, and Cursor. Use each agent's page for what its endpoint adds; for example, Claude Code:

export ANTHROPIC_BASE_URL="https://ai-gateway.vercel.sh/claude-code"
export ANTHROPIC_API_KEY=""
export ANTHROPIC_AUTH_TOKEN="your-ai-gateway-api-key"
export CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY=1

ANTHROPIC_API_KEY must be empty: a non-empty value is used instead of the gateway token. The discovery variable puts every gateway model in Claude Code's /model picker.

Verify a setup

  1. Run a trivial prompt through the agent.
  2. Confirm the request appears in AI Gateway Logs with the coding-agent authentication and the expected model.
  3. Check that retries, model pickers, and spend tracking work. Coding-agent sessions can generate high token counts; recommend a key budget or expiration when appropriate.

If an agent fails, inspect Logs before rewriting its config: a 401 is authentication, a 402 is credits or budget, and a 429 is a rate limit.

Building an application that uses an agent

This reference covers routing existing coding agents. To build an agent application, read the ai-sdk skill and current ToolLoopAgent docs, or the eve and build-agents skills for a durable agent project. Do not conflate "route my coding agent" with "build my own agent."

Source: SKILL.md on GitHub

Third-party checks

No third-party reports yet.

Provenance

Signed by skilld at 8fd4644. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 11 hours ago.

Activeupdated last week

Capability

Other metadata
summary
Set up and operate Vercel AI Gateway with current models, correct authentication, routing, spend controls, and verification.
metadata
{
  "priority": 7,
  "docs": [
    "https://vercel.com/docs/ai-gateway",
    "https://vercel.com/docs/ai-gateway/getting-started",
    "https://ai-sdk.dev/providers/ai-sdk-providers/ai-gateway"
  ],
  "sitemap": "https://vercel.com/docs/sitemap.md",
  "pathPatterns": [],
  "importPatterns": [
    "ai",
    "@ai-sdk/gateway"
  ],
  "bashPatterns": [
    "\\bvercel\\s+ai-gateway\\b",
    "\\bvercel\\s+env\\s+pull\\b",
    "\\bnpm\\s+(install|i|add)\\s+[^\\n]*@ai-sdk/gateway\\b",
    "\\bpnpm\\s+(install|i|add)\\s+[^\\n]*@ai-sdk/gateway\\b",
    "\\bbun\\s+(install|i|add)\\s+[^\\n]*@ai-sdk/gateway\\b",
    "\\byarn\\s+add\\s+[^\\n]*@ai-sdk/gateway\\b"
  ],
  "promptSignals": {
    "phrases": [
      "ai gateway",
      "vercel ai gateway",
      "ai-gateway",
      "ai-gateway.vercel.sh"
    ],
    "allOf": [
      [
        "model",
        "routing"
      ],
      [
        "provider",
        "failover"
      ],
      [
        "gateway",
        "budget"
      ],
      [
        "gateway",
        "logs"
      ],
      [
        "gateway",
        "oidc"
      ],
      [
        "coding",
        "gateway"
      ]
    ],
    "anyOf": [
      "provider ordering",
      "model fallback",
      "byok",
      "spend tracking",
      "gateway key",
      "credit balance",
      "safety identifier",
      "reasoning effort",
      "tool calling",
      "structured outputs"
    ],
    "noneOf": [
      "cloudflare ai gateway",
      "aws api gateway"
    ],
    "minScore": 6
  }
}
validate
[
  {
    "pattern": "\\bclaude-(sonnet|opus|haiku)-\\d+-\\d+\\b",
    "message": "Claude model version uses a hyphen where the AI Gateway slug uses a dot. Fetch /v1/models and use the returned provider/model ID.",
    "severity": "error"
  },
  {
    "pattern": "gateway\\(['\"][^'\"/]+['\"]\\)",
    "message": "AI Gateway model string is missing its provider prefix. Fetch /v1/models and use a provider/model ID.",
    "severity": "error"
  },
  {
    "pattern": "(OPENAI_API_KEY|ANTHROPIC_API_KEY|GOOGLE_API_KEY)",
    "message": "Provider key detected. AI Gateway request authentication uses AI_GATEWAY_API_KEY or VERCEL_OIDC_TOKEN; provider keys belong only in an intentional BYOK configuration.",
    "severity": "recommended",
    "skipIfFileContains": "[Bb][Yy][Oo][Kk]|providerOptions\\s*:\\s*\\{[^}]*gateway"
  },
  {
    "pattern": "gateway\\s*:\\s*\\{[^}]*cacheControl",
    "message": "AI Gateway does not cache whole responses through cacheControl. Use caching: 'auto' for provider prompt caching and verify the current caching docs.",
    "severity": "error"
  },
  {
    "pattern": "ANTHROPIC_BASE_URL\\s*=\\s*[\"']?https://ai-gateway\\.vercel\\.sh",
    "message": "Claude Code through AI Gateway needs ANTHROPIC_API_KEY set to an empty value and the gateway key in ANTHROPIC_AUTH_TOKEN. A non-empty ANTHROPIC_API_KEY is used instead of the gateway token.",
    "severity": "recommended",
    "skipIfFileContains": "ANTHROPIC_AUTH_TOKEN"
  }
]
chainTo
[
  {
    "pattern": "from\\s+['\"]ai['\"]|require\\(['\"]ai['\"]\\)|\\b(generateText|streamText|ToolLoopAgent)\\b",
    "targetSkill": "ai-sdk",
    "message": "AI SDK code detected. Load the AI SDK skill and read the installed package docs before writing or changing SDK code."
  }
]
retrieval
{
  "aliases": [
    "model router",
    "ai proxy",
    "provider failover",
    "llm gateway",
    "gateway credits"
  ],
  "intents": [
    "add Vercel AI Gateway to an application",
    "route AI models across providers",
    "configure provider or model fallbacks",
    "authenticate AI Gateway requests",
    "track AI model costs and set budgets",
    "debug AI Gateway requests and routing",
    "connect coding agents to AI Gateway",
    "find a model by modality, capability, price, or data retention",
    "check AI Gateway credit balance or generation cost",
    "configure reasoning or extended thinking across providers and API formats",
    "add tool calling or function calling across API formats",
    "get structured JSON output matching a schema",
    "send images or PDFs to a model"
  ],
  "entities": [
    "AI Gateway",
    "AI Gateway Credits",
    "providerOptions.gateway",
    "AI_GATEWAY_API_KEY",
    "VERCEL_OIDC_TOKEN",
    "model routing",
    "provider failover",
    "BYOK",
    "spend reporting",
    "safetyIdentifier",
    "Usage & Billing API"
  ]
}

README badge

README badge for vercel-labs/vercel-plugin/ai-gateway