Skip to content

README.md

Latest commit

 

History

History
155 lines (114 loc) · 3.78 KB

README.md

File metadata and controls

155 lines (114 loc) · 3.78 KB

elizaOS REST API Examples

This directory contains REST API examples for elizaOS using TypeScript web frameworks.

All examples use the canonical elizaOS implementation pattern:

runtime.messageService.handleMessage(runtime, messageMemory, callback)

The Canonical Pattern

Every example follows the same core pattern:

  1. Create an AgentRuntime with plugins (sql, openai, etc.)
  2. Initialize the runtime with await runtime.initialize()
  3. Ensure connection for the user session
  4. Create a message memory with the user's message
  5. Call messageService.handleMessage() to process the message

TypeScript Example

import {
  AgentRuntime,
  ChannelType,
  createCharacter,
  createMessageMemory,
  stringToUuid,
} from "@elizaos/core";
import { openaiPlugin } from "@elizaos/plugin-openai";
import sqlPlugin from "@elizaos/plugin-sql";

// Create runtime
const runtime = new AgentRuntime({
  character: createCharacter({ name: "Eliza", bio: "A helpful AI assistant." }),
  plugins: [sqlPlugin, openaiPlugin],
});

await runtime.initialize();

// Handle a message
const messageMemory = createMessageMemory({
  id: uuidv4(),
  entityId: userId,
  roomId: stringToUuid("room"),
  content: { text: "Hello!", source: "api", channelType: ChannelType.API },
});

await runtime.messageService?.handleMessage(runtime, messageMemory, async (content) => {
  console.log("Response:", content.text);
  return [];
});

Available Examples

Framework Language Directory Full Runtime
Express TypeScript express/ Yes
Hono TypeScript hono/ Yes
Elysia TypeScript elysia/ Yes

Common API

All examples expose the same REST API:

GET /

Returns information about the agent.

curl http://localhost:3000/

GET /health

Health check endpoint.

curl http://localhost:3000/health

POST /chat

Send a message to the agent.

curl -X POST http://localhost:3000/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello, how are you?"}'

Response:

{
  "response": "Hello! I'm doing well. How can I help you today?",
  "character": "Eliza",
  "userId": "generated-uuid"
}

POST /chat/stream (TypeScript only)

Send a message and receive a streaming response via Server-Sent Events.

curl -X POST http://localhost:3000/chat/stream \
  -H "Content-Type: application/json" \
  -d '{"message": "Tell me a story"}'

Quick Start

TypeScript (Express, Hono, Elysia)

cd express  # or hono, elysia
bun install
OPENAI_API_KEY=your-key bun run start

Environment Variables

Variable Description Required
OPENAI_API_KEY OpenAI API key Yes
PORT Server port (default: 3000) No
CHARACTER_NAME Agent name No
CHARACTER_BIO Agent bio/description No

Important: Never Call Plugins Directly

DO NOT do this:

// ❌ WRONG - Never call plugin functions directly
import { generateElizaResponse } from "@elizaos/plugin-eliza-classic";
const response = generateElizaResponse(message);

DO this instead:

// ✅ CORRECT - Always use the runtime's message service
await runtime.messageService?.handleMessage(runtime, messageMemory, callback);

The message service:

  • Manages conversation context and memory
  • Runs the shouldRespond classifier to decide whether to reply
  • Invokes providers to gather context
  • Executes actions based on the conversation
  • Handles all model calls through the plugin system