Vercel

Vercel is a serverless platform optimized for frontend frameworks and API routes. Best for: API-based agents, webhook handlers, and request-response workflows with automatic scaling. Vercel offers zero-configuration deployment and automatic scaling, though it is limited by serverless function execution times. This guide shows you how to deploy your ADK-TS agent to Vercel.

What You'll Need

Before deploying to Railway, ensure you have:

• A Vercel Account to manage your deployments
• Your ADK-TS project ready for deployment

Deployment Options

Vercel offers two main deployment methods:

1. GitHub Auto-Deploy (Recommended): Vercel automatically detects and builds your project from GitHub (Recommended)
2. Vercel CLI (Manual Deployment): Deploy directly from your terminal for manual control and testing

Option 1: GitHub Auto-Deploy (Recommended)

Vercel automatically detects and builds your Node.js/TypeScript project without requiring manual configuration.

Step 1: Set up your API route

• Install Vercel's dependencies so the platform can build and serve your API route:

pnpm add -D vercel @vercel/node

Or use npm install --save-dev if you prefer npm or yarn add --dev for yarn.

• Create an API route in the api directory (e.g., api/chat.ts): This tells Vercel how to handle incoming requests to your agent.

import { AgentBuilder } from "@iqai/adk";
import type { VercelRequest, VercelResponse } from "@vercel/node";
import { env } from "./env";

export default async function handler(req: VercelRequest, res: VercelResponse) {
  if (req.method !== "POST") {
    return res.status(405).json({ error: "Method not allowed" });
  }

  try {
    const { message } = req.body;

    const { runner } = await AgentBuilder.create("assistant")
      .withModel(env.LLM_MODEL)
      .withInstruction("You are a helpful assistant")
      .build();

    const response = await runner.ask(message);

    return res.status(200).json({ response });
  } catch (error) {
    console.error("Agent error:", error);
    return res.status(500).json({ error: "Internal server error" });
  }
}

export const config = {
  maxDuration: 60,
};

Step 2: Push to GitHub

Commit and push your code to GitHub:

git add .
git commit -m "Prepare for Vercel deployment"
git push origin main

Step 3: Connect to Vercel

1. Log in to Vercel
2. Click "Add New..." → "Project"
3. Select "Import Git Repository" and choose your repository
4. Authorize Vercel to access your Git provider (if first time)
5. Choose the branch to deploy (usually main) and click "Deploy"

Step 4: Configure Environment Variables

See Configuring Environment Variables below for detailed instructions.

Step 5: Automatic Deployment

Vercel handles everything automatically:

• First deployment: Clones your repo, installs dependencies, builds, and deploys
• Future updates: Every time you push to your connected branch, Vercel rebuilds and redeploys
• No manual steps needed after initial setup

Option 2: Vercel CLI (Manual Deployment)

Use the Vercel CLI for manual deployments or when you want to deploy without a Git integration.

Step 1: Install Vercel CLI

npm install -g vercel

Step 2: Login

vercel login

Step 3: Deploy

From your project directory:

# Deploy to preview (staging)
vercel

# Deploy to production
vercel --prod

Step 4: Configure Environment Variables

See Configuring Environment Variables below.

Configuring Environment Variables

All deployment options require environment variables to be configured in Vercel. This is a one-time setup for each project.

Add Environment Variables to Vercel

1. In your Vercel project, go to "Settings" → "Environment Variables"
2. Add each required environment variable based on your agent's needs.

Verifying Deployment

Check Deployment Status

In your Vercel project dashboard:

1. Look for the "Deployments" tab - it should show "Ready" with a green indicator
2. Click on the latest deployment to view detailed logs and the deployment URL
3. Check the logs for your agent's startup messages
4. Look for any error messages

Test Your Agent

Once deployment is active, test that it works:

• API agents: Make a test HTTP request to your endpoint (e.g., https://your-project.vercel.app/api/chat)
• Check logs: Watch Vercel logs in real-time to see your agent responding
• Webhooks: Verify that your webhook handlers are receiving data

Monitoring and Updates

View Logs

Vercel provides real-time logs in the "Logs" tab of your deployment. Use them to:

• Debug issues by viewing error messages
• Monitor your agent's activity and responses
• Track performance and execution times

Updating Your Deployment

For GitHub deployments (Option 1):

1. Make code changes locally
2. Test changes locally using vercel dev
3. Commit and push to your connected branch:

   git add .
   git commit -m "Update agent features"
   git push origin main

4. Vercel automatically detects changes, rebuilds, and redeploys

For CLI deployments (Option 2):

1. Make code changes locally
2. Deploy again using the CLI:

   vercel --prod

3. Vercel will create a new deployment automatically

Vercel Troubleshooting

• Function Timeouts: If your agent takes longer than the default 10-15s to respond, Vercel will terminate the function. Increase maxDuration in your function config (up to 60s or more depending on your plan).
• Cold Start Latency: The first request after some inactivity may be slower due to serverless cold starts. If low latency is critical, consider a platform with long-running instances like Railway.
• Deployment Conflicts: If multiple branches are deploying, check the "Deployments" tab to ensure you are testing the correct version.

Vercel Best Practices

• Local Development: Always use vercel dev to test your API routes locally. This simulates the Vercel environment more accurately than standard Node.js.
• Edge Functions: For simple logic, consider using Edge Functions for faster startup times, though note they have more limited Node.js API support.

Next Steps