Neocortex Logo

Come aggiungere un personaggio IA parlante al tuo sito web

Aggiungi un personaggio IA parlante a qualsiasi sito: installa l'SDK Web di Neocortex, tieni la chiave API sul tuo server, inserisci un elemento di chat vocale e gestisci le azioni.

Sercan AltundasFounder of Neocortex

· 7 min di lettura

Aggiungi un personaggio IA parlante a qualsiasi sito: installa l'SDK Web di Neocortex, tieni la chiave API sul tuo server, inserisci un elemento di chat vocale e gestisci le azioni.

Un personaggio per il sito è una guida, un presentatore o un assistente di negozio con cui i visitatori possono parlare con parole loro, con una personalità e una voce invece di un generico fumetto di chat. Questa guida mostra come aggiungerne uno a qualsiasi sito con l'SDK Web di Neocortex: poche righe sul server, un elemento nella pagina e azioni opzionali che permettono al personaggio di fare delle cose.

Cosa costruirai

Un personaggio nella tua pagina che:

  • risponde a domande scritte o parlate con la propria voce
  • conosce i tuoi contenuti, da una base di conoscenza che carichi
  • può eseguire azioni sulla pagina, come aprire un prodotto o avviare un tour
  • non espone mai la tua chiave API al browser

Cosa ti serve

  • Un account Neocortex, una chiave API e un personaggio dalla dashboard
  • Un server che esegue Node 20 o successivo, oppure Cloudflare Workers, Bun o Deno
  • Una pagina servita in HTTPS, perché i browser consentono il microfono solo sulle pagine sicure

Passo 1: progetta il personaggio

Nell'editor di Neocortex, dai al personaggio una personalità, una voce e una base di conoscenza con le pagine del tuo prodotto, le FAQ o le note del tour. Testalo nel browser finché suona giusto: il test nell'editor è incluso in ogni piano. Copia l'ID del personaggio dalla dashboard.

Passo 2: installa l'SDK

Esegui npm install @neocortex-link/web nel progetto del tuo sito.

Passo 3: aggiungi il proxy al tuo server

Le chiavi API di Neocortex sono segrete. Chiunque legga una chiave dal JavaScript della tua pagina può far salire l'uso del tuo account, quindi l'SDK include un piccolo gestore lato server che custodisce la chiave. Verifica anche chi sta parlando e consente solo i personaggi che elenchi.

In un'app Next.js, crea app/api/neocortex/[...path]/route.ts:

import { createNeocortexHandler } from "@neocortex-link/web/server";
import { auth } from "@/auth";

const handler = createNeocortexHandler({
  apiKey: process.env.NEOCORTEX_API_KEY!,
  characters: ["your-character-id"],
  authorize: async () => {
    const session = await auth();
    return session?.user ? { id: session.user.id } : null;
  },
});

export { handler as GET, handler as POST, handler as OPTIONS };

authorize restituisce il visitatore come { id }, oppure null per rifiutare. Quell'id diventa il playerId del personaggio, così ogni visitatore ha la sua conversazione. Per Express, avvolgi lo stesso gestore in toNodeHandler e montalo su /api/neocortex. I siti senza login possono assegnare a ogni visitatore un id stabile in un cookie firmato.

Passo 4: inserisci il personaggio nella pagina

Carica l'interfaccia una volta con import "@neocortex-link/web/ui/auto" (oppure da un tag script CDN se il tuo sito non usa un bundler), poi posiziona l'elemento dove deve comparire il personaggio:

<neocortex-chat endpoint="/api/neocortex" character-id="your-character-id" voice></neocortex-chat>

La chat include una casella di testo e l'input del microfono. L'attributo voice aggiunge le risposte parlate: ogni battuta viene riprodotta in streaming come voce, e la successiva viene richiesta mentre quella corrente suona. Aggiungi push-to-talk se i visitatori devono tenere premuto il pulsante mentre parlano, oppure mic="false" per il solo testo.

Gli elementi sono Web Component standard, quindi funzionano con React, Vue, Svelte, Angular o HTML semplice, e puoi cambiarne lo stile con le proprietà CSS personalizzate in modalità chiara o scura. Ci sono anche elementi per una chat di gruppo con più personaggi (piani Pro e Team) e per un conduttore di quiz (piano Team).

Passo 5: lascia che il personaggio agisca

Definisci le azioni nell'editor, come OPEN_PRODUCT o START_TOUR, poi gestiscile nella pagina:

const chat = document.querySelector("neocortex-chat");
chat.agent.registerAction("OPEN_PRODUCT", (action) => openProduct(action.targetId));

openProduct è una tua funzione. Il personaggio decide quando un'azione si adatta alla conversazione, e il tuo codice decide cosa fa.

Idee per personaggi sul sito

  • Una guida al prodotto in un configuratore 3D che spiega le opzioni e cambia i colori quando richiesto.
  • Un presentatore di evento che risponde alle domande sul programma e indirizza i visitatori al palco giusto.
  • Un personaggio di museo o di marchio che racconta storie dal tuo archivio con la sua voce.
  • La landing page di un gioco dove i visitatori possono parlare con i personaggi del gioco prima di acquistarlo.

Le nostre guide sui casi d'uso approfondiscono guide IA per negozi web 3D e presentatori IA per eventi virtuali.

Problemi comuni

  • Il microfono non parte. I browser richiedono HTTPS e un clic o un tocco prima di registrare. Prova sul tuo dominio reale, non su un'anteprima HTTP semplice.
  • 401 o 403 dall'endpoint. authorize ha restituito null, oppure l'ID del personaggio non è nell'elenco characters.
  • La chiave è finita nel browser. Non passarla mai al codice client. Solo il gestore lato server deve leggere NEOCORTEX_API_KEY.

Prossimi passi

Per i motori di gioco invece che per i siti, inizia da come aggiungere un personaggio IA al tuo gioco Unity. Per capire il lato vocale, leggi come funziona la pipeline vocale degli NPC IA. Ogni tutorial della serie è nella guida alla costruzione di NPC IA, e la configurazione completa è nella documentazione dell'SDK Web.

Domande frequenti

Come aggiungo un personaggio IA con voce al mio sito?

Installa l'SDK Web di Neocortex, aggiungi il suo piccolo proxy al tuo server così la chiave API resta privata, poi inserisci un elemento neocortex-chat nella pagina con l'attributo voice. I visitatori possono scrivere o parlare, e il personaggio risponde a voce.

Posso mettere un chatbot IA sul mio sito senza esporre la mia chiave API?

Sì. L'SDK Web di Neocortex include un gestore lato server che custodisce la chiave, verifica chi sta parlando e consente solo i personaggi che elenchi. Il browser parla sempre e solo con il tuo endpoint.

Funziona con React, Vue o WordPress?

L'interfaccia della chat è composta da Web Component standard, quindi funziona con React, Vue, Svelte, Angular e HTML semplice. Qualsiasi sito che può far girare un piccolo endpoint server, come Next.js, Express o Cloudflare Workers, può ospitare il proxy.

L'SDK Web di Neocortex è gratuito?

L'SDK è open source con licenza Apache-2.0. Le conversazioni contano sul tuo piano Neocortex.

Il personaggio può fare cose sulla pagina?

Sì. Definisci le azioni del personaggio nell'editor di Neocortex, poi registra un gestore per ciascuna nella pagina, per esempio per aprire un prodotto, avviare un tour o scorrere fino a una sezione.

Articoli simili

Continua a leggere