Integrating VoltAgent with Next.js

This guide walks you through setting up VoltAgent in a Next.js application. We'll build a simple AI calculator example using Server Actions and the Vercel AI SDK.

Quick Start with Example

If you prefer to start directly with the completed example project, you can create it using the following command:

npm create voltagent-app@latest -- --example with-nextjs

This command will scaffold the entire Next.js example project described in this guide.

Create a New Next.js Project

Start by creating a new Next.js project using the latest version:

npx create-next-app@latest my-voltagent-app
cd my-voltagent-app

Follow the prompts, selecting TypeScript and App Router.

Install VoltAgent Dependencies

Install the necessary VoltAgent packages and the Vercel AI SDK provider:

npm install @voltagent/core @voltagent/vercel-ai @voltagent/cli @ai-sdk/openai zod

• @voltagent/core: The core VoltAgent library.
• @voltagent/vercel-ai: Integrates VoltAgent with the Vercel AI SDK.
• @ai-sdk/openai: The AI SDK provider for OpenAI (or your preferred LLM provider).
• @voltagent/cli: The command-line interface for VoltAgent tasks (e.g., managing updates).
• zod: Required by the Vercel AI SDK for schema validation.

Configure next.config.js

Next.js might try to bundle server-side packages by default. To prevent issues with VoltAgent, you need to mark its packages as external in your next.config.mjs (or .js / .ts) file:

next.config.mjs // or next.config.ts

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  experimental: {
    // Mark VoltAgent packages as external
    serverComponentsExternalPackages: ["@voltagent/*"],
    // If using other packages that need to run externally (like npm-check-updates in the example)
    // add them here too.
    // serverComponentsExternalPackages: ["@voltagent/*", "another-package"],
  },
};

export default nextConfig;

Note: The property was serverExternalPackages in older Next.js versions, but changed to experimental.serverComponentsExternalPackages. Ensure you use the correct one for your Next.js version.

Initialize VoltAgent

Create a file to initialize the VoltAgent agent, for example, voltagent/index.ts in your project root:

voltagent/index.ts

import { VoltAgent } from "@voltagent/core";
import { VercelAIManager } from "@voltagent/vercel-ai";
import { openai } from "@ai-sdk/openai"; // Or your preferred provider

export const agent = new VoltAgent({
  provider: "vercel-ai", // Specify the Vercel AI provider
  manager: new VercelAIManager({
    model: openai("gpt-4o"), // Configure your desired model
  }),
  functions: [
    // Add any VoltAgent functions/tools here if needed
  ],
});

Remember to set up your environment variables (e.g., OPENAI_API_KEY) in a .env.local file. Create a .env.local file in your project root if it doesn't exist, and add your necessary API keys:

.env.local

OPENAI_API_KEY="your-openai-api-key-here"
# Add other environment variables if needed

Create a Server Action

Define a Server Action to interact with the VoltAgent agent. Create app/actions.ts:

app/actions.ts

"use server";

import { agent } from "@/voltagent"; // Adjust path if needed

export async function calculateExpression(expression: string) {
  const result = await agent.generateText(
    `Calculate ${expression}. Only respond with the numeric result.`
  );

  return result.text;
}

Build the UI Component

Create a client component to take user input and display the result. Create app/components/calculator.tsx:

app/components/calculator.tsx

"use client";

import { useState } from "react";
import { calculateExpression } from "../actions";

export function Calculator() {
  const [result, setResult] = useState<string | null>(null);
  const [loading, setLoading] = useState(false);
  const [expression, setExpression] = useState("");

  async function handleSubmit(formData: FormData) {
    const expr = formData.get("expression") as string;
    if (!expr.trim()) return;

    setLoading(true);
    try {
      const calcResult = await calculateExpression(expr);
      setResult(calcResult);
      setExpression(expr);
    } catch (error) {
      console.error("Calculation error:", error);
      setResult("Error calculating expression");
    } finally {
      setLoading(false);
    }
  }

  return (
    <div>
      <h2>AI Calculator</h2>
      <form action={handleSubmit}>
        <label htmlFor="expression">Enter calculation:</label>
        <input
          id="expression"
          name="expression"
          type="text"
          placeholder="E.g. (5 + 3) * 2"
          required
        />
        <button type="submit" disabled={loading}>
          {loading ? "Calculating..." : "Calculate"}
        </button>
      </form>

      {result && (
        <div>
          <h3>Result:</h3>
          <p>{expression} = {result}</p>
        </div>
      )}
    </div>
  );
}

(Styling omitted for brevity. Refer to the example project for full styling)

Use the Component

Finally, import and use the Calculator component in your main page (app/page.tsx):

app/page.tsx

import { Calculator } from "./components/calculator";

export default function HomePage() {
  return (
    <main>
      <h1>VoltAgent Next.js Example</h1>
      <Calculator />
    </main>
  );
}

Now you can run your Next.js development server (npm run dev) and test the AI calculator! This demonstrates a basic integration of VoltAgent within a Next.js application using Server Actions.