This example demonstrates how to integrate VoltAgent with a NestJS application as a middleware, serving the VoltAgent console on the same port as your NestJS app. It shows how to use agents directly in NestJS services while having the VoltAgent developer console integrated at /voltagent/*.

• Middleware Integration: VoltAgent console runs on the same port as NestJS at /voltagent/*
• WebSocket Support: Real-time logs and observability via WebSocket
• Dependency Injection: Proper NestJS DI pattern for agents
• Single Port: Both NestJS app and VoltAgent console on port 3000
• Multiple Endpoints: REST API endpoints using agents
• Text Processing: Example agent with custom tools

• NestJS App: Runs on port 3000 (configurable via PORT)
• VoltAgent Console: Integrated at http://localhost:3000/voltagent
• WebSocket: Available at ws://localhost:3000/voltagent/ws
• Agents: Injected into controllers via NestJS DI

• Node.js 18+ and pnpm
• OpenAI API key

# Install dependencies
pnpm install

# Copy environment file
cp .env.example .env

# Add your OpenAI API key to .env

# Development mode with watch
pnpm start:dev

# Production mode
pnpm build
pnpm start:prod

The application will start on a single port with all services:

🚀 NestJS Application is running on: http://localhost:3000
📊 VoltAgent Console is available at: http://localhost:3000/voltagent
   - Swagger UI: http://localhost:3000/voltagent/ui
   - OpenAPI Docs: http://localhost:3000/voltagent/doc
🔌 VoltAgent WebSocket: ws://localhost:3000/voltagent/ws
   - Logs stream: ws://localhost:3000/voltagent/ws/logs
   - Observability: ws://localhost:3000/voltagent/ws/observability

• GET / - Welcome message
• POST /api/process - Process text with the agent

  curl -X POST http://localhost:3000/api/process \
    -H "Content-Type: application/json" \
    -d '{"text": "hello world"}'

• GET /voltagent - Console landing page
• GET /voltagent/ui - Swagger UI (development only)
• GET /voltagent/doc - OpenAPI documentation
• GET /voltagent/agents - List all agents
• POST /voltagent/agents/:agentName/generateText - Generate text with an agent
• WebSocket endpoints for real-time logs and observability

src/
├── app.module.ts                    # Main app module
├── app.controller.ts                # Example controller using agents
├── main.ts                          # NestJS bootstrap with WebSocket setup
└── voltagent/
    ├── voltagent.module.ts          # VoltAgent module with middleware config
    ├── voltagent.service.ts         # Agent initialization and management
    ├── voltagent.middleware.ts      # HTTP middleware for console routing
    └── voltagent-websocket.setup.ts # WebSocket integration setup

VoltAgent console is integrated as NestJS middleware, allowing it to run on the same port:

// In VoltAgentModule
configure(consumer: MiddlewareConsumer) {
  consumer
    .apply(VoltAgentMiddleware)
    .forRoutes('/voltagent*');
}

WebSocket support is configured in main.ts before the app starts listening:

const voltAgentService = app.get(VoltAgentService);
setupVoltAgentWebSocket(app, voltAgentService, "/voltagent/ws");

Inject the VoltAgentService into any controller or service:

@Controller("api")
export class AppController {
  constructor(private readonly voltAgentService: VoltAgentService) {}

  @Post("process")
  async process(@Body() body: { text: string }): Promise<any> {
    const result = await this.voltAgentService.textAgent.generateText(`Process: ${body.text}`);
    return { result: result.text };
  }
}

The VoltAgent console provides:

• Real-time agent execution logs via WebSocket
• Tool usage monitoring
• Performance metrics
• OpenAPI documentation with Swagger UI
• Live observability streams

• OPENAI_API_KEY - Your OpenAI API key (required)
• PORT - Application port (default: 3000)
• NODE_ENV - Environment (development/production)

With middleware integration, you access VoltAgent console via:

• Landing Page: http://localhost:3000/voltagent
• Swagger UI: http://localhost:3000/voltagent/ui
• Agents API: http://localhost:3000/voltagent/agents

• ws://localhost:3000/voltagent/ws - Test connection
• ws://localhost:3000/voltagent/ws/logs - Real-time logs with filters
• ws://localhost:3000/voltagent/ws/observability - Observability stream

# Watch mode
pnpm start:dev

# Type checking
pnpm typecheck

# Linting
pnpm lint
pnpm lint:fix

1. Request comes to /voltagent/*
2. NestJS middleware intercepts it
3. Converts Express Request → Web Standard Request
4. Calls Hono app's fetch() method
5. Converts Web Response → Express Response

1. WebSocket upgrade request comes to /voltagent/ws/*
2. NestJS HTTP server emits 'upgrade' event
3. Custom handler strips prefix and routes to VoltAgent
4. VoltAgent's WebSocket handlers process the connection

✅ Single Port - Simplifies deployment and firewall rules ✅ Unified App - Everything in one process ✅ NestJS Guards - Can protect console with your existing auth ✅ No Port Conflicts - No need to manage multiple ports ✅ Easy Deployment - Single container, single service

Use NestJS guards to restrict access to the console:

@Injectable()
export class VoltAgentAuthGuard implements CanActivate {
  canActivate(context: ExecutionContext): boolean {
    // Only allow internal network in production
    if (process.env.NODE_ENV === "production") {
      const req = context.switchToHttp().getRequest();
      const ip = req.ip;
      return ip.startsWith("10.") || ip.startsWith("192.168.");
    }
    return true;
  }
}

// Apply to middleware
consumer.apply(VoltAgentAuthGuard, VoltAgentMiddleware).forRoutes("/voltagent*");

If you prefer VoltAgent console on a separate port (original approach), see the NestJS integration docs for the separate port configuration.

• VoltAgent Documentation
• NestJS Integration Guide
• Agent Documentation
• NestJS Documentation

MIT