> For the complete documentation index, see [llms.txt](/llms.txt).
> A full single-fetch corpus is available at [llms-full.txt](/llms-full.txt).
---
title: Deploy a serverless endpoint to Vercel
description: Deploy an AGNT5 endpoint with Next.js route handlers or the Vercel Python runtime, then activate an immutable release.
last_verified: 2026-08-25
---

A **serverless endpoint** exposes AGNT5 components through signed HTTP routes. This guide adds those routes to a TypeScript or Python application, deploys them to Vercel, and syncs the immutable Vercel deployment into AGNT5.

## 1. Add the handler

Choose the runtime already used by your project.

### TypeScript and Next.js

```bash
npm install @agnt5/sdk
agnt5 serverless init \
  --provider vercel \
  --runtime typescript \
  --name orders-api
```

The command creates a shared handler plus `GET /.well-known/agnt5` and `POST /agnt5/invoke` route handlers. Keep both generated routes on the Node.js runtime. The TypeScript SDK loads optional native packages and does not support the Edge runtime.

Configure Next.js to leave the SDK and its SQLite driver external to the route bundle:

```js title="next.config.mjs"
/** @type {import('next').NextConfig} */
const nextConfig = {
  serverExternalPackages: ['@agnt5/sdk', 'better-sqlite3'],
};

export default nextConfig;
```

For Next.js 16, build with Webpack because Turbopack cannot currently bundle the SDK's optional native loader:

```json title="package.json"
{
  "scripts": {
    "build": "next build --webpack",
    "dev": "next dev --webpack"
  }
}
```

Set `runtime` and `maxDuration` as route-segment config in the generated invoke route. Size `maxDuration` for your workflow's total LLM and tool-call time — agents that make several sequential tool calls per run need more budget than a single-call agent, since each tool call is its own model round trip:

```ts title="app/agnt5/invoke/route.ts"
import { agnt5Workerless } from '../../../src/agnt5-workerless';

export const runtime = 'nodejs';
export const maxDuration = 120;

export function POST(request: Request): Promise<Response> {
  return agnt5Workerless.fetch(request);
}
```

Check Vercel's current [function duration limits](https://vercel.com/docs/functions/configuring-functions/duration) for the maximum allowed on your plan.

### Python and FastAPI

The Vercel Python runtime is beta. It recognizes a FastAPI `app` at the generated `app.py` entrypoint.

```bash
uv add agnt5 fastapi
agnt5 serverless init \
  --provider vercel \
  --runtime python \
  --name orders-api
```

The Python scaffold reads `VERCEL_DEPLOYMENT_ID` as its immutable service version. Add a supported Python version to `pyproject.toml` or `.python-version` before deployment.

## 2. Configure signing

Generate one secret and store the same value in Vercel and AGNT5:

```bash
( umask 077 && openssl rand -base64 32 > .agnt5-serverless-secret )
vercel env add AGNT5_SERVERLESS_SIGNING_SECRET production \
  < .agnt5-serverless-secret
```

Add `.agnt5-serverless-secret` to `.gitignore` before continuing.

## 3. Deploy and validate

Deploy an immutable production release:

```bash
vercel deploy --prod
agnt5 serverless validate https://<vercel-deployment-host>
```

For a protected deployment, pass Vercel's automation bypass header:

```bash
export VERCEL_AUTOMATION_BYPASS_SECRET=<vercel-bypass-secret>
agnt5 serverless validate https://<vercel-deployment-host> \
  --invoke-header-env x-vercel-protection-bypass=VERCEL_AUTOMATION_BYPASS_SECRET
```

## 4. Sync and activate

Import the release without changing active routes:

```bash
export AGNT5_SERVERLESS_SIGNING_SECRET="$(cat .agnt5-serverless-secret)"

agnt5 serverless sync https://<vercel-deployment-host> \
  --provider vercel \
  --env production \
  --immutable-ref <vercel-deployment-id> \
  --signing-secret-env AGNT5_SERVERLESS_SIGNING_SECRET \
  --request-timeout-ms 10000 \
  --yield-before-timeout-ms 1000 \
  --activate=false
```

Run **`agnt5 serverless status --deployment-id <deployment-id> --verify`**. Repeat the sync with `--activate=true` only after verification passes.

## Next steps

- [Serverless SDK reference](/docs/run/serverless-sdk-reference.md): use durable steps, timers, events, and budget suspension.
- [Serverless support matrix](/docs/run/serverless-support-matrix.md): compare the TypeScript and Python evidence levels.
- [Integrate Python web frameworks](/docs/integrations/python-web-frameworks.md): use the Python adapter outside FastAPI.
- [Operate serverless endpoints](/docs/run/operate-serverless-endpoints.md): promote, disable, recover, and roll back releases.
- [Serverless CLI reference](/docs/cli/serverless.md): inspect every sync and provider-header option.