---
title: Flue with AI Gateway
product: vercel
url: /docs/ai-gateway/ecosystem/framework-integrations/flue
canonical_url: "https://vercel.com/docs/ai-gateway/ecosystem/framework-integrations/flue"
last_updated: 2018-10-20
type: how-to
prerequisites:
  - /docs/ai-gateway/ecosystem/framework-integrations
  - /docs/ai-gateway/ecosystem
related:
  - /docs/frameworks/agents/flue
  - /docs/accounts
  - /docs/ai-gateway/authentication-and-byok/authentication
  - /docs/environment-variables
  - /docs/ai-gateway/observability-and-spend/observability
summary: Route Flue agent requests through Vercel AI Gateway with the built-in provider, using an API key or Vercel OIDC authentication.
install_vercel_plugin: npx plugins add vercel/vercel-plugin
search_with_vercel_cli: npx vercel@latest docs search "<query>"
---

# Flue with AI Gateway

[Flue](/docs/frameworks/agents/flue) agents can use AI Gateway through the built-in `vercel-ai-gateway` provider. Choose a model with `useModel()` to route requests through AI Gateway and track usage in your Vercel dashboard.


<!-- docsgraph:related -->
## Related pages

> **For AI agents:** Follow these links to understand how this page connects to the rest of the Vercel ecosystem. For the full cross-link map (inbound, outbound, prerequisites, and semantic neighbors), see the .graph.md link below.

- [How to build your own AI model router](https://vercel.com/kb/guide/how-to-build-your-own-ai-model-router) — Build an AI model router with Vercel AI Gateway. Keep routing, key, and retention decisions in your code while the gatew
- [How to route your coding agent spend through AI Gateway](https://vercel.com/kb/guide/route-coding-agent-spend-through-ai-gateway) — Point Claude Code, Codex, Cursor, and every other harness on your machine at AI Gateway with one CLI command, on a budge
- [Build a Software Factory with Flue](https://vercel.com/docs/agent-resources/software-factory/flue) — Use Flue with AI Gateway, Vercel Sandbox, and explicit GitHub tool adapters for investigated and reviewed code changes.
- [Agent Frameworks on Vercel](https://vercel.com/docs/frameworks/agents) — Build AI agents with eve, Mastra, Flue, and Vercel. Learn how each framework connects to Vercel compute, models, and sto
- [Ecosystem](https://vercel.com/docs/sandbox/ecosystem) — Use Vercel Sandbox with the agent frameworks, model SDKs, and agents you already work with.
- [Getting Started with AI Gateway](https://vercel.com/docs/ai-gateway/getting-started) — Set up AI Gateway with a coding agent, route the agent through AI Gateway, or make your first request with cURL, TypeScr
- [Xcode with AI Gateway](https://vercel.com/docs/ai-gateway/ecosystem/framework-integrations/xcode) — Connect Xcode's AI chat to AI Gateway through the Chat Completions API. Configure the provider, API key, and models in X

Full cross-link map for this page: [/docs/ai-gateway/ecosystem/framework-integrations/flue.graph.md](/docs/ai-gateway/ecosystem/framework-integrations/flue.graph.md)
<!-- /docsgraph:related -->

## Prerequisites

Start with an [existing Flue project](/docs/frameworks/agents/flue) with `@flue/runtime` and `@flue/cli` installed, Node.js 22.19 or later, and a [Vercel account](/docs/accounts).

## Configure authentication

Create an [AI Gateway API key](/docs/ai-gateway/authentication-and-byok/authentication) and add it to `.env.local`:

```bash filename=".env.local"
AI_GATEWAY_API_KEY=your-api-key-here
```

For deployed applications, set `AI_GATEWAY_API_KEY` in your project's [environment variables](/docs/environment-variables). To authenticate with a Vercel OpenID Connect (OIDC) token instead, use the [OIDC configuration below](#use-vercel-oidc-authentication).

## Configure your agent

Create or update your agent module:

**src/agents/assistant.ts**

```ts filename="src/agents/assistant.ts" framework=all
'use agent';

import { useModel } from '@flue/runtime';

export function Assistant() {
  useModel('vercel-ai-gateway/openai/gpt-6.1-sol');
  return 'Answer questions clearly and concisely.';
}
```

**src/agents/assistant.js**

```js filename="src/agents/assistant.js" framework=all
'use agent';

import { useModel } from '@flue/runtime';

export function Assistant() {
  useModel('vercel-ai-gateway/openai/gpt-6.1-sol');
  return 'Answer questions clearly and concisely.';
}
```

The first part of the model specifier, `vercel-ai-gateway`, selects Flue's provider. The remaining `openai/gpt-6.1-sol` is the AI Gateway model ID. To use another model, choose one from the provider's model catalog.

Flue includes all built-in providers by default. If your Flue configuration has a `providers` list, include `'vercel-ai-gateway'` in that list for server builds. See [Flue's provider configuration](https://flueframework.com/docs/reference/provider-api/#the-providers-config).

## Run your agent

Load `.env.local` and send a prompt with the Flue CLI:

```bash filename="terminal"
pnpm exec flue run src/agents/assistant.ts --env .env.local --message "Explain AI Gateway in one sentence."
```

For the JavaScript example, use `src/agents/assistant.js`. After the response, check your request in [AI Gateway observability](/docs/ai-gateway/observability-and-spend/observability).

## Use Vercel OIDC authentication

Flue's built-in AI Gateway provider reads `AI_GATEWAY_API_KEY`. To use a Vercel OIDC token, register a provider with a request-time authentication resolver. This sends the token in the `Authorization` header to AI Gateway's [Anthropic-compatible Messages API](/docs/ai-gateway/sdks-and-apis/anthropic-messages-api).

Install the provider and OIDC packages:

**pnpm**

```bash
pnpm i @earendil-works/pi-ai @vercel/oidc
```

**yarn**

```bash
yarn add @earendil-works/pi-ai @vercel/oidc
```

**npm**

```bash
npm i @earendil-works/pi-ai @vercel/oidc
```

**bun**

```bash
bun add @earendil-works/pi-ai @vercel/oidc
```

For local development, link your project and pull a token:

```bash filename="terminal"
vercel link
vercel env pull .env.local
```

Replace the agent module with the following configuration. Keep the registration in the agent module so it also applies to `flue run`, which doesn't load `app.ts`:

**src/agents/assistant.ts**

```ts filename="src/agents/assistant.ts" framework=all
'use agent';

import { createProvider } from '@earendil-works/pi-ai';
import { anthropicMessagesApi } from '@earendil-works/pi-ai/api/anthropic-messages.lazy';
import { vercelAIGatewayProvider } from '@earendil-works/pi-ai/providers/vercel-ai-gateway';
import { setProvider, useModel } from '@flue/runtime';
import { getVercelOidcToken } from '@vercel/oidc';

setProvider(
  createProvider({
    id: 'vercel-ai-gateway',
    baseUrl: 'https://ai-gateway.vercel.sh',
    models: vercelAIGatewayProvider().getModels(),
    api: anthropicMessagesApi(),
    auth: {
      apiKey: {
        name: 'Vercel OIDC',
        resolve: async () => ({
          auth: {
            headers: {
              Authorization: `Bearer ${await getVercelOidcToken()}`,
            },
          },
        }),
      },
    },
  }),
);

export function Assistant() {
  useModel('vercel-ai-gateway/openai/gpt-6.1-sol');
  return 'Answer questions clearly and concisely.';
}
```

**src/agents/assistant.js**

```js filename="src/agents/assistant.js" framework=all
'use agent';

import { createProvider } from '@earendil-works/pi-ai';
import { anthropicMessagesApi } from '@earendil-works/pi-ai/api/anthropic-messages.lazy';
import { vercelAIGatewayProvider } from '@earendil-works/pi-ai/providers/vercel-ai-gateway';
import { setProvider, useModel } from '@flue/runtime';
import { getVercelOidcToken } from '@vercel/oidc';

setProvider(
  createProvider({
    id: 'vercel-ai-gateway',
    baseUrl: 'https://ai-gateway.vercel.sh',
    models: vercelAIGatewayProvider().getModels(),
    api: anthropicMessagesApi(),
    auth: {
      apiKey: {
        name: 'Vercel OIDC',
        resolve: async () => ({
          auth: {
            headers: {
              Authorization: `Bearer ${await getVercelOidcToken()}`,
            },
          },
        }),
      },
    },
  }),
);

export function Assistant() {
  useModel('vercel-ai-gateway/openai/gpt-6.1-sol');
  return 'Answer questions clearly and concisely.';
}
```

The registration replaces the built-in provider's authentication for chat requests while retaining its model catalog. It uses OIDC even if `AI_GATEWAY_API_KEY` is set. `getVercelOidcToken()` resolves the current token when authentication runs, rather than capturing it when the module loads.

On Vercel, your deployment supplies the [OIDC token](/docs/oidc). For local development, rerun `vercel env pull .env.local` when the token expires. See [AI Gateway OIDC authentication](/docs/ai-gateway/authentication-and-byok/oidc) for details. Run the agent with the same CLI command above.

## Run agent commands in Vercel Sandbox

To give your agent isolated file and command tools, follow [Flue with Vercel Sandbox](/docs/sandbox/ecosystem/flue). Model requests continue to use AI Gateway from your application process.

## Prepare your agent for launch

Before you launch your Flue agent, work through the [agent checklist](/docs/agent-checklist?framework=flue). It lists the AI Gateway settings to check, such as budgets, spend alerts, and model fallbacks. Its Flue items include route authentication and conversation storage.

## Frequently asked questions

### How does Flue send model requests through AI Gateway?

Flue includes a built-in `vercel-ai-gateway` provider. When you call `useModel('vercel-ai-gateway/openai/gpt-6.1-sol')`, Flue splits the specifier at the first `/`. The `vercel-ai-gateway` part selects the provider, and `openai/gpt-6.1-sol` is the AI Gateway model ID. The provider reads `AI_GATEWAY_API_KEY`, so you don't need separate OpenAI or Anthropic keys. To switch models, change the model ID in `useModel()`.

### Can Flue authenticate to AI Gateway with Vercel OIDC instead of an API key?

Yes, but the built-in provider only reads `AI_GATEWAY_API_KEY`. To use OIDC, register a replacement `vercel-ai-gateway` provider with `setProvider()` that resolves a token from `getVercelOidcToken()` on each request, as shown in [Use Vercel OIDC authentication](#use-vercel-oidc-authentication). The replacement uses OIDC even when `AI_GATEWAY_API_KEY` is set. Register it in the agent module, because `flue run` doesn't load `app.ts`.

### Why does a vercel-ai-gateway model work with flue run but fail in my server build?

Check the `providers` list in your Flue configuration. When you set that list, Flue registers only the providers it names in server builds, so a `vercel-ai-gateway/...` specifier fails at model resolution if the list omits `'vercel-ai-gateway'`. `flue run` ignores the list and always registers every built-in provider, which hides the problem locally. Add `'vercel-ai-gateway'` to the list, or remove the list to include all built-in providers.

### How do I track the usage and cost of my Flue agent's model requests?

Open [AI Gateway observability](/docs/ai-gateway/observability-and-spend/observability) in your Vercel dashboard. Each request your Flue agent sends through AI Gateway appears there, with usage, spend, and a request log at team and project level. To bill requests to your own provider accounts, add your credentials at the team level with [Bring Your Own Key (BYOK)](/docs/ai-gateway/authentication-and-byok/byok).

### Which other Vercel products can a Flue agent use?

AI Gateway handles model requests wherever you host the Flue runtime. You can also use these Vercel products:

- [Vercel Sandbox](/docs/sandbox) runs the agent's file and command tools in an isolated microVM, and [Vercel Drives](/docs/sandbox/concepts/drives) keep workspace files across runs.
- [Vercel Blob](/docs/vercel-blob) stores completed responses and other artifacts.
- [Vercel Workflows](/docs/workflows) coordinate a hosted Flue agent with other application steps.
- [Vercel Passport](/docs/passport) forwards a verified visitor identity from your Vercel app to your Flue service.
- [Vercel Connect](/docs/connect) provides credentials for third-party services.
- [Vercel Functions](/docs/functions) run the application that calls your agent. Flue's durable runtime needs a host where one process owns each conversation, so see [Flue with Vercel](/docs/frameworks/agents/flue#hosting-considerations) before you choose where to run it.

## Search the docs from your terminal

Search the Vercel docs and read pages as Markdown with the Vercel CLI. No login required.

```bash
# Find docs pages by keyword
npx vercel@latest docs search "environment variables"
npx vercel@latest docs search "function timeout"

# Print a docs page as Markdown, by path or URL
npx vercel@latest docs inspect <page>
```

---

[View full sitemap](/docs/sitemap)


If you encounter incorrect information, can’t find what you need, need a capability Vercel doesn’t currently offer, or have any other feedback to report, please do it by following the instructions at https://vercel.com/feedback.md.
