Next.JS

Erfahren Sie, wie Sie eine Webanwendung für Sprachgespräche mit ElevenLabs-KI-Agenten erstellen

Dieses Tutorial zeigt Ihnen, wie Sie einen Webclient erstellen, der mit einem ElevenLabs-Agenten interagieren kann. Sie lernen, Echtzeit-Sprachunterhaltungen zu implementieren, damit Nutzer mit einem KI-Agenten sprechen können, der zuhören, verstehen und mithilfe von Sprachsynthese natürlich antworten kann.

Was Sie benötigen

Einen ElevenLabs-Agenten, den Sie gemäß dieser Anleitung erstellt haben
npm, installiert auf Ihrem lokalen System
Wir verwenden in diesem Tutorial Typescript, Sie können aber auch Javascript verwenden.

Sie suchen ein vollständiges Beispiel? Sehen Sie sich unsere Next.js-Demo auf GitHub an.

Einrichtung

Neues Next.js-Projekt erstellen

Öffnen Sie ein Terminal und führen Sie den folgenden Befehl aus:

npm create next-app my-conversational-agent

Sie werden einige Fragen zur Einrichtung Ihres Projekts beantworten. Für dieses Tutorial verwenden wir die Standardvorschläge.

Zum Projektverzeichnis wechseln

cd my-conversational-agent

ElevenLabs-Abhängigkeit installieren

npm install @elevenlabs/react

Einrichtung testen

Führen Sie den folgenden Befehl aus, um den Entwicklungsserver zu starten, und öffnen Sie die bereitgestellte URL in Ihrem Browser:

npm run dev

ElevenLabs Agents implementieren

Unterhaltungskomponente erstellen

Erstellen Sie eine neue Datei app/components/conversation.tsx:

app/components/conversation.tsx

'use client';
import { useConversation } from '@elevenlabs/react';
import { useCallback } from 'react';
export function Conversation() {
  const conversation = useConversation({
    onConnect: () => console.log('Connected'),
    onDisconnect: () => console.log('Disconnected'),
    onMessage: (message) => console.log('Message:', message),
    onError: (error) => console.error('Error:', error),
  });
  const startConversation = useCallback(async () => {
    try {
      // Request microphone permission
      await navigator.mediaDevices.getUserMedia({ audio: true });
      // Start the conversation with your agent
      await conversation.startSession({
        agentId: 'YOUR_AGENT_ID', // Replace with your agent ID
        userId: 'YOUR_CUSTOMER_USER_ID', // Optional field for tracking your end user IDs
      });
    } catch (error) {
      console.error('Failed to start conversation:', error);
    }
  }, [conversation]);
  const stopConversation = useCallback(async () => {
    await conversation.endSession();
  }, [conversation]);
  return (
    <div className="flex flex-col items-center gap-4">
      <div className="flex gap-2">
        <button
          onClick={startConversation}
          disabled={conversation.status === 'connected'}
          className="px-4 py-2 bg-blue-500 text-white rounded disabled:bg-gray-300"
        >
          Start Conversation
        </button>
        <button
          onClick={stopConversation}
          disabled={conversation.status !== 'connected'}
          className="px-4 py-2 bg-red-500 text-white rounded disabled:bg-gray-300"
        >
          Stop Conversation
        </button>
      </div>
      <div className="flex flex-col items-center">
        <p>Status: {conversation.status}</p>
        <p>Agent is {conversation.isSpeaking ? 'speaking' : 'listening'}</p>
      </div>
    </div>
  );
}

Hauptseite aktualisieren

Ersetzen Sie den Inhalt von app/page.tsx durch:

app/page.tsx

'use client';
import { ConversationProvider } from '@elevenlabs/react';
import { Conversation } from './components/conversation';
export default function Home() {
  return (
    <ConversationProvider>
      <main className="flex min-h-screen flex-col items-center justify-between p-24">
        <div className="z-10 max-w-5xl w-full items-center justify-between font-mono text-sm">
          <h1 className="text-4xl font-bold mb-8 text-center">
            ElevenLabs Agents
          </h1>
          <Conversation />
        </div>
      </main>
    </ConversationProvider>
  );
}

(Optional) Agenten mit einer signierten URL authentifizieren

Dieser Authentifizierungsschritt ist nur für private Agenten erforderlich. Wenn Sie einen öffentlichen Agenten verwenden, können Sie diesen Abschnitt überspringen und die agentId direkt im startSession-Aufruf verwenden.

Wenn Sie einen privaten Agenten verwenden, der eine Authentifizierung erfordert, müssen Sie auf Ihrem Server eine signierte URL generieren. Dieser Abschnitt erklärt die Einrichtung.

Was Sie benötigen

Ein ElevenLabs-Konto und einen API-Schlüssel. Registrieren Sie sich hier.

Umgebungsvariablen erstellen

Erstellen Sie im Stammverzeichnis Ihres Projekts eine .env.local-Datei:

.env.local

ELEVENLABS_API_KEY=your-api-key-here
NEXT_PUBLIC_AGENT_ID=your-agent-id-here

Fügen Sie .env.local unbedingt zu Ihrer .gitignore-Datei hinzu, damit sensible Zugangsdaten nicht versehentlich in die Versionsverwaltung übertragen werden.
Legen Sie Ihren API-Schlüssel niemals im clientseitigen Code offen. Bewahren Sie ihn immer sicher auf dem Server auf.

API-Route erstellen

Erstellen Sie eine neue Datei app/api/get-signed-url/route.ts:

app/api/get-signed-url/route.ts

import { NextResponse } from 'next/server';
export async function GET() {
  try {
    const response = await fetch(
      `https://api.elevenlabs.io/v1/convai/conversation/get-signed-url?agent_id=${process.env.NEXT_PUBLIC_AGENT_ID}`,
      {
        headers: {
          'xi-api-key': process.env.ELEVENLABS_API_KEY!,
        },
      }
    );
    if (!response.ok) {
      throw new Error('Failed to get signed URL');
    }
    const data = await response.json();
    return NextResponse.json({ signedUrl: data.signed_url });
  } catch (error) {
    return NextResponse.json(
      { error: 'Failed to generate signed URL' },
      { status: 500 }
    );
  }
}

Conversation-Komponente aktualisieren

Ändern Sie Ihre conversation.tsx, um die signierte URL abzurufen und zu verwenden:

app/components/conversation.tsx

// ... existing imports ...
export function Conversation() {
  // ... existing conversation setup ...
  const getSignedUrl = async (): Promise<string> => {
    const response = await fetch("/api/get-signed-url");
    if (!response.ok) {
      throw new Error(`Failed to get signed url: ${response.statusText}`);
    }
    const { signedUrl } = await response.json();
    return signedUrl;
  };
  const startConversation = useCallback(async () => {
    try {
      // Request microphone permission
      await navigator.mediaDevices.getUserMedia({ audio: true });
      const signedUrl = await getSignedUrl();
      // Start the conversation with your signed url
      await conversation.startSession({
        signedUrl,
      });
    } catch (error) {
      console.error('Failed to start conversation:', error);
    }
  }, [conversation]);
  // ... rest of the component ...
}

Signierte URLs laufen nach kurzer Zeit ab. Unterhaltungen, die vor dem Ablauf gestartet wurden, werden jedoch ohne Unterbrechung fortgesetzt. Implementieren Sie in einer Produktionsumgebung eine geeignete Fehlerbehandlung und Logik zum Aktualisieren der URL, um neue Unterhaltungen zu starten.

Nächste Schritte

Nachdem Sie jetzt eine grundlegende Implementierung haben, können Sie:

Visuelles Feedback für Sprachaktivität hinzufügen
Fehlerbehandlung und Wiederholungslogik implementieren
Eine Anzeige für den Chatverlauf hinzufügen
Die Benutzeroberfläche an Ihre Marke anpassen

Weitere erweiterte Funktionen und Anpassungsoptionen finden Sie im Paket @elevenlabs/react.