Skip to content

README.md

Latest commit

 

History

History
399 lines (286 loc) · 9.57 KB

README.md

File metadata and controls

399 lines (286 loc) · 9.57 KB

GCP Cloud Run elizaOS Worker Examples

Deploy elizaOS agents as serverless GCP Cloud Run services. This example shows how to run an AI agent as a containerized worker that processes chat messages via HTTP.

Architecture

┌──────────────┐     ┌─────────────────┐     ┌────────────────┐
│  Test Client │────▶│  Cloud Run      │────▶│  elizaOS       │
│  (curl/node) │◀────│  (HTTP)         │◀────│  Worker        │
└──────────────┘     └─────────────────┘     └────────────────┘
                                                     │
                                                     ▼
                                              ┌────────────────┐
                                              │  OpenAI API    │
                                              └────────────────┘

Prerequisites

  • Google Cloud SDK installed and configured
  • Docker installed
  • GCP project with Cloud Run API enabled
  • OpenAI API key

Quick Start

1. Set Environment Variables

export PROJECT_ID="your-gcp-project-id"
export REGION="us-central1"
export OPENAI_API_KEY="your-openai-api-key"

2. Enable Required APIs

gcloud config set project $PROJECT_ID
gcloud services enable run.googleapis.com
gcloud services enable cloudbuild.googleapis.com
gcloud services enable artifactregistry.googleapis.com

3. Deploy

cd packages/examples/gcp
npm install
npm run build

# Build and deploy
gcloud run deploy eliza-worker-ts \
  --source . \
  --region $REGION \
  --allow-unauthenticated \
  --set-env-vars "OPENAI_API_KEY=$OPENAI_API_KEY"

4. Test Your Deployment

After deployment, Cloud Run provides a URL. Test it:

# Get service URL
SERVICE_URL=$(gcloud run services describe eliza-worker-ts --region $REGION --format 'value(status.url)')

# Health check
curl $SERVICE_URL/health

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

# Using the test client
cd packages/examples/gcp
bun run test-client.ts --url $SERVICE_URL

Local Development

cd packages/examples/gcp
npm install
npm run dev
# Server runs at http://localhost:8080

Validate

bun run test
bun run typecheck

bun run test performs a non-interactive worker availability check. If no local or deployed worker URL is configured, it skips cleanly and prints the setup hint.

Project Structure

packages/examples/gcp/
├── README.md                 # This file
├── Dockerfile                # Cloud Run container image
├── handler.ts                # Cloud Run handler
├── test-client.ts            # Interactive test client
├── package.json              # Test client dependencies
├── cloudbuild.yaml           # Cloud Build configuration
├── deploy.sh                 # Deployment helper
├── env.example               # Environment template
└── terraform/                # Optional infrastructure template

API Reference

POST /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 /health

Health check endpoint.

Response:

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

GET /

Service info endpoint.

Response:

{
  "name": "Eliza",
  "bio": "A helpful AI assistant.",
  "version": "2.0.0-beta.0",
  "powered_by": "elizaOS"
}

Deployment Options

Option 1: gcloud run deploy (Recommended)

# Deploy from source (builds automatically)
gcloud run deploy eliza-worker \
  --source . \
  --region $REGION \
  --allow-unauthenticated \
  --set-env-vars "OPENAI_API_KEY=$OPENAI_API_KEY"

Option 2: Cloud Build

# Submit build and deploy
gcloud builds submit --config=cloudbuild.yaml \
  --substitutions=_REGION=$REGION,_OPENAI_API_KEY=$OPENAI_API_KEY

Option 3: Terraform

See the Terraform example for infrastructure-as-code deployment.

Configuration

Environment Variables

Variable Required Default Description
OPENAI_API_KEY Yes - Your OpenAI API key
OPENAI_MODEL No gpt-5-mini Model to use
OPENAI_BASE_URL No OpenAI default Custom API endpoint
CHARACTER_NAME No Eliza Agent's name
CHARACTER_BIO No A helpful AI assistant. Agent's bio
CHARACTER_SYSTEM No Default system prompt Custom system prompt
PORT No 8080 Server port (set by Cloud Run)
LOG_LEVEL No INFO Logging level

Character Customization

Customize the agent's personality via environment variables:

gcloud run deploy eliza-worker \
  --set-env-vars "OPENAI_API_KEY=$OPENAI_API_KEY" \
  --set-env-vars "CHARACTER_NAME=Ada" \
  --set-env-vars "CHARACTER_BIO=A brilliant mathematician and programmer" \
  --set-env-vars "CHARACTER_SYSTEM=You are Ada Lovelace, speaking from the 19th century..."

Performance Considerations

Cold Starts

Cloud Run cold starts are typically 1-3 seconds. To minimize:

  1. Minimum Instances: Keep at least one instance warm

    gcloud run deploy eliza-worker --min-instances 1

  2. Smaller Container: Use multi-stage Docker builds

  3. Startup CPU Boost: Enable for faster cold starts

    gcloud run deploy eliza-worker --cpu-boost

Resource Configuration

Recommended settings:

Runtime Memory CPU Timeout
TypeScript 512 Mi 1 60s 
gcloud run deploy eliza-worker \
  --memory 512Mi \
  --cpu 1 \
  --timeout 60s

Monitoring

View Logs

gcloud run logs read eliza-worker --region $REGION --limit 100

Streaming Logs

gcloud run logs tail eliza-worker --region $REGION

Cloud Monitoring

Cloud Run automatically provides metrics:

  • Request count
  • Request latencies
  • Container instance count
  • Billable container instance time
  • CPU and memory utilization

Cost Estimation

Cloud Run pricing (as of 2025):

  • CPU: $0.000024 per vCPU-second
  • Memory: $0.0000025 per GiB-second
  • Requests: $0.40 per million requests

Example (1 vCPU, 512 MiB, 2s avg duration, 10K requests/month):

  • CPU: 10,000 × 2s × $0.000024 = $0.48
  • Memory: 10,000 × 2s × 0.5 × $0.0000025 = $0.025
  • Requests: 10,000 × $0.0000004 = $0.004
  • Total: ~$0.51/month

Note: Free tier includes 2 million requests/month

Authentication

Allow Unauthenticated (Public)

gcloud run deploy eliza-worker --allow-unauthenticated

Require Authentication

gcloud run deploy eliza-worker --no-allow-unauthenticated

# Invoke with authentication
curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
  $SERVICE_URL/chat

Custom Domain

gcloud run domain-mappings create \
  --service eliza-worker \
  --domain eliza.yourdomain.com \
  --region $REGION

Troubleshooting

Container Fails to Start

Check logs for startup errors:

gcloud run logs read eliza-worker --region $REGION --limit 50

"Permission Denied" Error

Ensure the service account has required permissions:

gcloud run services add-iam-policy-binding eliza-worker \
  --member="allUsers" \
  --role="roles/run.invoker" \
  --region $REGION

API Key Not Found

Verify environment variables are set:

gcloud run services describe eliza-worker \
  --region $REGION \
  --format 'yaml(spec.template.spec.containers[0].env)'

Timeout Errors

Increase request timeout:

gcloud run deploy eliza-worker --timeout 300s

Cleanup

Remove all deployed resources:

# Delete Cloud Run service
gcloud run services delete eliza-worker --region $REGION --quiet

# Delete container images (optional)
gcloud artifacts docker images delete \
  $REGION-docker.pkg.dev/$PROJECT_ID/eliza/eliza-worker --quiet

Security Best Practices

  1. Use Secret Manager for API keys:

    echo -n "$OPENAI_API_KEY" | gcloud secrets create openai-api-key --data-file=-

gcloud run deploy eliza-worker \
  --set-secrets "OPENAI_API_KEY=openai-api-key:latest"

  2. Enable VPC Connector for private networking

  3. Set up Cloud Armor for DDoS protection

  4. Use IAM for authentication when possible

See Also