From d167303052a092bac72a782dc248773b6138534a Mon Sep 17 00:00:00 2001 From: Varun Nuthalapati Date: Mon, 22 Jun 2026 21:33:01 -0700 Subject: [PATCH 1/2] docs(server-hono): add README with usage and configuration reference --- .changeset/server-hono-readme.md | 5 ++ packages/server-hono/README.md | 132 +++++++++++++++++++++++++++++++ 2 files changed, 137 insertions(+) create mode 100644 .changeset/server-hono-readme.md create mode 100644 packages/server-hono/README.md diff --git a/.changeset/server-hono-readme.md b/.changeset/server-hono-readme.md new file mode 100644 index 000000000..3941d8baf --- /dev/null +++ b/.changeset/server-hono-readme.md @@ -0,0 +1,5 @@ +--- +"@voltagent/server-hono": patch +--- + +Add README documentation diff --git a/packages/server-hono/README.md b/packages/server-hono/README.md new file mode 100644 index 000000000..0f80860d3 --- /dev/null +++ b/packages/server-hono/README.md @@ -0,0 +1,132 @@ +
+ +voltagent + + +

+AI Agent Engineering Platform +

+ +
+ Home Page | + Documentation | + Examples +
+
+ +
+ +
+ +[![GitHub issues](https://img.shields.io/github/issues/voltagent/voltagent)](https://github.com/voltagent/voltagent/issues) +[![GitHub pull requests](https://img.shields.io/github/issues-pr/voltagent/voltagent)](https://github.com/voltagent/voltagent/pulls) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) +[![npm version](https://img.shields.io/npm/v/@voltagent/server-hono.svg)](https://www.npmjs.com/package/@voltagent/server-hono) +[![npm downloads](https://img.shields.io/npm/dm/@voltagent/server-hono.svg)](https://www.npmjs.com/package/@voltagent/server-hono) +[![Discord](https://img.shields.io/discord/1361559153780195478.svg?label=&logo=discord&logoColor=ffffff&color=7389D8&labelColor=6A7EC2)](https://s.voltagent.dev/discord) + +
+ +## @voltagent/server-hono + +The default VoltAgent server adapter, built on [Hono](https://hono.dev/). It wires up the routes, handlers, WebSocket support, and OpenAPI/Swagger UI provided by [`@voltagent/server-core`](https://github.com/VoltAgent/voltagent/tree/main/packages/server-core) into a runnable HTTP server. + +--- + +## Install + +```bash +npm install @voltagent/server-hono +# or +yarn add @voltagent/server-hono +# or +pnpm add @voltagent/server-hono +``` + +## Usage + +```typescript +import { VoltAgent, Agent } from "@voltagent/core"; +import { honoServer } from "@voltagent/server-hono"; +import { openai } from "@ai-sdk/openai"; + +const agent = new Agent({ + name: "my-agent", + instructions: "A helpful assistant", + model: openai("gpt-4o-mini"), +}); + +new VoltAgent({ + agents: { agent }, + server: honoServer(), +}); +``` + +This starts an HTTP server exposing the agent/workflow/tool/memory/observability routes defined in `@voltagent/server-core`, along with a Swagger UI for exploring the API. + +## Configuration + +`honoServer(config)` accepts a `HonoServerConfig`: + +| Option | Type | Default | Description | +| ----------------- | ------------------------------ | --------------------- | --------------------------------------------------------------------------------------------------------------------------------- | +| `port` | `number` | `3141` | Port to listen on | +| `hostname` | `string` | `"0.0.0.0"` | Hostname to bind the server to | +| `cors` | `CORSOptions \| false` | allows all origins | CORS configuration, or `false` to disable default CORS | +| `enableSwaggerUI` | `boolean` | `true` in development | Enable the `/ui` Swagger UI route | +| `resumableStream` | `{ adapter, defaultEnabled? }` | — | Configure a [`@voltagent/resumable-streams`](https://github.com/VoltAgent/voltagent/tree/main/packages/resumable-streams) adapter | +| `configureApp` | `(app: Hono) => void` | — | Register custom routes/middleware directly on the Hono app | + +```typescript +new VoltAgent({ + agents: { agent }, + server: honoServer({ + port: 8080, + cors: { + origin: "https://example.com", + allowMethods: ["GET", "POST", "OPTIONS"], + }, + configureApp: (app) => { + app.get("/healthz", (c) => c.text("ok")); + }, + }), +}); +``` + +## Authentication + +`jwtAuth` provides a ready-to-use JWT `AuthProvider`: + +```typescript +import { jwtAuth } from "@voltagent/server-hono"; + +const auth = jwtAuth({ + secret: process.env.JWT_SECRET, +}); + +new VoltAgent({ + agents: { agent }, + server: honoServer({ auth }), +}); +``` + +## Custom Endpoints & App Factory + +- `extractCustomEndpoints`, `getEnhancedOpenApiDoc` — helpers for registering custom routes and extending the generated OpenAPI document. +- `createVoltAgentApp` — builds the underlying Hono app instance for embedding into existing Node.js servers (e.g. NestJS, Express) instead of using `honoServer` directly. + +```typescript +import { createVoltAgentApp } from "@voltagent/server-hono"; + +const app = createVoltAgentApp(deps, config); +``` + +## Documentation + +- [VoltAgent Documentation](https://voltagent.dev/docs/) +- [`@voltagent/server-core`](https://github.com/VoltAgent/voltagent/tree/main/packages/server-core) — the framework-agnostic server core this adapter builds on +- [Agent Overview](https://voltagent.dev/docs/agents/overview/) + +## License + +Licensed under the MIT License, Copyright © 2026-present VoltAgent. From 3a8efd94e2819f71c532c9a1e53be35c880e76fe Mon Sep 17 00:00:00 2001 From: Varun Nuthalapati Date: Sat, 27 Jun 2026 19:37:05 -0700 Subject: [PATCH 2/2] docs(server-hono): add auth/authNext to config table; expand createVoltAgentApp example Co-Authored-By: Claude Sonnet 4.6 --- packages/server-hono/README.md | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/packages/server-hono/README.md b/packages/server-hono/README.md index 0f80860d3..4a2377aa1 100644 --- a/packages/server-hono/README.md +++ b/packages/server-hono/README.md @@ -76,6 +76,8 @@ This starts an HTTP server exposing the agent/workflow/tool/memory/observability | `enableSwaggerUI` | `boolean` | `true` in development | Enable the `/ui` Swagger UI route | | `resumableStream` | `{ adapter, defaultEnabled? }` | — | Configure a [`@voltagent/resumable-streams`](https://github.com/VoltAgent/voltagent/tree/main/packages/resumable-streams) adapter | | `configureApp` | `(app: Hono) => void` | — | Register custom routes/middleware directly on the Hono app | +| `auth` | `AuthProvider` | — | Authentication provider for protecting execution endpoints. **Deprecated** — use `authNext` instead | +| `authNext` | `AuthNextConfig` | — | Next-gen authentication policy. All routes are protected by default; configure `publicRoutes` and console access via the config | ```typescript new VoltAgent({ @@ -117,8 +119,25 @@ new VoltAgent({ ```typescript import { createVoltAgentApp } from "@voltagent/server-hono"; +import type { ServerProviderDeps } from "@voltagent/core"; + +// `deps` is the ServerProviderDeps object passed in by VoltAgent (agents, workflows, etc.) +// `config` is a HonoServerConfig — same options as honoServer() +// The function is async and returns { app } — a configured Hono instance + +// Example: embed into an existing Node.js server +async function bootstrap(deps: ServerProviderDeps) { + const { app } = await createVoltAgentApp(deps, { + port: 3141, + enableSwaggerUI: false, + configureApp: (honoApp) => { + honoApp.get("/healthz", (c) => c.text("ok")); + }, + }); -const app = createVoltAgentApp(deps, config); + // `app` is a plain Hono app — mount it, serve it, or pass it to your framework + return app; +} ``` ## Documentation