README-IT.md

Indice

• Benvenuto in TEN
• Esempi di agenti
• Guida rapida agli esempi di agenti
  • Ambiente locale
  • Codespaces
• Auto-hosting degli esempi
  • Distribuire con Docker
  • Distribuire su altri servizi cloud
• Rimani aggiornato
• Ecosistema TEN
• Domande
• Contribuire
  • Contributor del codice
  • Linee guida per contribuire
  • Licenza

Benvenuto in TEN

TEN è un framework open source per creare agenti vocali conversazionali.

L’ecosistema TEN comprende TEN Framework, Esempi di agenti, VAD, Turn Detection e Portal.

Canale della community	Scopo
	Segui TEN Framework su X per aggiornamenti e annunci
	Unisciti alla community Discord per confrontarti con altri sviluppatori
	Segui TEN Framework su LinkedIn per non perdere nessuna novità
	Esplora i nostri spazi e modelli su Hugging Face
	Entra nel gruppo WeChat per parlare con la community cinese

Esempi di agenti

Assistente vocale multiuso — Assistente in tempo reale, a bassa latenza e alta qualità, estendibile con memoria, VAD, rilevamento dei turni e altre estensioni.

Consulta il codice di esempio per maggiori dettagli.

Doodler — Una lavagna di scarabocchi che trasforma prompt vocali o digitati in semplici schizzi a mano, con una palette di pastelli e disegno in tempo reale.

Codice di esempio

Avatar con lip sync — Supporta diversi provider di avatar. La demo mostra Kei, un personaggio anime con sincronizzazione labiale Live2D, e presto includerà avatar realistici di Trulience, HeyGen e Tavus.

Guarda il codice di esempio Live2D.

Diarizzazione vocale — Rilevamento e etichettatura dei parlanti in tempo reale. Il gioco "Who Likes What" mostra un caso d’uso interattivo.

Codice di esempio

Chiamata SIP — Estensione SIP che abilita chiamate telefoniche gestite da TEN.

Codice di esempio

Trascrizione — Strumento che trascrive l’audio in testo.

Codice di esempio

ESP32-S3 Korvo V3 — Esegue un esempio di TEN Agent sulla scheda di sviluppo Espressif ESP32-S3 Korvo V3 per portare comunicazioni basate su LLM sull’hardware.

Consulta la guida di integrazione per ulteriori informazioni.

Guida rapida agli esempi di agenti

Ambiente locale

Passaggio ⓵ - Prerequisiti

Categoria	Requisiti
Chiavi	• Agora App ID e App Certificate (minuti gratuiti ogni mese) • Chiave API OpenAI (qualsiasi LLM compatibile con OpenAI) • ASR Deepgram (crediti gratuiti alla registrazione) • TTS ElevenLabs (crediti gratuiti alla registrazione)
Installazione	• Docker / Docker Compose • Node.js (LTS) v18
Requisiti minimi	• CPU ≥ 2 core • RAM ≥ 4 GB

Passaggio ⓶ - Compila gli esempi nella VM

1. Clona il repo, entra in ai_agents e crea .env da .env.example

cd ai_agents
cp ./.env.example ./.env

2. Configura Agora App ID e App Certificate in .env

AGORA_APP_ID=
AGORA_APP_CERTIFICATE=

# Esegui l’esempio predefinito dell’assistente vocale
# Deepgram (necessario per STT)
DEEPGRAM_API_KEY=your_deepgram_api_key_here

# OpenAI (necessario per il modello linguistico)
OPENAI_API_KEY=your_openai_api_key_here
OPENAI_MODEL=gpt-4o

# ElevenLabs (necessario per TTS)
ELEVENLABS_TTS_KEY=your_elevenlabs_api_key_here

3. Avvia i container di sviluppo

docker compose up -d

4. Entra nel container

docker exec -it ten_agent_dev bash

5. Compila l’agente con l’esempio predefinito (≈5-8 min)

Trovi altre demo nella cartella agents/examples. Inizia da una di queste:

# Assistente vocale concatenato
cd agents/examples/voice-assistant

# Assistente voce-a-voce in tempo reale
cd agents/examples/voice-assistant-realtime

6. Avvia il server web

Esegui task build se hai modificato il codice locale. È obbligatorio per i linguaggi compilati (TypeScript, Go, ecc.) e facoltativo per Python.

task install
task run

7. Accedi all’agente

Quando l’esempio è in esecuzione puoi usare queste interfacce:

localhost:49483

localhost:3000

• TMAN Designer: http://localhost:49483
• UI degli esempi: http://localhost:3000

Passaggio ⓷ - Personalizza l’esempio

1. Apri localhost:49483.
2. Fai clic con il tasto destro sulle estensioni STT, LLM e TTS.
3. Inserisci le relative API key.
4. Dopo aver salvato, la versione aggiornata sarà visibile su localhost:3000.

Esegui un’app di trascrizione da TEN Manager senza Docker (Beta)

TEN offre anche un’app di trascrizione che puoi eseguire in TEN Manager senza usare Docker.

Consulta la guida rapida per ulteriori dettagli.

Codespaces

GitHub offre Codespaces gratuiti per ogni repository. Puoi eseguire gli esempi senza Docker e, in genere, l’avvio è più rapido rispetto all’ambiente locale basato su container.

Consulta questa guida per i dettagli.

Auto-hosting degli esempi

Distribuire con Docker

Dopo aver personalizzato l’agente (con TMAN Designer o modificando property.json), crea un’immagine Docker di release e distribuiscila.

Pubblicare come immagine Docker

Nota: esegui i comandi al di fuori di qualsiasi container.

Build dell’immagine

cd ai_agents
docker build -f agents/examples/<example-name>/Dockerfile -t example-app .

Esecuzione

docker run --rm -it --env-file .env -p 3000:3000 example-app

Distribuire su altri servizi cloud

Puoi dividere il deployment in due parti quando ospiti TEN su piattaforme come Vercel o Netlify.

1. Esegui il backend TEN su una piattaforma compatibile con container (VM Docker, Fly.io, Render, ECS, Cloud Run, ecc.). Usa l’immagine di esempio senza modificarla ed esponi la porta 8080.
2. Distribuisci solo il frontend su Vercel o Netlify. Imposta la radice del progetto su ai_agents/agents/examples/<example>/frontend, esegui pnpm install (o bun install) e poi pnpm build (o bun run build), mantenendo la cartella di output .next predefinita.
3. Configura le variabili di ambiente dal pannello del provider: AGENT_SERVER_URL deve puntare al backend e aggiungi le chiavi NEXT_PUBLIC_* necessarie (per esempio le credenziali Agora esposte al browser).
4. Consenti al backend di accettare richieste dall’origine del frontend tramite CORS aperto o usando il middleware proxy incluso.

In questo modo il backend gestisce i processi di lunga durata e il frontend hostato instrada semplicemente il traffico API.

Rimani aggiornato

Ricevi notifiche immediate su nuove release e aggiornamenti. Il tuo supporto ci aiuta a migliorare TEN!

Ecosistema TEN

Progetto	Anteprima
️TEN Framework Framework open source per agenti conversazionali.
TEN VAD Rilevatore di attività vocale in streaming, leggero e a bassa latenza.
️TEN Turn Detection Abilita dialoghi full-duplex tramite rilevamento dei turni.
TEN Agent Examples Casi d'uso costruiti con TEN.
TEN Portal Sito ufficiale con documentazione e blog.

Domande

TEN Framework è presente anche su piattaforme di Q&A alimentate dall’IA. Offrono risposte multilingue, dalla configurazione di base agli scenari avanzati.

Servizio	Link
DeepWiki
ReadmeX

Contribuire

Accogliamo qualsiasi forma di collaborazione open source! Bugfix, nuove funzionalità, documentazione o idee: ogni contributo aiuta a far crescere strumenti di IA personalizzati. Dai un’occhiata a Issues e Projects su GitHub per trovare attività su cui lavorare e mostrare le tue competenze. Costruiamo TEN insieme!

Contributor del codice

Linee guida per contribuire

Le contribuzioni sono benvenute! Leggi prima le linee guida per contribuire.

Licenza

1. L’intero TEN Framework (esclusi i folder elencati qui sotto) è rilasciato sotto Apache License 2.0 con restrizioni aggiuntive. Consulta il file LICENSE nella root del progetto.
2. I componenti nella directory packages sono distribuiti sotto Apache License 2.0. Ogni package contiene il proprio file LICENSE.
3. Le librerie di terze parti utilizzate da TEN Framework sono elencate nella cartella third_party.