@voltagent/server-core

Framework-agnostic server core for VoltAgent. This package provides the shared infrastructure — route definitions, request handlers, WebSocket support, authentication utilities, MCP/A2A protocol helpers, and a base server provider — that all VoltAgent server adapters (e.g. @voltagent/server-hono) build on top of.

You typically do not use this package directly. Instead, choose a server adapter for your framework (such as @voltagent/server-hono) and pass it to the VoltAgent constructor. If you are building a custom server adapter, this package gives you everything you need.

Key Exports

Base Server Provider

BaseServerProvider — Abstract class that handles the common server lifecycle (port allocation, WebSocket setup, graceful shutdown, startup banner). Extend it when building a custom adapter.

import { BaseServerProvider } from "@voltagent/server-core";

Route Definitions

Pre-built, framework-agnostic route metadata objects you can use to register routes in any HTTP framework:

| Export | Routes covered | | ----------------------------- | -------------------------------------------- | | AGENT_ROUTES | Agent management and generation | | WORKFLOW_ROUTES | Workflow execute / stream / suspend / resume | | TOOL_ROUTES | Tool listing and direct execution | | MEMORY_ROUTES | Conversation and message management | | LOG_ROUTES | Log retrieval | | OBSERVABILITY_ROUTES | Traces, spans, and observability status | | OBSERVABILITY_MEMORY_ROUTES | Memory inspection for observability | | MCP_ROUTES | Model Context Protocol server endpoints | | A2A_ROUTES | Agent-to-Agent protocol endpoints | | ALL_ROUTES | All of the above combined |

Helper functions: getAllRoutesArray(), getRoutesByTag(tag).

Request Handlers

Framework-agnostic handler functions. Each handler receives a ServerProviderDeps context and returns a serialisable response object, making them easy to wrap in any HTTP framework:

• Agent handlers — handleGenerateText, handleStreamText, handleChatStream, handleResumeChatStream, handleGenerateObject, handleStreamObject
• Workflow handlers — handleGetWorkflows, handleGetWorkflow, handleExecuteWorkflow, handleStreamWorkflow, handleAttachWorkflowStream, handleSuspendWorkflow, handleResumeWorkflow, handleListWorkflowRuns, handleGetWorkflowState
• Tool handlers — handleListTools, handleExecuteTool
• Memory handlers — handleListMemoryConversations, handleCreateMemoryConversation, handleSaveMemoryMessages, and more
• Observability handlers — getTracesHandler, getTraceByIdHandler, getObservabilityStatusHandler, and more
• Log handlers — handleGetLogs

Authentication

Plug-in auth via the AuthProvider interface. A built-in JWT provider is included:

import { jwtAuth, createJWT } from "@voltagent/server-core";

WebSocket Utilities

createWebSocketServer, setupWebSocketUpgrade — set up real-time log and observability streaming over WebSocket.

MCP & A2A Protocol Helpers

• MCPServerRegistry, listMcpServers, lookupMcpServer — register and resolve MCP servers
• A2AServerRegistry, listA2AServers, lookupA2AServer, executeA2ARequest — Agent-to-Agent protocol support

App Setup Utilities

getOpenApiDoc, shouldEnableSwaggerUI, getOrCreateLogger, DEFAULT_CORS_OPTIONS — helpers shared by all server adapters.

Edge Entry Point

A lighter entry point for edge runtimes (e.g. Cloudflare Workers, Vercel Edge) is available at the ./edge export:

import { AGENT_ROUTES, handleGenerateText } from "@voltagent/server-core/edge";

Usage Example — Custom Server Adapter

The snippet below shows the minimum required to build a custom server adapter on top of @voltagent/server-core:

import { createServer, type Server } from "node:http";
import { BaseServerProvider, type ServerProviderConfig } from "@voltagent/server-core";
import type { ServerProviderDeps } from "@voltagent/core";

export class MyCustomServerProvider extends BaseServerProvider {
  constructor(deps: ServerProviderDeps, config: ServerProviderConfig = {}) {
    super(deps, config);
  }

  protected async startServer(port: number): Promise<Server> {
    const server = createServer((req, res) => {
      // Route incoming requests to the framework-agnostic handlers
      res.writeHead(404);
      res.end("Not found");
    });

    await new Promise<void>((resolve) => server.listen(port, resolve));
    return server;
  }

  protected async stopServer(): Promise<void> {
    await new Promise<void>((resolve, reject) => {
      this.server?.close((err) => (err ? reject(err) : resolve()));
    });
  }
}

// Factory function consumed by VoltAgent
export function myCustomServer(config?: ServerProviderConfig) {
  return (deps: ServerProviderDeps) => new MyCustomServerProvider(deps, config);
}

Pass the factory to VoltAgent:

import { VoltAgent, Agent } from "@voltagent/core";
import { openai } from "@ai-sdk/openai";
import { myCustomServer } from "./my-custom-server";

const agent = new Agent({
  name: "my-agent",
  instructions: "A helpful assistant",
  model: openai("gpt-4o-mini"),
});

new VoltAgent({
  agents: { agent },
  server: myCustomServer({ port: 3141 }),
});

For a complete, production-ready server adapter see @voltagent/server-hono.

Documentation

• VoltAgent Documentation
• Agent Overview
• MCP Integration

License

Licensed under the MIT License, Copyright © 2026-present VoltAgent.