---
title: Build an agent with Vercel and Flue
description: Build and deploy an agent with Flue, Vercel Sandbox, and AI Gateway
url: /kb/guide/build-an-agent-with-vercel-and-flue
canonical_url: "https://vercel.com/kb/guide/build-an-agent-with-vercel-and-flue"
published: 2026-06-17
last_updated: 2026-06-17
authors: Allen Zhou
related:
  - /docs/vercel-sandbox
  - /docs/ai-gateway
  - /docs/vercel-sandbox/sdk-reference
install_vercel_plugin: npx plugins add vercel/vercel-plugin
---
<!-- 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.

- [Coding Agents](https://vercel.com/docs/ai-gateway/coding-agents?from=related) — Configure popular AI coding agents to use the AI Gateway for unified model access and spend monitoring.
- [LangChain](https://vercel.com/docs/sandbox/ecosystem/langchain?from=related) — Give a LangChain agent a tool that executes model-generated code in an isolated Vercel Sandbox, with models served by AI
- [Ship It](https://eve.dev/docs/tutorial/ship-it?from=related) — Part 9 of the Build an Agent tutorial. Put a web dashboard on the agent with useEveAgent, replace placeholderAuth, and d
- [Concepts](https://vercel.com/docs/eve/concepts?from=related) — Learn how eve agents, sessions, channels, tools, skills, connections, and sandboxes fit together.
- [Building an agent with OpenAI Agents SDK and Vercel Sandbox](https://vercel.com/kb/guide/building-an-agent-with-openai-agents-sdk-and-vercel-sandbox?from=related) — Learn how to build an agent with with OpenAI Agents SDK and Vercel Sandbox
- [Build AI agents with AI Gateway and AI SDK](https://vercel.com/kb/guide/ai-gateway-and-ai-sdk?from=related) — Build AI agents on Vercel with AI Gateway and AI SDK, then make them reliable, capable, and durable with Sandbox, Chat S
- [Draft content in your voice from Slack with eve](https://vercel.com/kb/guide/eve-content-agent?from=related) — Deploy the eve content agent template, a Slack bot that drafts blog posts, LinkedIn posts, release notes, and newsletter
- [How to build a durable AI code agent on Vercel](https://vercel.com/kb/guide/how-to-build-a-durable-ai-code-agent-on-vercel?from=related) — Build an AI agent that generates code, writes its own tests, and executes them in an isolated microVM with automatic ret
- [Build your first Slack agent with eve](https://vercel.com/kb/guide/eve-slack-agent-starter?from=related) — Deploy the eve Slack agent template: a starter Slack bot built on the eve framework with an example tool and skill.

Full cross-link map for this page: [/kb/guide/build-an-agent-with-vercel-and-flue.graph.md](/kb/guide/build-an-agent-with-vercel-and-flue.graph.md)
<!-- /docsgraph:related -->


[Flue](https://flueframework.com/) is a TypeScript framework for building autonomous agents, designed around a built-in agent harness. It's like Claude Code, but headless and programmable. No TUI, no GUI, just TypeScript. The agents you build act autonomously to solve problems and complete tasks, and most of the logic lives in Markdown: skills, context, and `AGENTS.md`. Write once, then deploy anywhere.

In this guide you will build and deploy a Flue agent to Vercel, connect it to a [Vercel Sandbox](https://vercel.com/docs/vercel-sandbox) MicroVM for isolated code execution, and route all model traffic through [Vercel AI Gateway](https://vercel.com/docs/ai-gateway) for spend tracking, failover, and observability.

## What you'll build

A coding agent exposed over HTTP. It receives a repo URL and a prompt, clones the repo into an isolated Sandbox MicroVM with a real Linux shell, and uses an LLM to explore and work on the codebase. All LLM calls are routed through AI Gateway using a single `provider/model` string, with spend caps and rate limits available from the [Vercel dashboard](https://vercel.com/d?to=%2F%5Bteam%5D%2F%7E%2Fai-gateway%2Fapi-keys&title=AI+Gateway+API+Keys).

## Prerequisites

- Node.js 22+
  
- Vercel CLI (`pnpm add -g vercel`)
  
- A Vercel project with [AI Gateway enabled](https://vercel.com/docs/ai-gateway)
  
- `pnpm` installed
  

You should already have a Flue project that builds and runs. If you don't, scaffold one first:

```bash
pnpm create flue
cd my-agent
```

This gives you a project with the following layout:

```javascript
.flue/
  agents/
  roles/
  connectors/
flue.config.ts
package.json
```

## Link your Vercel project

Connect your Flue project to Vercel and pull a development OIDC token:

```bash
vercel link
vercel env pull
```

This creates a `.env.local` file with a `VERCEL_OIDC_TOKEN`, a short-lived JWT that authenticates requests to both AI Gateway and Sandbox. Both SDKs read it from the environment automatically. No provider API keys or manual wiring needed.

The token expires after 12 hours. Run `vercel env pull` again if you see auth errors. On Vercel deployments, token refresh is automatic.

## Install the Sandbox connector

Flue ships a first-party Vercel Sandbox connector. Install it with `flue add` and pipe the instructions to your coding agent:

```bash
flue add vercel --print | claude
```

This writes a `.flue/connectors/vercel.ts` adapter into your project. Any coding agent works here:

```bash
flue add vercel --print | opencode
flue add vercel --print | codex
flue add vercel --print | cursor-agent
```

Then install the Sandbox SDK:

```bash
pnpm add @vercel/sandbox
```

## Write the agent

Create `.flue/agents/coder.ts`. Three things differ from a default Hello World agent: you import the Sandbox connector, create a MicroVM, and configure AI Gateway as the model provider.

```typescript
import type { FlueContext } from '@flue/sdk/client';
import { Sandbox } from '@vercel/sandbox';
import { vercel } from '../connectors/vercel';

export const triggers = { webhook: true };

export default async function (
  { init, payload, env }: FlueContext
) {
  const sandbox = await Sandbox.create({
    source: { type: 'git', url: payload.repo, depth: 1 },
    runtime: 'node24',
    resources: { vcpus: 2 },
    timeout: 30 * 60 * 1000,
  });
```

The Sandbox boots a real Linux MicroVM with `git`, `node`, `npm`, and a full shell. `resources: { vcpus: 2 }` gives it 4 GB of RAM (2 GB per vCPU). The `source` option clones the target repo on creation.

Next, initialize the Flue agent with the sandbox and AI Gateway routing:

```typescript
const agent = await init({
    sandbox: vercel(sandbox),
    model: 'anthropic/claude-sonnet-4.6',
    providers: {
      anthropic: {
        baseUrl: 'https://ai-gateway.vercel.sh',
        headers: {
          Authorization: `Bearer ${env.VERCEL_OIDC_TOKEN}`,
        },
      },
    },
  });
  const session = await agent.session();

  return await session.prompt(payload.prompt);
}
```

The `model` string uses AI Gateway's `provider/model` format. You can swap to any model in the [model catalog](https://vercel.com/ai-gateway/models) by changing that string. The `providers` block routes all Anthropic traffic through AI Gateway's endpoint, authenticated with your OIDC token. No `ANTHROPIC_API_KEY` needed.

## Run locally

Start the Flue dev server, pointing it at your `.env.local`:

```bash
flue dev --target node --env .env.local
```

Flue defaults to port `3583`. Test the agent with `curl`:

```bash
curl http://localhost:3583/agents/coder/session-1 \
  -H "Content-Type: application/json" \
  -d '{
    "repo": "https://github.com/your-org/your-repo.git",
    "prompt": "Find all API routes and explain them."
  }'
```

The response streams back via SSE. Reuse the same session ID (`session-1`) to continue the conversation. Use a new ID to start fresh.

## Add a role

Roles give your agent persistent instructions without polluting the user prompt. Create `.flue/roles/coder.md`:

```markdown
You are a senior software engineer working inside a
Linux sandbox. You have full shell access.

When exploring a codebase:
1. Start by reading the project structure.
2. Read key config files (package.json, tsconfig).
3. Then dive into the specific area the user asks about.

Always explain what you find before suggesting changes.
```

Then pass the role in your prompt call:

```typescript
return await session.prompt(payload.prompt, {
  role: 'coder',
});
```

Roles can be set at the agent, session, or call level. Call-level roles (like above) take the highest precedence.

## Use tasks for parallel work

Use `session.task()` to run a focused subtask in a detached session. Tasks share the same sandbox and filesystem but get their own message history. This is useful for parallel exploration before a main prompt:

```typescript
const research = await session.task(
  'Find all API routes and summarize the key files.',
  { cwd: '/vercel/sandbox', role: 'researcher' }
);

const answer = await session.prompt(
  `Use this research:\n\n${research.text}\n\n` +
    payload.prompt,
  { role: 'coder' }
);

return answer;
```

The LLM can also spawn tasks on its own during `prompt()` and `skill()` calls, delegating parallel research or exploration work without you writing the orchestration.

## Use snapshots for fast cold starts

The first Sandbox creation takes a few seconds while the MicroVM boots and clones the repo. For repeat sessions against the same repo, snapshots eliminate that wait:

```typescript
const snapshot = await sandbox.snapshot();
console.log('Snapshot ID:', snapshot.snapshotId);
```

Calling `snapshot()` saves the entire MicroVM state, including cloned files and installed dependencies. Subsequent sessions boot from the snapshot in ~100ms:

```typescript
const sandbox = await Sandbox.create({
  source: {
    type: 'snapshot',
    snapshotId: 'snap_abc123',
  },
  ports: [3000],
});
```

Store the snapshot ID per repo and reuse it across agent invocations.

## Configure the sandbox

Common knobs you can set on `Sandbox.create()`:

- `**runtime**`: `'node24'`, `'node22'`, or `'python3.13'`.
  
- `**resources**`: `{ vcpus: 1 }` through `{ vcpus: 8 }`. Each vCPU comes with 2 GB of RAM.
  
- `**ports**`: up to 4 exposed ports, each gets a public URL via `sandbox.domain(port)`.
  
- `**timeout**`: max lifetime. Up to 5 hours on Pro/Enterprise, 45 minutes on Hobby.
  
- `**networkPolicy**`: restrict outbound access to specific domains or CIDRs if your agent should not reach arbitrary hosts.
  

For anything beyond these, treat the [Sandbox SDK reference](https://vercel.com/docs/vercel-sandbox/sdk-reference) as the source of truth.

## Deploy to Vercel

Build the deployable artifact and deploy:

```bash
flue build --target node
vercel deploy
```

On Vercel, the OIDC token auto-refreshes. AI Gateway spend caps, rate limits, and usage analytics apply to all production traffic from the [dashboard](https://vercel.com/d?to=%2F%5Bteam%5D%2F%7E%2Fai-gateway%2Fapi-keys&title=AI+Gateway+API+Keys).

## Next steps

- Browse the [AI Gateway model catalog](https://vercel.com/ai-gateway/models) to try different models by changing the `provider/model` string.
  
- Configure [failover and caching](https://vercel.com/docs/ai-gateway) in AI Gateway for production resilience.
  
- Explore [Sandbox network policies](https://vercel.com/docs/vercel-sandbox) to lock down outbound access.
  

## Troubleshooting

- **OIDC token expired locally?** Run `vercel env pull` again to get a fresh one.
  
- **Sandbox provisioning slow?** Use [snapshots](#use-snapshots-for-fast-cold-starts) to skip boot and clone time.
  
- **Model not found?** Check the [model catalog](https://vercel.com/ai-gateway/models) for the correct `provider/model` slug. Version numbers use dots, not hyphens (e.g. `claude-sonnet-4.6`, not `claude-sonnet-4-6`).
  
- **Sandbox questions**: [Vercel Sandbox docs](https://vercel.com/docs/vercel-sandbox), [SDK reference](https://vercel.com/docs/vercel-sandbox/sdk-reference).
  
- **AI Gateway questions**: [AI Gateway docs](https://vercel.com/docs/ai-gateway).
  
- **Flue questions**: [withastro/flue on GitHub](https://github.com/withastro/flue).