ten-framework README

The project's README from github.com/TEN-framework/ten-framework. As one markdown file: README.md.

![Image][ten-framework-banner]

TEN Releases Coverage Status Release Date Commits Issues closed Contributors GitHub license Ask DeepWiki ReadmeX

README in English 简体中文操作指南 日本語のREADME README in 한국어 README en Español README en Français README in Italiano

TEN-framework%2Ften-framework | Trendshift

Official Site • Documentation • Blog


Table of Contents

Welcome to TEN

TEN is an open-source framework for real-time multimodal conversational AI.

TEN Ecosystem includes TEN Framework, Agent Examples, VAD, Turn Detection and Portal.


Community Channel Purpose
Follow on X Follow TEN Framework on X for updates and announcements
Discord TEN Community Join our Discord community to connect with developers
Follow on LinkedIn Follow TEN Framework on LinkedIn for updates and announcements
Hugging Face Space Join our Hugging Face community to explore our spaces and models

Agent Examples


Image

Multi-Purpose Voice Assistant — This low-latency, high-quality real-time assistant supports both RTC and WebSocket connections, and you can extend it with Memory, VAD, Turn Detection, and other extensions.

See the Example code for more details.


divider divider


![Image][doodler-image]

Doodler — A doodle board that turns spoken or typed prompts into simple hand-drawn sketches, complete with a crayon palette and real-time drawing.

[Example code][doodler-example]


divider divider


![Image][speaker-diarization-image]

Speaker Diarization — Real-time diarization that detects and labels speakers, the Who Likes What game shows an interactive use case.

[Example code][speechmatics-diarization-example]


divider divider


Image

Lip Sync Avatars — Works with multiple avatar vendors, the main character features Kei, an anime character with MotionSync-powered lip sync, and also supports realistic avatars from Trulience, HeyGen, and Tavus.

See the Example code for different Live2D characters.


divider divider


![Image][sip-call-image]

SIP Call — SIP extension that enables phone calls powered by TEN.

[Example code][voice-assistant-sip-example]


divider divider


![Image][transcription-image]

Transcription — A transcription tool that transcribes audio to text.

[Example code][transcription-example]


divider divider


![Image][esp32-image]

ESP32-S3 Korvo V3 — Runs TEN agent example on the Espressif ESP32-S3 Korvo V3 development board to integrate LLM-powered communication with hardware.

See the [integration guide][esp32-guide] for more details.


Quick Start with Agent Examples

Localhost

Step ⓵ - Prerequisites

Category Requirements
Keys • Agora [App ID][agora-app-id] and [App Certificate][agora-app-certificate]
• [OpenAI][openai-api] API key
• [Deepgram][deepgram] ASR
• [ElevenLabs][elevenlabs] TTS
Installation • [Docker][docker] / [Docker Compose][docker-compose]
• [Node.js (LTS) v18][nodejs]
Minimum System Requirements • CPU >= 2 cores
• RAM >= 4 GB

divider divider

Step ⓶ - Build agent examples in VM

1. Clone the repo, cd into ai_agents, and create a .env file from .env.example
cd ai_agents
cp ./.env.example ./.env
2. Set up the Agora App ID and App Certificate in .env
AGORA_APP_ID=
AGORA_APP_CERTIFICATE=

# Deepgram (required for speech-to-text)
DEEPGRAM_API_KEY=

# OpenAI (required for language model)
OPENAI_API_KEY=

# ElevenLabs (required for text-to-speech)
ELEVENLABS_TTS_KEY=
3. Start agent development containers
docker compose up -d
4. Enter the container
docker exec -it ten_agent_dev bash
5. Build the agent with the default example (~5-8 min)

Check the agents/examples folder for additional samples. Start with one of these defaults:

# use the chained voice assistant
cd agents/examples/voice-assistant

# or use the speech-to-speech voice assistant in real time
cd agents/examples/voice-assistant-realtime
6. Start the web server

Run task install before the first launch and after changing dependencies or Go source code. It installs the TEN, Python, and frontend dependencies and builds the Go API server. Python-only source changes do not require reinstalling.

task install
task run
7. Access the agent

Once the agent example is running, you can access the following interfaces:

localhost:49483 localhost:3000
![Screenshot 1][localhost-49483-image] ![Screenshot 2][localhost-3000-image]

divider divider

Step ⓷ - Customize your agent example

  1. Open [localhost:49483][localhost-49483].
  2. Right-click the STT, LLM, and TTS extensions.
  3. Open their properties and enter the corresponding API keys.
  4. Submit your changes, now you can see the updated Agent Example in [localhost:3000][localhost-3000].

divider divider


Run a transcriber app from TEN Manager without Docker (Beta)

TEN also provides a transcriber app that you can run from TEN Manager without using Docker.

Check the [quick start guide][quick-start-guide-ten-manager] for more details.


divider divider


Codespaces

GitHub offers free Codespaces for each repository. You can run Agent Examples in Codespaces without using Docker. Codespaces typically start faster than local Docker environments.

[![][codespaces-shield]][codespaces-new]

Check out [this guide][codespaces-guide] for more details.


Agent Examples Self-Hosting

Deploying with Docker

Once you have customized your agent (either by using the TMAN Designer or editing property.json directly), you can deploy it by creating a release Docker image for your service.

Release as Docker image

Note: The following commands need to be executed outside of any Docker container.

Build image
cd ai_agents
docker build -f agents/examples/<example-name>/Dockerfile -t example-app .
Run
docker run --rm -it --env-file .env -p 3000:3000 example-app

divider divider

Deploying with other cloud services

You can split the deployment into two pieces when you want to host TEN on providers such as [Vercel][vercel] or [Netlify][netlify].

  1. Run the TEN backend on any container-friendly platform (a VM with Docker, Fly.io, Render, ECS, Cloud Run, or similar). Use the example Docker image without modifying it and expose port 8080 from that service.

  2. Deploy only the frontend to Vercel or Netlify. Point the project root to ai_agents/agents/examples/<example>/frontend, run pnpm install (or bun install) followed by pnpm build (or bun run build), and keep the default .next output directory.

  3. Configure environment variables in your hosting dashboard so that AGENT_SERVER_URL points to the backend URL, and add any NEXT_PUBLIC_* keys the UI needs (for example, Agora credentials you surface to the browser).

  4. Ensure your backend accepts requests from the frontend origin — via open CORS or by using the built-in proxy middleware.

With this setup, the backend handles long-running worker processes, while the hosted frontend simply forwards API traffic to it.


Stay Tuned

Get instant notifications for new releases and updates. Your support helps us grow and improve TEN!


![Image][stay-tuned-image]



TEN Ecosystem


Project Preview
[️TEN Framework][ten-framework-link]
Open-source framework for conversational AI Agents.

![][ten-framework-shield]		 ![][ten-framework-banner]
[TEN VAD][ten-vad-link]
Low-latency, lightweight and high-performance streaming voice activity detector (VAD).

![][ten-vad-shield]		 ![][ten-vad-banner]
[️ TEN Turn Detection][ten-turn-detection-link]
TEN Turn Detection enables full-duplex dialogue communication.

![][ten-turn-detection-shield]		 ![][ten-turn-detection-banner]
[TEN Agent Examples][ten-agent-example-link]
Usecases powered by TEN.

 ![][ten-agent-example-banner]
[TEN Portal][ten-portal-link]
The official site of the TEN Framework with documentation and a blog.

![][ten-portal-shield]		 ![][ten-portal-banner]


Questions

TEN Framework is available on these AI-powered Q&A platforms. They can help you find answers quickly and accurately in multiple languages, covering everything from basic setup to advanced implementation details.

Service Link
DeepWiki Ask DeepWiki
ReadmeX ReadmeX

Contributing

We welcome all forms of open-source collaboration! Whether you're fixing bugs, adding features, improving documentation, or sharing ideas, your contributions help advance personalized AI tools. Check out our GitHub Issues and Projects to find ways to contribute and show your skills. Together, we can build something amazing!


[!TIP]

Welcome all kinds of contributions 🙏

Join us in building TEN better! Every contribution makes a difference, from code to documentation. Share your TEN Agent projects on social media to inspire others!

Connect with one of the TEN maintainers [@elliotchen200][elliotchen200-x] on 𝕏 or [@cyfyifanchen][cyfyifanchen-github] on GitHub for project updates, discussions, and collaboration opportunities.


divider divider

Code Contributors

![TEN][contributors-image]

Contribution Guidelines

Contributions are welcome! Please read the [contribution guidelines][contribution-guidelines-doc] first.


divider divider

License

  1. The entire TEN framework (except for the folders explicitly listed below) is released pursuant the Apache License, Version 2.0, with additional restrictions. For details, please refer to the [LICENSE][license-file] file located in the root directory of the TEN framework.

  2. The components within the packages directory are released under the Apache License, Version 2.0. For details, please refer to the LICENSE file located in each package's root directory.

  3. The third-party libraries used by the TEN framework are listed and described in detail. For more information, please refer to the [third_party][third-party-folder] folder.

[spe

ten-framework (TEN-framework/ten-framework)

Searching Database…

11.2K ·GitHub
Ten-framework
Что это такое?TEN — это фреймворк с открытым исходным кодом для создания голосовых ИИ-агентов, которые ведут диалог в реальном времени и работают с несколькими типами данных (мультимодальные). В комплекте есть примеры агентов: помощники, рисование, разделение речи по говорящим, аватары с синхронизацией губ, SIP-звонки и транскрибация.
Это фреймворк или готовый чат-бот?Это фреймворк, а также экосистема TEN из связанных проектов (VAD, Turn Detection, Portal) и готовые примеры агентов, которые вы настраиваете через визуальный TMAN Designer. Это не одно готовое приложение.
Как запустить пример агента?Клонируйте репозиторий, создайте файл .env с вашими App ID и Certificate от Agora, запустите dev-контейнеры через Docker, зайдите в контейнер, соберите пример по умолчанию и запустите веб-сервер. После этого TMAN Designer будет доступен по адресу localhost:49483, а Agent UI — по адресу localhost:3000.
Какие API-ключи и инструменты нужны перед началом работы?Нужны App ID и App Certificate от Agora, ключ API OpenAI, Deepgram для ASR и ElevenLabs для TTS, а также установленные Docker, Docker Compose и Node.js LTS v18. Потребуется минимум 2 ядра процессора и 4 ГБ оперативной памяти.
Можно ли запустить без Docker?В основном нет: для полных примеров агентов Docker нужен. Есть бета-версия приложения для транскрибации, которое можно запустить из TEN Manager без Docker. GitHub Codespaces предлагается как способ попробовать полные примеры агентов без Docker.
Можно ли развернуть агента вне Docker-хостингов, например Vercel?Да. Бэкенд TEN запускается на любой платформе, которая поддерживает контейнеры (VM, Fly.io, Render, ECS, Cloud Run) и открывает порт 8080. Затем фронтенд разворачивается на Vercel или Netlify, а AGENT_SERVER_URL указывает на бэкенд.
Какие примеры агентов входят в TEN?Среди примеров: универсальный голосовой ассистент, агент для рисования набросков (doodle), разделение речи по говорящим в реальном времени, аватары с синхронизацией губ (Kei, Trulience, HeyGen, Tavus), SIP-агент для телефонных звонков, инструмент транскрибации и интеграция с аппаратной платформой ESP32-S3.
Можно ли настроить провайдеров STT, LLM и TTS?Да. Откройте TMAN Designer по адресу localhost:49483, щёлкните правой кнопкой мыши по расширениям STT, LLM и TTS и введите ваши API-ключи в их свойствах.
What are similar projects?agentscope, jargo, pipecat, openai-agents-python, Omni-Interaction-Agent, agents, OpenDots, Tel-Agent
Which topics is it in?conversational-ai, voice-assistant, webrtc, voice, speech-recognition, text-to-speech, real-time, chatbot, video, sdk, multi-agent, agents
Creator
TEN-framework
Size
124.2 MB
Stars
11.2K
Updated
CommitOct 16Release0.11.73Sep 22
Age
2y
Commits · 90 Days