Skip to content

README.md

Latest commit

 

History

History
241 lines (179 loc) · 6.16 KB

README.md

File metadata and controls

241 lines (179 loc) · 6.16 KB

@voltagent/server-elysia

Elysia server implementation for VoltAgent - A high-performance, type-safe server provider built on Elysia.

Features

  • 🚀 High Performance: Built on Elysia, one of the fastest TypeScript frameworks
  • 🔒 Type Safe: Full TypeScript support with strict typing
  • 🔐 Authentication: JWT authentication with flexible configuration via authNext
  • 🌐 CORS Support: Easy CORS configuration for cross-origin requests
  • 📡 WebSocket Support: Real-time streaming and updates
  • 🛠️ Extensible: Easy to add custom routes, middleware, and plugins
  • 📚 OpenAPI/Swagger: Built-in API documentation via @elysiajs/swagger
  • 🔌 MCP Support: Full Model Context Protocol implementation

Installation

pnpm add @voltagent/server-elysia elysia

Quick Start

import { createVoltAgent } from "@voltagent/core";
import { elysiaServer } from "@voltagent/server-elysia";
import { openai } from "@ai-sdk/openai";

const volt = createVoltAgent({
  agents: [
    {
      id: "my-agent",
      model: openai("gpt-4"),
      instructions: "You are a helpful assistant",
    },
  ],
  server: elysiaServer({
    port: 3141,
  }),
});

volt.start();

Configuration

Basic Configuration

elysiaServer({
  port: 3141,
  hostname: "0.0.0.0",
  enableSwaggerUI: true,
});

CORS Configuration

elysiaServer({
  cors: {
    origin: "https://example.com",
    allowMethods: ["GET", "POST", "PUT", "DELETE"],
    allowHeaders: ["Content-Type", "Authorization"],
    credentials: true,
  },
});

Authentication with authNext

import { jwtAuth } from "@voltagent/server-elysia";

elysiaServer({
  authNext: {
    provider: jwtAuth({ secret: process.env.JWT_SECRET! }),
    publicRoutes: ["GET /health", "POST /webhooks/*"],
  },
});

Custom Routes

elysiaServer({
  configureApp: (app) => {
    // Add custom routes
    app.get("/health", () => ({ status: "ok" }));

    // Add route groups
    app.group("/api/v2", (app) => app.get("/users", () => ({ users: [] })));

    // Add middleware
    app.use(customPlugin);
  },
});

Full App Configuration

For complete control over route and middleware ordering:

elysiaServer({
  configureFullApp: ({ app, routes, middlewares }) => {
    // Apply middleware first
    middlewares.cors();
    middlewares.auth();

    // Register routes in custom order
    routes.agents();

    // Add custom routes between VoltAgent routes
    app.get("/custom", () => ({ custom: true }));

    // Register remaining routes
    routes.workflows();
    routes.tools();
    routes.doc();
  },
});

API Endpoints

Once running, the following endpoints are available:

Agent Endpoints

  • GET /agents - List all agents
  • GET /agents/:id - Get agent details
  • POST /agents/:id/text - Generate text
  • POST /agents/:id/stream - Stream text generation
  • POST /agents/:id/chat - Stream chat messages
  • POST /agents/:id/object - Generate structured objects

Workflow Endpoints

  • GET /workflows - List all workflows
  • GET /workflows/:id - Get workflow details
  • POST /workflows/:id/execute - Execute a workflow
  • POST /workflows/:id/stream - Stream workflow execution

Tool Endpoints

  • GET /tools - List all tools
  • POST /tools/:name/execute - Execute a tool

Observability Endpoints

  • GET /observability - Get observability data
  • GET /observability/traces - List traces
  • GET /observability/traces/:traceId - Get specific trace

Documentation

  • GET / - Landing page
  • GET /doc - OpenAPI specification
  • GET /ui - Swagger UI (if enabled)

Comparison with server-hono

Both server-hono and server-elysia provide the same VoltAgent features, but with different framework implementations:

Feature server-hono server-elysia
Performance Fast Faster (Elysia is optimized for speed)
Validation Zod (Native) TypeBox (via Zod Adapter)
OpenAPI Via @hono/zod-openapi Via @elysiajs/swagger (built-in)
Middleware Hono middleware Elysia plugins
Type Safety Full TypeScript Full TypeScript with enhanced inference
Bundle Size ~28KB ~26KB

Architecture & Validation

One key difference is how validation is handled:

  • server-hono uses zod natively for validation and OpenAPI generation.
  • server-elysia uses TypeBox (Elysia's native validation engine) for maximum performance.

Since VoltAgent's core schemas are defined in zod (in @voltagent/server-core), server-elysia includes a specialized Zod Adapter. This adapter automatically transforms Zod schemas into TypeBox/JSON Schema format at runtime, ensuring:

  1. Compatibility: All existing VoltAgent schemas work out of the box.
  2. Performance: Validation runs using Elysia's optimized TypeBox compiler.
  3. Documentation: OpenAPI specs are generated correctly using Elysia's Swagger plugin.

Choose server-elysia if you:

  • Want maximum performance
  • Prefer Elysia's plugin ecosystem
  • Need built-in Eden (type-safe client)

Choose server-hono if you:

  • Are already familiar with Hono
  • Need compatibility with Cloudflare Workers
  • Want a more mature ecosystem

Advanced Usage

Custom Middleware

import { Elysia } from "elysia";

const customMiddleware = new Elysia().derive(({ request }) => ({
  userId: request.headers.get("x-user-id"),
}));

elysiaServer({
  configureApp: (app) => {
    app.use(customMiddleware);
  },
});

Error Handling

elysiaServer({
  configureApp: (app) => {
    app.onError(({ code, error }) => {
      if (code === "NOT_FOUND") {
        return { error: "Route not found" };
      }
      return { error: error.message };
    });
  },
});

License

MIT

Links