Vercel Edge Function elizaOS Worker Examples

Deploy AI chat agents as serverless Vercel Edge Functions. These examples show how to run an elizaOS agent as a stateless worker that processes chat messages via HTTP.

All handlers use the full elizaOS runtime with OpenAI as the LLM provider, providing the same capabilities as the AWS Lambda examples.

Architecture

┌──────────────┐     ┌─────────────────┐     ┌────────────────┐
│  Test Client │────▶│  Vercel Edge    │────▶│  Edge Function │
│  (curl/bun)  │◀────│  Network        │◀────│  (elizaOS)     │
└──────────────┘     └─────────────────┘     └────────────────┘
                                                    │
                                                    ▼
                                             ┌────────────────┐
                                             │  OpenAI API    │
                                             └────────────────┘

Prerequisites

• Vercel CLI (npm i -g vercel)
• Bun or Node.js 20+
• OpenAI API key

Quick Start

1. Set Environment Variables

Create a .env file in the project root (/home/shaw/eliza/.env):

OPENAI_API_KEY=your-openai-api-key

Or export directly:

export OPENAI_API_KEY="your-openai-api-key"

2. Test Locally First

Before deploying, test locally to verify everything works.

Start Local Development Server

cd examples/vercel
bun install
vercel dev

The development server runs at http://localhost:3000.

Run Automated Tests

# Test the local dev server
bun run test

Test with curl

# Health check
curl http://localhost:3000/api/health

# Chat
curl -X POST http://localhost:3000/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello, Eliza!"}'

3. Deploy to Vercel

First-time Setup

# Link to your Vercel account
vercel link

# Set your OpenAI API key as an environment variable
vercel env add OPENAI_API_KEY
# When prompted, enter your API key

Deploy

# Preview deployment
vercel deploy

# Production deployment
vercel deploy --prod

4. Test Your Deployment

After deployment, Vercel outputs your deployment URL. Test it:

# Using curl
curl -X POST https://your-app.vercel.app/api/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello, Eliza!"}'

# Using the test client
bun run test-client.ts --endpoint https://your-app.vercel.app

Project Structure

examples/vercel/
├── README.md
├── vercel.json
├── package.json
├── tsconfig.json
├── test-client.ts
└── api/
    ├── health.ts
    └── chat.ts

API Reference

POST /api/chat

Send a message to the elizaOS agent.

Request:

{
  "message": "Hello, how are you?",
  "userId": "optional-user-id",
  "conversationId": "optional-conversation-id"
}

Response:

{
  "response": "I'm doing well, thank you for asking!",
  "conversationId": "uuid-for-conversation-tracking",
  "timestamp": "2025-01-10T12:00:00.000Z"
}

GET /api/health

Health check endpoint.

Response:

{
  "status": "healthy",
  "runtime": "elizaos-typescript",
  "version": "2.0.0-beta.0"
}

Edge functions (TypeScript)

Handlers live under api/ as Vercel Edge routes. Local workflow:

cd examples/vercel
bun install
vercel dev

Configuration

Environment Variables

Character Customization

Customize the agent's personality by setting environment variables in the Vercel dashboard or CLI:

vercel env add CHARACTER_NAME
# Enter: MyBot

vercel env add CHARACTER_SYSTEM
# Enter: You are a friendly assistant that loves to help.

Comparison with AWS Lambda

Performance Considerations

Edge Functions

• Cold starts: Edge Functions have minimal cold starts (~50ms)
• Global distribution: Automatically deployed to all Vercel edge locations
• Streaming: Supports streaming responses for real-time output

Serverless Functions (Python)

• Cold starts: Slightly longer than Edge (~200-500ms)
• Memory: More memory available (up to 1GB)
• Duration: Longer execution time allowed (60s)

Monitoring

Vercel Dashboard

View logs, metrics, and analytics in the Vercel dashboard:

1. Go to your project at https://vercel.com
2. Click on "Functions" tab
3. View real-time logs and invocation metrics

CLI Logs

# View production logs
vercel logs --output raw

# Follow logs in real-time
vercel logs -f

Cost Estimation

Vercel pricing (as of 2025):

Hobby (Free):

• 100GB bandwidth/month
• 100 hours function execution/month
• Serverless functions only

Pro ($20/month):

• 1TB bandwidth/month
• 1000 hours function execution/month
• Edge functions included

Example (10K requests/month, avg 2s response):

• Function hours: 10,000 × 2s = ~5.5 hours
• Well within free tier

Troubleshooting

"Module not found" Error

Ensure dependencies are installed:

bun install

OPENAI_API_KEY Not Found

1. Verify the environment variable is set in Vercel:

   bashCopy

   vercel env ls
   

2. If missing, add it:

   bashCopy

   vercel env add OPENAI_API_KEY
   

3. Redeploy:

   bashCopy

   vercel deploy --prod
   

Function Timeout

Edge Functions have a 30-second limit. For longer operations:

1. Use Serverless Functions (60s limit)
2. Implement streaming responses
3. Consider background jobs with Vercel Cron

CORS Issues

CORS headers are included by default. If you need custom origins:

const headers = {
  "Access-Control-Allow-Origin": "https://your-domain.com",
  // ... other headers
};

Cleanup

Remove your Vercel deployment:

# Remove from Vercel
vercel remove your-project-name

# Or delete via dashboard at vercel.com

See Also

• elizaOS Documentation
• Vercel Edge Functions
• Vercel CLI Documentation
• AWS Lambda Examples