assistants / Next Assistants

Next-Assistants

Integrate OpenAI assistants into Next.js apps.

Getting Started

To integrate Next-Assistants into your Next.js application, follow these steps:

Prerequisites

  • Ensure you have Next.js (version 13 or later) set up in your project and are using the app router.
  • An OpenAI API key. Sign up and get your API key from OpenAI.
  • openai sdk >= 14.16.2

Installation

npm install next-assistants
# or
yarn add next-assistants
# or
pnpm add next-assistants

Server-Side Setup

Route Handlers

Create a route handler with this file structure: ./app/api/ai/assistants/[assistantId]/[...params]/route.ts.

// ./app/api/ai/assistants/[assistantId]/[...params]/route.ts
import { createAssistantRoutes } from "next-assistants/server";
 
const handler = createAssistantRoutes({ debug: true });
 
export async function GET(req, context) {
    return await handler(req, context);
}
 
export async function POST(req, context) {
    return await handler(req, context);
}

Client-Side Usage

next-assistants/client

next-assistants/client provides a hook for interacting with AI assistants on the client-side. It handles the creation of threads, sending messages, polling for updates and tracking the status of the assistant.

Features

  • Custom React Hook (useThread): Manage AI conversations with functions for sending messages, creating threads, and tracking status.
  • Real-Time Conversation Handling: Support for real-time updates and asynchronous operations.
  • Error and Loading State Management: Built-in handling of loading and error states.

Usage Example

Import useThread from next-assistants/client to manage conversation threads with an assistant.

import { useState } from "react";
import { useThread } from "next-assistants/client";
 
function AssistantComponent() {
    const [prompt, setPrompt] = useState("");
  const { messages, sendMessage, loading } = useThread({
    assistantId: "your-assistant-id",
    threadId: "optional-thread-id",
    functions: {
      generate_image: async ({ image_prompt }) => {
        try {
          const response = await fetch("/api/ai/dalle/generate", {
            method: "POST",
            body: JSON.stringify({
              prompt: image_prompt
            })
          })
 
          const { data } = await response.json()
 
          return data?.[0]?.url
        } catch (error) {
          console.log(error)
          throw new Error("could not generate image")
        }
      }
    }
  });
 
  const handleSubmit = () => {
        sendMessage(prompt);
      setPrompt("");
    };
 
  return (
        <div>
        <input
          value={prompt}
          onChange={(e) => setPrompt(e.target.value)}
          disabled={loading}
        />
        <button onClick={handleSubmit} disabled={loading}>Send</button>
        <div>
          {messages.map((msg, index) => (
              <p key={index}>{msg.content}</p>
          ))}
        </div>
      </div>
    );
  }

API Reference

useThread Hook

Arguments

ArgumentTypeDescription
assistantIdstringThe identifier for the AI assistant.
threadIdstring(Optional) Identifier for a specific thread.
functionsobject(Optional) Custom functions for extended capabilities.

Returns

  • Type: Function

  • Description: Manages conversation threads with an AI assistant.

    • createNewThread: Function to initialize a new conversation thread.
    • thread: The current thread object.
    • messages: Array of messages in the current thread.
    • sendMessage: Function to send a message to the assistant.
    • startRun: Function to begin an AI run based on provided input.
    • error: Current error state.
    • loading: Indicates if the hook is in a loading state.
    • runStatus: Status of the current AI run.
    • initializing: Indicates if the hook is initializing.

createAssistantRoutes

Creates a handler for routing API requests related to assistants, threads, runs, and file operations.

Arguments

ArgumentTypeDescription
debugbooleanWhether to log debug information. Optional.

Returns

  • Type: Function
  • Description: An async function that handles incoming Next.js App router requests and returns an appropriate response.

License

MIT