AI Agent Engineering Platform
[](https://github.com/voltagent/voltagent/issues)
[](https://github.com/voltagent/voltagent/pulls)
[](https://opensource.org/licenses/MIT)
[](https://www.npmjs.com/package/@voltagent/server-core)
[](https://www.npmjs.com/package/@voltagent/server-core)
[](https://s.voltagent.dev/discord)
## @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.
```ts
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:
```ts
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:
```ts
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`:
```typescript
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 {
const server = createServer((req, res) => {
// Route incoming requests to the framework-agnostic handlers
res.writeHead(404);
res.end("Not found");
});
await new Promise((resolve) => server.listen(port, resolve));
return server;
}
protected async stopServer(): Promise {
await new Promise((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`:
```typescript
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`](https://github.com/VoltAgent/voltagent/tree/main/packages/server-hono).
---
## Documentation
- [VoltAgent Documentation](https://voltagent.dev/docs/)
- [Agent Overview](https://voltagent.dev/docs/agents/overview/)
- [MCP Integration](https://voltagent.dev/docs/agents/mcp/)
## License
Licensed under the MIT License, Copyright © 2026-present VoltAgent.