ContextQMD
Back to Eliza

Convex elizaOS Agent

packages/examples/convex/README.md

2.0.17.5 KB
Original Source

Convex elizaOS Agent

Deploy an elizaOS agent as a Convex backend. Messages are processed through runtime.messageService.handleMessage and persisted in Convex's real-time database, giving you reactive queries, automatic caching, and zero-config hosting.

Architecture

┌──────────────┐     ┌──────────────────┐     ┌────────────────────────┐
│  Client      │────▶│  Convex HTTP      │────▶│  Node.js Action        │
│  (curl/app)  │◀────│  Router (http.ts) │◀────│  (agent.ts)            │
└──────────────┘     └──────────────────┘     │                        │
                                               │  AgentRuntime          │
                                               │  messageService        │
                                               │    .handleMessage()    │
                                               └───────────┬────────────┘
                                                           │
                                            ┌──────────────┼──────────────┐
                                            ▼              ▼              ▼
                                      ┌──────────┐  ┌──────────┐  ┌────────────┐
                                      │ Convex   │  │ LLM API  │  │ elizaOS    │
                                      │ Database │  │ (OpenAI  │  │ Plugins    │
                                      │          │  │  etc.)   │  │            │
                                      └──────────┘  └──────────┘  └────────────┘

How It Works

  1. HTTP Router (convex/http.ts) — exposes POST /chat, GET /health, and GET /messages endpoints
  2. Agent Action (convex/agent.ts) — a "use node" action that boots the full elizaOS AgentRuntime, calls messageService.handleMessage, and returns the response
  3. Message Persistence (convex/messages.ts) — internal mutations store every user message and agent response in Convex; public queries let clients subscribe to real-time updates
  4. Schema (convex/schema.ts) — typed tables for messages and conversations

Prerequisites

  • Node.js 18+
  • A Convex account (convex.dev)
  • At least one LLM API key (OpenAI, Anthropic, xAI, Google GenAI, or Groq)

Quick Start

1. Install Dependencies

bash
cd examples/convex
bun install        # or npm install

2. Start Convex Dev Server

bash
convex dev

On first run this will:

  • Prompt you to log in via GitHub
  • Create a new Convex project
  • Generate the convex/_generated/ directory
  • Print your HTTP Actions URL (e.g. https://your-deployment.convex.cloud)

3. Set Environment Variables

Set your LLM API key as a Convex environment variable:

bash
convex env set OPENAI_API_KEY sk-your-key-here

Or for other providers:

bash
convex env set ANTHROPIC_API_KEY your-key
convex env set XAI_API_KEY your-key
convex env set GOOGLE_GENERATIVE_AI_API_KEY your-key
convex env set GROQ_API_KEY your-key

4. Test with curl

bash
# Health check
curl https://your-deployment.convex.cloud/health

# Send a message
curl -X POST https://your-deployment.convex.cloud/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello Eliza!", "conversationId": "test-1"}'

# Retrieve messages
curl "https://your-deployment.convex.cloud/messages?conversationId=test-1"

5. Interactive Test Client

bash
CONVEX_URL=https://your-deployment.convex.cloud bun run test-client.ts

Project Structure

examples/convex/
├── README.md                # This file
├── package.json             # Dependencies (convex, @elizaos/core, LLM plugins)
├── tsconfig.json            # TypeScript configuration
├── .env.example             # Environment variable template
├── convex/
│   ├── schema.ts            # Database schema (messages, conversations)
│   ├── messages.ts          # Queries & mutations for message persistence
│   ├── agent.ts             # "use node" action — elizaOS runtime + handleMessage
│   ├── http.ts              # HTTP router (POST /chat, GET /health, GET /messages)
│   └── _generated/          # Auto-generated by Convex (do not edit)
├── test-client.ts           # Interactive CLI test client
└── scripts/
    └── test-curl.sh         # Quick curl smoke tests

API Reference

POST /chat

Send a message to the elizaOS agent.

Request:

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

Response:

json
{
  "response": "I'm doing well, thank you!",
  "conversationId": "uuid",
  "agentName": "Eliza",
  "provider": "OpenAI",
  "timestamp": "2025-01-10T12:00:00.000Z"
}

GET /health

Returns service health status.

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

GET /messages?conversationId=...

Retrieve all messages in a conversation (ordered by creation time).

json
{
  "messages": [
    { "role": "user", "text": "Hello!", "entityId": "...", ... },
    { "role": "assistant", "text": "Hi there!", "entityId": "...", ... }
  ],
  "conversationId": "..."
}

Environment Variables

VariableRequiredDescription
OPENAI_API_KEYOne ofOpenAI API key
ANTHROPIC_API_KEYOne ofAnthropic API key
XAI_API_KEYOne ofxAI (Grok) API key
GOOGLE_GENERATIVE_AI_API_KEYOne ofGoogle GenAI (Gemini) API key
GROQ_API_KEYOne ofGroq API key

Set via convex env set KEY value.

Deploying to Production

bash
convex deploy

This pushes your functions to Convex's production environment. Set environment variables on the production deployment:

bash
convex env set OPENAI_API_KEY sk-your-prod-key --prod

Key Concepts

Why "use node" in agent.ts?

The "use node" directive tells Convex to run this action in a full Node.js environment instead of the default Convex runtime. This is required because @elizaos/core and the LLM plugins use Node.js APIs and npm packages.

Warm Container Reuse

The AgentRuntime is cached at module scope so that subsequent invocations on the same Convex isolate reuse the already-initialized runtime, avoiding cold-start overhead.

Real-time Subscriptions

Because messages are stored in Convex tables, any client using the Convex React hooks (or the Convex client SDK) can subscribe to api.messages.list and get real-time updates as the agent responds.

See Also