Skip to content

vercel

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

vercel

README.md

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

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 packages/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 packages/examples/vercel
bun install
vercel dev

Configuration

Environment Variables

Variable Required Default Description
OPENAI_API_KEY Yes - Your OpenAI API key
OPENAI_SMALL_MODEL No gpt-5-mini Small model to use
OPENAI_LARGE_MODEL No gpt-5 Large model to use
CHARACTER_NAME No Eliza Agent's name
CHARACTER_BIO No A helpful AI assistant. Agent's bio
CHARACTER_SYSTEM No (default) System prompt

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

Feature Vercel Edge AWS Lambda
Cold start ~50ms 2-5s
Global distribution Automatic Via CloudFront
Pricing Per invocation Per invocation + duration
Max execution time 30s (Edge) 15 min
Memory 128MB (Edge) Up to 10GB
Languages JS/TS, WASM Many

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:

    vercel env ls

  2. If missing, add it:

    vercel env add OPENAI_API_KEY

  3. Redeploy:

    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