Skip to main content

VoltAgent Server API

VoltAgent provides a flexible HTTP API for interacting with agents and workflows. The server architecture is framework-agnostic, allowing you to use different server implementations or create your own.

Architecture​

VoltAgent 1.x introduces a pluggable server architecture:

  • @voltagent/server-core - Framework-agnostic core with route definitions, handlers, and base provider
  • @voltagent/server-hono - Official server implementation using Hono (recommended)

Quick Start​

import { Agent, VoltAgent } from "@voltagent/core";
import { honoServer } from "@voltagent/server-hono";
import { openai } from "@ai-sdk/openai";

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

new VoltAgent({
  agents: { agent },
  server: honoServer({
    port: 3141,
    enableSwaggerUI: true,
  }),
});

The server starts automatically and displays:

══════════════════════════════════════════════════
  VOLTAGENT SERVER STARTED SUCCESSFULLY
══════════════════════════════════════════════════
  ✓ HTTP Server:  http://localhost:3141
  ✓ Swagger UI:   http://localhost:3141/ui
══════════════════════════════════════════════════

API Documentation​

Interactive Documentation​

Access Swagger UI at http://localhost:3141/ui to explore and test all endpoints directly in your browser.

Swagger UI Demo

OpenAPI Specification​

Get the raw OpenAPI 3.1 spec at http://localhost:3141/doc for code generation and tooling.

Core Endpoints​

Agent Endpoints​

  • GET /agents - List all agents
  • POST /agents/:id/text - Generate text response
  • POST /agents/:id/stream - Stream text response (SSE)
  • POST /agents/:id/object - Generate structured object
  • POST /agents/:id/stream-object - Stream structured object (SSE)
  • GET /agents/:id/history - Get agent execution history

Workflow Endpoints​

  • GET /workflows - List all workflows
  • POST /workflows/:id/execute - Execute workflow
  • POST /workflows/:id/stream - Stream workflow execution (SSE)
  • POST /workflows/:id/executions/:executionId/suspend - Suspend execution
  • POST /workflows/:id/executions/:executionId/resume - Resume execution
  • GET /workflows/:id/executions/:executionId/state - Get execution state

Observability & Logs​

  • POST /setup-observability - Configure .env with VoltAgent keys
  • GET /observability/status - Observability status
  • GET /observability/traces - List traces
  • GET /observability/traces/:traceId - Get trace by ID
  • GET /observability/spans/:spanId - Get span details
  • GET /observability/traces/:traceId/logs - Logs for a trace
  • GET /observability/spans/:spanId/logs - Logs for a span
  • GET /observability/logs - Query logs (filters)
  • GET /api/logs - System logs (filters)

System​

  • GET /updates - Check available updates
  • POST /updates/install - Install updates (all or a specific package)

Documentation Sections​

Next Steps​

  1. Explore the Server Architecture to understand how VoltAgent servers work
  2. Check Agent Endpoints for detailed API usage
  3. Visit /ui on your running server for interactive API exploration

Table of Contents