--- 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" 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 --- [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: `pnpm create flue cd my-agent` This gives you a project with the following layout: `.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: `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: `flue add vercel --print | claude` This writes a `.flue/connectors/vercel.ts` adapter into your project. Any coding agent works here: `flue add vercel --print | opencode flue add vercel --print | codex flue add vercel --print | cursor-agent` Then install the Sandbox SDK: `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. `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: ``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`: `flue dev --target node --env .env.local` Flue defaults to port `3583`. Test the agent with `curl`: `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`: `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: `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: ``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: `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: `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: `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).