ten-framework Documentation

Technical Documentation: TEN-framework/ten-framework

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (README.md) Copy Section

Table of Contents

• Welcome to TEN
• Agent Examples
• Quick Start with Agent Examples
  • Localhost
  • Codespaces
• Agent Examples Self-Hosting
  • Deploying with Docker
  • Deploying with other cloud services
• Stay Tuned
• TEN Ecosystem
• Questions
• Contributing
  • Code Contributors
  • Contribution Guidelines
  • License

Welcome to TEN Copy Chapter

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 TEN Framework on X for updates and announcements
	Join our Discord community to connect with developers
	Follow TEN Framework on LinkedIn for updates and announcements
	Join our Hugging Face community to explore our spaces and models

Agent Examples Copy Chapter

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.

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

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

Example code

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.

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

Example code

Transcription — A transcription tool that transcribes audio to text.

Example code

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 for more details.

Quick Start with Agent Examples Copy Chapter

Localhost Copy Section

Step ⓵ - Prerequisites

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

• TMAN Designer: localhost:49483
• Agent Examples UI: localhost:3000

Step ⓷ - Customize your agent example

1. Open 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.

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 for more details.

Codespaces Copy Section

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.

Check out this guide for more details.

Agent Examples Self-Hosting Copy Chapter

Deploying with Docker Copy Section

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

Deploying with other cloud services Copy Section

You can split the deployment into two pieces when you want to host TEN on providers such as Vercel or 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 Copy Chapter

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

TEN Ecosystem Copy Chapter

Project	Preview
️TEN FrameworkOpen-source framework for conversational AI Agents.
TEN VADLow-latency, lightweight and high-performance streaming voice activity detector (VAD).
️ TEN Turn DetectionTEN Turn Detection enables full-duplex dialogue communication.
TEN Agent ExamplesUsecases powered by TEN.
TEN PortalThe official site of the TEN Framework with documentation and a blog.

Questions Copy Chapter

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
ReadmeX

Contributing Copy Chapter

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 on 𝕏 or @cyfyifanchen on GitHub for project updates, discussions, and collaboration opportunities.

Code Contributors Copy Section

Contribution Guidelines Copy Section

Contributions are welcome! Please read the contribution guidelines first.

License Copy Section

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 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 folder.

Third Party Curl Docs README (`third_party/curl/docs/README.md`) Copy Section

Documentation

you will find a mix of various documentation in this directory and
subdirectories, using several different formats. Some of them are not ideal
for reading directly in your browser.

If you would rather see the rendered version of the documentation, check out the
curl website's documentation section for
general curl stuff or the libcurl section for
libcurl related documentation.

Third Party Nlohmann Json Docs README (`third_party/nlohmann_json/docs/README.md`) Copy Section

Documentation

Generate documentation Copy Chapter

Note on documentation: The source files contain links to the online documentation at https://json.nlohmann.me. This URL
contains the most recent documentation and should also be applicable to previous versions; documentation for deprecated
functions is not removed, but marked deprecated.

If you want to see the documentation for a specific tag or commit hash, you can generate it as follows (here for tag
v3.10.2):

git clone https://github.com/nlohmann/json.git
cd json
git checkout v3.10.2
make install_venv serve -C docs/mkdocs

Open URL http://127.0.0.1:8000/ in your browser. Replace from any URL from the source code https://json.nlohmann.me
with http://127.0.0.1:8000 to see the documentation for your tag or commit hash.

Ai L1 L2 Index (`docs/ai/L1/L2/_index.md`) Copy Section

Deep Dives Index

Third Party Curl Docs Examples README (`third_party/curl/docs/examples/README.md`) Copy Section

libcurl examples

This directory is for libcurl programming examples. They are meant to show
some simple steps on how you can build your own application to take full
advantage of libcurl.

If you end up with other small but still useful example sources, please mail
them for submission in future packages and on the website.

Building Copy Chapter

The Makefile.example is an example Makefile that could be used to build
these examples. Just edit the file according to your system and requirements
first.

Most examples should build fine using a command line like this:

`curl-config --cc --cflags --libs` -o example example.c

Some compilers do not like having the arguments in this order but instead
want you do reorganize them like:

`curl-config --cc` -o example example.c `curl-config --cflags --libs`

Please do not use the curl.se site as a test target for your libcurl
applications/experiments. Even if some of the examples use that site as a URL
at some places, it does not mean that the URLs work or that we expect you to
actually torture our website with your tests. Thanks.

Examples Copy Chapter

Each example source code file is designed to be and work stand-alone and
rather self-explanatory. The examples may at times lack the level of error
checks you need in a real world, but that is then only for the sake of
readability: to make the code smaller and easier to follow.

Third Party Nlohmann Json Docs Docset README (`third_party/nlohmann_json/docs/docset/README.md`) Copy Section

docset

The folder contains the required files to create a docset which can be used in
documentation browsers like Dash, Velocity, or
Zeal.

The docset can be created with

make nlohmann_json.docset

The generated folder nlohmann_json.docset can then be opened in the documentation browser.

A recent version is also part of the Dash user contributions.

Licenses Copy Chapter

The JSON logo is public domain.

Third Party Clingo Sys Clingo Third Party Catch Docs Readme (`third_party/clingo-sys/clingo/third_party/catch/docs/Readme.md`) Copy Section

Reference

To get the most out of Catch2, start with the tutorial.
Once you're up and running consider the following reference material.

Writing tests:

• Assertion macros
• Matchers (asserting complex properties)
• Comparing floating point numbers
• Logging macros
• Test cases and sections
• Test fixtures
• Explicitly skipping, passing, and failing tests at runtime
• Reporters (output customization)
• Event Listeners
• Data Generators (value parameterized tests)
• Other macros
• Micro benchmarking

Fine tuning:

• Supplying your own main()
• Compile-time configuration
• String Conversions

Running:

• Command line

Odds and ends:

• Frequently Asked Questions (FAQ)
• Best practices and other tips
• CMake integration
• Tooling integration (CI, test runners, other)
• Known limitations

Other:

• Why Catch2?
• Migrating from v2 to v3
• Open Source Projects using Catch2
• Commercial Projects using Catch2
• Contributing
• Release Notes
• Deprecations and incoming changes

Third Party Nlohmann Json Docs Mkdocs Docs Integration Index (`third_party/nlohmann_json/docs/mkdocs/docs/integration/index.md`) Copy Section

Header only

json.hpp is the single required
file in single_include/nlohmann or released here. You need to add

#include <nlohmann/json.hpp>

// for convenience
using json = nlohmann::json;

to the files you want to process JSON and set the necessary switches to enable C++11 (e.g., -std=c++11 for GCC and
Clang).

You can further use file
single_include/nlohmann/json_fwd.hpp
for forward declarations.

Third Party Nlohmann Json Docs Mkdocs Docs Api Adl Serializer Index (`third_party/nlohmann_json/docs/mkdocs/docs/api/adl_serializer/index.md`) Copy Section

nlohmann::adl_serializer

template<typename, typename>
struct adl_serializer;

Serializer that uses ADL (Argument-Dependent Lookup) to choose
to_json/from_json functions from the types' namespaces.

It is implemented similar to

template<typename ValueType>
struct adl_serializer {
    template<typename BasicJsonType>
    static void to_json(BasicJsonType& j, const T& value) {
        // calls the "to_json" method in T's namespace
    }

    template<typename BasicJsonType>
    static void from_json(const BasicJsonType& j, T& value) {
        // same thing, but with the "from_json" method
    }
};

Member functions Copy Chapter

• from_json - convert a JSON value to any value type
• to_json - convert any value type to a JSON value

Version history Copy Chapter

• Added in version 2.1.0.

Third Party Nlohmann Json Docs Mkdocs Docs Api Basic Json Index (`third_party/nlohmann_json/docs/mkdocs/docs/api/basic_json/index.md`) Copy Section

nlohmann::basic_json

Defined in header <nlohmann/json.hpp>

template<
    template<typename U, typename V, typename... Args> class ObjectType = std::map,
    template<typename U, typename... Args> class ArrayType = std::vector,
    class StringType = std::string,
    class BooleanType = bool,
    class NumberIntegerType = std::int64_t,
    class NumberUnsignedType = std::uint64_t,
    class NumberFloatType = double,
    template<typename U> class AllocatorType = std::allocator,
    template<typename T, typename SFINAE = void> class JSONSerializer = adl_serializer,
    class BinaryType = std::vector<std::uint8_t>,
    class CustomBaseClass = void
>
class basic_json;

Template parameters Copy Chapter

Specializations Copy Chapter

• json - default specialization
• ordered_json - specialization that maintains the insertion order of object keys

Iterator invalidation Copy Chapter

Todo

Requirements Copy Chapter

The class satisfies the following concept requirements:

Basic Copy Section

• DefaultConstructible: JSON values can be default
  constructed. The result will be a JSON null value.
• MoveConstructible: A JSON value can be constructed
  from an rvalue argument.
• CopyConstructible: A JSON value can be
  copy-constructed from an lvalue expression.
• MoveAssignable: A JSON value can be assigned from an
  rvalue argument.
• CopyAssignable: A JSON value can be copy-assigned from
  an lvalue expression.
• Destructible: JSON values can be destructed.

Layout Copy Section

• StandardLayoutType: JSON values have
  standard layout: All non-static data
  members are private and standard layout types, the class has no virtual functions or (virtual) base classes.

Library-wide Copy Section

• EqualityComparable: JSON values can be compared with
  ==, see operator==.
• LessThanComparable: JSON values can be compared with
  <, see operator<.
• Swappable: Any JSON lvalue or rvalue of can be swapped with
  any lvalue or rvalue of other compatible types, using unqualified function swap.
• NullablePointer: JSON values can be compared against
  std::nullptr_t objects which are used to model the null value.

Container Copy Section

• Container: JSON values can be used like STL containers and
  provide iterator access.
• ReversibleContainer: JSON values can be used like
  STL containers and provide reverse iterator access.

Member types Copy Chapter

• adl_serializer - the default serializer
• value_t - the JSON type enumeration
• json_pointer - JSON Pointer implementation
• json_serializer - type of the serializer to for conversions from/to JSON
• error_handler_t - type to choose behavior on decoding errors
• cbor_tag_handler_t - type to choose how to handle CBOR tags
• initializer_list_t - type for initializer lists of basic_json values
• input_format_t - type to choose the format to parse
• json_sax_t - type for SAX events

Exceptions Copy Section

• exception - general exception of the basic_json class
  • parse_error - exception indicating a parse error
  • invalid_iterator - exception indicating errors with iterators
  • type_error - exception indicating executing a member function with a wrong type
  • out_of_range - exception indicating access out of the defined range
  • other_error - exception indicating other library errors

Container types Copy Section

JSON value data types Copy Section

• array_t - type for arrays
• binary_t - type for binary arrays
• boolean_t - type for booleans
• default_object_comparator_t - default comparator for objects
• number_float_t - type for numbers (floating-point)
• number_integer_t - type for numbers (integer)
• number_unsigned_t - type for numbers (unsigned)
• object_comparator_t - comparator for objects
• object_t - type for objects
• string_t - type for strings

Parser callback Copy Section

• parse_event_t - parser event types
• parser_callback_t - per-element parser callback type

Member functions Copy Chapter

• (constructor)
• (destructor)
• operator= - copy assignment
• array (static) - explicitly create an array
• binary (static) - explicitly create a binary array
• object (static) - explicitly create an object

Object inspection Copy Section

Functions to inspect the type of a JSON value.

• type - return the type of the JSON value
• operator value_t - return the type of the JSON value
• type_name - return the type as string
• is_primitive - return whether type is primitive
• is_structured - return whether type is structured
• is_null - return whether value is null
• is_boolean - return whether value is a boolean
• is_number - return whether value is a number
• is_number_integer - return whether value is an integer number
• is_number_unsigned - return whether value is an unsigned integer number
• is_number_float - return whether value is a floating-point number
• is_object - return whether value is an object
• is_array - return whether value is an array
• is_string - return whether value is a string
• is_binary - return whether value is a binary array
• is_discarded - return whether value is discarded

Value access Copy Section

Direct access to the stored value of a JSON value.

• get - get a value
• get_to - get a value and write it to a destination
• get_ptr - get a pointer value
• get_ref - get a reference value
• operator ValueType - get a value
• get_binary - get a binary value

Element access Copy Section

Access to the JSON value

• at - access specified element with bounds checking
• operator[] - access specified element
• value - access specified object element with default value
• front - access the first element
• back - access the last element

Lookup Copy Section

• find - find an element in a JSON object
• count - returns the number of occurrences of a key in a JSON object
• contains - check the existence of an element in a JSON object

Iterators Copy Section

• begin - returns an iterator to the first element
• cbegin - returns a const iterator to the first element
• end - returns an iterator to one past the last element
• cend - returns a const iterator to one past the last element
• rbegin - returns an iterator to the reverse-beginning
• rend - returns an iterator to the reverse-end
• crbegin - returns a const iterator to the reverse-beginning
• crend - returns a const iterator to the reverse-end
• items - wrapper to access iterator member functions in range-based for

Capacity Copy Section

• empty - checks whether the container is empty
• size - returns the number of elements
• max_size - returns the maximum possible number of elements

Modifiers Copy Section

• clear - clears the contents
• push_back - add a value to an array/object
• operator+= - add a value to an array/object
• emplace_back - add a value to an array
• emplace - add a value to an object if key does not exist
• erase - remove elements
• insert - inserts elements
• update - updates a JSON object from another object, overwriting existing keys
• swap - exchanges the values

Lexicographical comparison operators Copy Section

• operator== - comparison: equal
• operator!= - comparison: not equal
• operator< - comparison: less than
• operator> - comparison: greater than
• operator<= - comparison: less than or equal
• operator>= - comparison: greater than or equal
• operator<=> - comparison: 3-way

Serialization / Dumping Copy Section

• dump - serialization

Deserialization / Parsing Copy Section

• parse (static) - deserialize from a compatible input
• accept (static) - check if the input is valid JSON
• sax_parse (static) - generate SAX events

JSON Pointer functions Copy Section

• flatten - return flattened JSON value
• unflatten - unflatten a previously flattened JSON value

JSON Patch functions Copy Section

• patch - applies a JSON patch
• patch_inplace - applies a JSON patch in place
• diff (static) - creates a diff as a JSON patch

JSON Merge Patch functions Copy Section

• merge_patch - applies a JSON Merge Patch

Static functions Copy Chapter

• meta - returns version information on the library
• get_allocator - returns the allocator associated with the container

Binary formats Copy Section

• from_bjdata (static) - create a JSON value from an input in BJData format
• from_bson (static) - create a JSON value from an input in BSON format
• from_cbor (static) - create a JSON value from an input in CBOR format
• from_msgpack (static) - create a JSON value from an input in MessagePack format
• from_ubjson (static) - create a JSON value from an input in UBJSON format
• to_bjdata (static) - create a BJData serialization of a given JSON value
• to_bson (static) - create a BSON serialization of a given JSON value
• to_cbor (static) - create a CBOR serialization of a given JSON value
• to_msgpack (static) - create a MessagePack serialization of a given JSON value
• to_ubjson (static) - create a UBJSON serialization of a given JSON value

Non-member functions Copy Chapter

• operator<<(std::ostream&) - serialize to stream
• operator>>(std::istream&) - deserialize from stream
• to_string - user-defined to_string function for JSON values

Literals Copy Chapter

• operator""_json - user-defined string literal for JSON values

Helper classes Copy Chapter

• std::hash<basic_json> - return a hash value for a JSON object
• std::swap<basic_json> - exchanges the values of two JSON objects

Examples Copy Chapter

??? example

The example shows how the library is used.

```cpp
--8<-- "examples/README.cpp"
```

Output:

```json
--8<-- "examples/README.output"
```

See also Copy Chapter

• RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format

Version history Copy Chapter

• Added in version 1.0.0.

Third Party Nlohmann Json Docs Mkdocs Docs Api Byte Container With Subtype Index (`third_party/nlohmann_json/docs/mkdocs/docs/api/byte_container_with_subtype/index.md`) Copy Section

nlohmann::byte_container_with_subtype

template<typename BinaryType>
class byte_container_with_subtype : public BinaryType;

This type extends the template parameter BinaryType provided to basic_json with a subtype
used by BSON and MessagePack. This type exists so that the user does not have to specify a type themselves with a
specific naming scheme in order to override the binary type.

Template parameters Copy Chapter

BinaryType
: container to store bytes (#!cpp std::vector<std::uint8_t> by default)

Member types Copy Chapter

• container_type - the type of the underlying container (BinaryType)
• subtype_type - the type of the subtype (#!cpp std::uint64_t)

Member functions Copy Chapter

• (constructor)
• operator== - comparison: equal
• operator!= - comparison: not equal
• set_subtype - sets the binary subtype
• subtype - return the binary subtype
• has_subtype - return whether the value has a subtype
• clear_subtype - clears the binary subtype

Version history Copy Chapter

• Added in version 3.8.0.
• Changed type of subtypes to #!cpp std::uint64_t in 3.10.0.

Third Party Nlohmann Json Docs Mkdocs Docs Api Json Pointer Index (`third_party/nlohmann_json/docs/mkdocs/docs/api/json_pointer/index.md`) Copy Section

nlohmann::json_pointer

template<typename RefStringType>
class json_pointer;

A JSON pointer defines a string syntax for identifying a specific value within a JSON document. It can be used with
functions at and operator[]. Furthermore, JSON pointers
are the base for JSON patches.

Template parameters Copy Chapter

RefStringType
: the string type used for the reference tokens making up the JSON pointer

!!! warning "Deprecation"

For backwards compatibility `RefStringType` may also be a specialization of [`basic_json`](../basic_json/index.md)
in which case `string_t` will be deduced as [`basic_json::string_t`](../basic_json/string_t.md). This feature is
deprecated and may be removed in a future major version.

Member types Copy Chapter

• string_t - the string type used for the reference tokens

Member functions Copy Chapter

• (constructor)
• to_string - return a string representation of the JSON pointer
• operator string_t - return a string representation of the JSON pointer
• operator== - compare: equal
• operator!= - compare: not equal
• operator/= - append to the end of the JSON pointer
• operator/ - create JSON Pointer by appending
• parent_pointer - returns the parent of this JSON pointer
• pop_back - remove last reference token
• back - return last reference token
• push_back - append an unescaped token at the end of the pointer
• empty - return whether pointer points to the root document

Literals Copy Chapter

• operator""_json_pointer - user-defined string literal for JSON pointers

See also Copy Chapter

• RFC 6901

Version history Copy Chapter

• Added in version 2.0.0.
• Changed template parameter from basic_json to string type in version 3.11.0.

Third Party Nlohmann Json Docs Mkdocs Docs Api Json Sax Index (`third_party/nlohmann_json/docs/mkdocs/docs/api/json_sax/index.md`) Copy Section

nlohmann::json_sax

template<typename BasicJsonType>
struct json_sax;

This class describes the SAX interface used by sax_parse. Each function is called in
different situations while the input is parsed. The boolean return value informs the parser whether to continue
processing the input.

Template parameters Copy Chapter

BasicJsonType
: a specialization of basic_json

Member types Copy Chapter

• number_integer_t - BasicJsonType's type for numbers (integer)
• number_unsigned_t - BasicJsonType's type for numbers (unsigned)
• number_float_t - BasicJsonType's type for numbers (floating-point)
• string_t - BasicJsonType's type for strings
• binary_t - BasicJsonType's type for binary arrays

Member functions Copy Chapter

• binary (virtual) - a binary value was read
• boolean (virtual) - a boolean value was read
• end_array (virtual) - the end of an array was read
• end_object (virtual) - the end of an object was read
• key (virtual) - an object key was read
• null (virtual) - a null value was read
• number_float (virtual) - a floating-point number was read
• number_integer (virtual) - an integer number was read
• number_unsigned (virtual) - an unsigned integer number was read
• parse_error (virtual) - a parse error occurred
• start_array (virtual) - the beginning of an array was read
• start_object (virtual) - the beginning of an object was read
• string (virtual) - a string value was read

Version history Copy Chapter

• Added in version 3.2.0.
• Support for binary values (binary_t, binary) added in version 3.8.0.

Third Party Nlohmann Json Docs Mkdocs Docs Api Macros Index (`third_party/nlohmann_json/docs/mkdocs/docs/api/macros/index.md`) Copy Section

Macros

Some aspects of the library can be configured by defining preprocessor macros before including the json.hpp
header. See also the macro overview page.

Runtime assertions Copy Chapter

• JSON_ASSERT(x) - control behavior of runtime assertions

Exceptions Copy Chapter

• **JSON_CATCH_USER(exception)****JSON_THROW_USER(exception)**JSON_TRY_USER - control exceptions
• JSON_DIAGNOSTICS - control extended diagnostics
• JSON_NOEXCEPTION - switch off exceptions

Language support Copy Chapter

• JSON_HAS_CPP_11JSON_HAS_CPP_14JSON_HAS_CPP_17****JSON_HAS_CPP_20 - set supported C++ standard
• JSON_HAS_FILESYSTEM****JSON_HAS_EXPERIMENTAL_FILESYSTEM - control std::filesystem support
• JSON_HAS_RANGES - control std::ranges support
• JSON_HAS_THREE_WAY_COMPARISON - control 3-way comparison support
• JSON_NO_IO - switch off functions relying on certain C++ I/O headers
• JSON_SKIP_UNSUPPORTED_COMPILER_CHECK - do not warn about unsupported compilers
• JSON_USE_GLOBAL_UDLS - place user-defined string literals (UDLs) into the global namespace

Library version Copy Chapter

• JSON_SKIP_LIBRARY_VERSION_CHECK - skip library version check
• NLOHMANN_JSON_VERSION_MAJORNLOHMANN_JSON_VERSION_MINORNLOHMANN_JSON_VERSION_PATCH
  - library version information

Library namespace Copy Chapter

• NLOHMANN_JSON_NAMESPACE - full name of the nlohmann namespace
• NLOHMANN_JSON_NAMESPACE_BEGIN****NLOHMANN_JSON_NAMESPACE_END - open and
  close the library namespace
• NLOHMANN_JSON_NAMESPACE_NO_VERSION - disable the version component of
  the inline namespace

Type conversions Copy Chapter

• JSON_DISABLE_ENUM_SERIALIZATION - switch off default serialization/deserialization functions for enums
• JSON_USE_IMPLICIT_CONVERSIONS - control implicit conversions

Comparison behavior Copy Chapter

• JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON -
  control comparison of discarded values

Serialization/deserialization macros Copy Chapter

• **NLOHMANN_DEFINE_TYPE_INTRUSIVE(type, member...)**NLOHMANN_DEFINE_TYPE_INTRUSIVE_WITH_DEFAULT(type, member...)
  NLOHMANN_DEFINE_TYPE_INTRUSIVE_ONLY_SERIALIZE(type, member...)
  - serialization/deserialization of types with access to private variables
• **NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(type, member...)**NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT(type, member...)
  NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_ONLY_SERIALIZE(type, member...)
  - serialization/deserialization of types without access to private variables
• NLOHMANN_JSON_SERIALIZE_ENUM(type, ...) - serialization/deserialization of enum types

Third Party Nlohmann Json Docs Mkdocs Docs Features Binary Formats Index (`third_party/nlohmann_json/docs/mkdocs/docs/features/binary_formats/index.md`) Copy Section

Binary Formats

Though JSON is a ubiquitous data format, it is not a very compact format suitable for data exchange, for instance over
a network. Hence, the library supports

• BJData (Binary JData),
• BSON (Binary JSON),
• CBOR (Concise Binary Object Representation),
• MessagePack, and
• UBJSON (Universal Binary JSON)

to efficiently encode JSON values to byte vectors and to decode such vectors.

Comparison Copy Chapter

Completeness Copy Section

Binary values Copy Section

See binary values for more information.

Sizes Copy Section

Sizes compared to minified JSON value.

Third Party Nlohmann Json Docs Mkdocs Docs Features Element Access Index (`third_party/nlohmann_json/docs/mkdocs/docs/features/element_access/index.md`) Copy Section

Element Access

There are many ways elements in a JSON value can be accessed:

• unchecked access via operator[]
• checked access via at
• access with default value via value
• iterators
• JSON pointers

Third Party Nlohmann Json Docs Mkdocs Docs Features Parsing Index (`third_party/nlohmann_json/docs/mkdocs/docs/features/parsing/index.md`) Copy Section

Parsing

!!! note

This page is under construction.

Input Copy Chapter

SAX vs. DOM parsing Copy Chapter

Exceptions Copy Chapter

See parsing and exceptions.

Third Party Nlohmann Json Docs Mkdocs Docs Features Types Index (`third_party/nlohmann_json/docs/mkdocs/docs/features/types/index.md`) Copy Section

Types

This page gives an overview how JSON values are stored and how this can be configured.

Overview Copy Chapter

By default, JSON values are stored as follows:

Note there are three different types for numbers - when parsing JSON text, the best fitting type is chosen.

Storage Copy Chapter

enum value_t {
    null
    object
    array
    string
    boolean
    number_integer
    number_unsigned
    number_float
    binary
    discarded
}

class json_value << (U,orchid) >> {
    object_t* object
    array_t* array
    string_t* string
    binary_t* binary
    boolean_t boolean
    number_integer_t number_integer
    number_unsigned_t number_unsigned
    number_float_t number_float
}

class basic_json {
    -- type and value --
    value_t m_type
    json_value m_value
    -- derived types --
    + <u>typedef</u> object_t
    + <u>typedef</u> array_t
    + <u>typedef</u> binary_t
    + <u>typedef</u> boolean_t
    + <u>typedef</u> number_integer_t
    + <u>typedef</u> number_unsigned_t
    + <u>typedef</u> number_float_t
}

basic_json .. json_value
basic_json .. value_t

Template arguments Copy Chapter

The data types to store a JSON value are derived from the template arguments passed to class basic_json:

template<
    template<typename U, typename V, typename... Args> class ObjectType = std::map,
    template<typename U, typename... Args> class ArrayType = std::vector,
    class StringType = std::string,
    class BooleanType = bool,
    class NumberIntegerType = std::int64_t,
    class NumberUnsignedType = std::uint64_t,
    class NumberFloatType = double,
    template<typename U> class AllocatorType = std::allocator,
    template<typename T, typename SFINAE = void> class JSONSerializer = adl_serializer,
    class BinaryType = std::vector<std::uint8_t>
>
class basic_json;

Type json is an alias for basic_json<> and uses the default types.

From the template arguments, the following types are derived:

using object_comparator_t = std::less<>;
using object_t = ObjectType<StringType, basic_json, object_comparator_t,
                   AllocatorType<std::pair<const StringType, basic_json>>>;

using array_t = ArrayType<basic_json, AllocatorType<basic_json>>;

using string_t = StringType;

using boolean_t = BooleanType;

using number_integer_t = NumberIntegerType;
using number_unsigned_t = NumberUnsignedType;
using number_float_t = NumberFloatType;

using binary_t = nlohmann::byte_container_with_subtype<BinaryType>;

Objects Copy Chapter

RFC 8259 describes JSON objects as follows:

An object is an unordered collection of zero or more name/value pairs, where a name is a string and a value is a string, number, boolean, null, object, or array.

Default type Copy Section

With the default values for ObjectType (std::map), StringType (std::string), and AllocatorType (std::allocator), the default value for object_t is:

std::map<
  std::string, // key_type
  basic_json, // value_type
  std::less<>, // key_compare
  std::allocator<std::pair<const std::string, basic_json>> // allocator_type
>

Behavior Copy Section

The choice of object_t influences the behavior of the JSON class. With the default type, objects have the following behavior:

• When all names are unique, objects will be interoperable in the sense that all software implementations receiving that object will agree on the name-value mappings.
• When the names within an object are not unique, it is unspecified which one of the values for a given key will be chosen. For instance, #!json {"key": 2, "key": 1} could be equal to either #!json {"key": 1} or #!json {"key": 2}.
• Internally, name/value pairs are stored in lexicographical order of the names. Objects will also be serialized (see dump) in this order. For instance, both #!json {"b": 1, "a": 2} and #!json {"a": 2, "b": 1} will be stored and serialized as #!json {"a": 2, "b": 1}.
• When comparing objects, the order of the name/value pairs is irrelevant. This makes objects interoperable in the sense that they will not be affected by these differences. For instance, #!json {"b": 1, "a": 2} and #!json {"a": 2, "b": 1} will be treated as equal.

Key order Copy Section

The order name/value pairs are added to the object is not preserved by the library. Therefore, iterating an object may return name/value pairs in a different order than they were originally stored. In fact, keys will be traversed in alphabetical order as std::map with std::less is used by default. Please note this behavior conforms to RFC 8259, because any order implements the specified "unordered" nature of JSON objects.

Limits Copy Section

RFC 8259 specifies:

An implementation may set limits on the maximum depth of nesting.

In this class, the object's limit of nesting is not explicitly constrained. However, a maximum depth of nesting may be introduced by the compiler or runtime environment. A theoretical limit can be queried by calling the max_size function of a JSON object.

Storage Copy Section

Objects are stored as pointers in a basic_json type. That is, for any access to object values, a pointer of type object_t* must be dereferenced.

Arrays Copy Chapter

RFC 8259 describes JSON arrays as follows:

An array is an ordered sequence of zero or more values.

Default type Copy Section

With the default values for ArrayType (std::vector) and AllocatorType (std::allocator), the default value for array_t is:

std::vector<
  basic_json, // value_type
  std::allocator<basic_json> // allocator_type
>

Limits Copy Section

RFC 8259 specifies:

An implementation may set limits on the maximum depth of nesting.

In this class, the array's limit of nesting is not explicitly constrained. However, a maximum depth of nesting may be introduced by the compiler or runtime environment. A theoretical limit can be queried by calling the max_size function of a JSON array.

Storage Copy Section

Arrays are stored as pointers in a basic_json type. That is, for any access to array values, a pointer of type array_t* must be dereferenced.

Strings Copy Chapter

RFC 8259 describes JSON strings as follows:

A string is a sequence of zero or more Unicode characters.

Unicode values are split by the JSON class into byte-sized characters during deserialization.

Default type Copy Section

With the default values for StringType (std::string), the default value for string_t is #!cpp std::string.

Encoding Copy Section

Strings are stored in UTF-8 encoding. Therefore, functions like std::string::size() or std::string::length() return the number of bytes in the string rather than the number of characters or glyphs.

String comparison Copy Section

RFC 8259 states:

Software implementations are typically required to test names of object members for equality. Implementations that transform the textual representation into sequences of Unicode code units and then perform the comparison numerically, code unit by code unit, are interoperable in the sense that implementations will agree in all cases on equality or inequality of two strings. For example, implementations that compare strings with escaped characters unconverted may incorrectly find that "a\\b" and "a\u005Cb" are not equal.

This implementation is interoperable as it does compare strings code unit by code unit.

Storage Copy Section

String values are stored as pointers in a basic_json type. That is, for any access to string values, a pointer of type string_t* must be dereferenced.

Booleans Copy Chapter

RFC 8259 implicitly describes a boolean as a type which differentiates the two literals true and false.

Default type Copy Section

With the default values for BooleanType (#!cpp bool), the default value for boolean_t is #!cpp bool.

Storage Copy Section

Boolean values are stored directly inside a basic_json type.

Numbers Copy Chapter

See the number handling article for a detailed discussion on how numbers are handled by this library.

RFC 8259 describes numbers as follows:

The representation of numbers is similar to that used in most programming languages. A number is represented in base 10 using decimal digits. It contains an integer component that may be prefixed with an optional minus sign, which may be followed by a fraction part and/or an exponent part. Leading zeros are not allowed. (...) Numeric values that cannot be represented in the grammar below (such as Infinity and NaN) are not permitted.

This description includes both integer and floating-point numbers. However, C++ allows more precise storage if it is known whether the number is a signed integer, an unsigned integer or a floating-point number. Therefore, three different types, number_integer_t, number_unsigned_t, and number_float_t are used.

Default types Copy Section

With the default values for NumberIntegerType (std::int64_t), the default value for number_integer_t is std::int64_t.
With the default values for NumberUnsignedType (std::uint64_t), the default value for number_unsigned_t is std::uint64_t.
With the default values for NumberFloatType (#!cpp double), the default value for number_float_t is #!cpp double.

Default behavior Copy Section

• The restrictions about leading zeros is not enforced in C++. Instead, leading zeros in integer literals lead to an interpretation as octal number. Internally, the value will be stored as decimal number. For instance, the C++ integer literal #!c 010 will be serialized to #!c 8. During deserialization, leading zeros yield an error.
• Not-a-number (NaN) values will be serialized to #!json null.

Limits Copy Section

RFC 8259 specifies:

An implementation may set limits on the range and precision of numbers.

When the default type is used, the maximal integer number that can be stored is #!c 9223372036854775807 (INT64_MAX) and the minimal integer number that can be stored is #!c -9223372036854775808 (INT64_MIN). Integer numbers that are out of range will yield over/underflow when used in a constructor. During deserialization, too large or small integer numbers will be automatically be stored as number_unsigned_t or number_float_t.

When the default type is used, the maximal unsigned integer number that can be stored is #!c 18446744073709551615 (UINT64_MAX) and the minimal integer number that can be stored is #!c 0. Integer numbers that are out of range will yield over/underflow when used in a constructor. During deserialization, too large or small integer numbers will be automatically be stored as number_integer_t or number_float_t.

RFC 8259 further states:

Note that when such software is used, numbers that are integers and are in the range $[-2^{53}+1, 2^{53}-1]$ are interoperable in the sense that implementations will agree exactly on their numeric values.

As this range is a subrange of the exactly supported range [INT64_MIN, INT64_MAX], this class's integer type is interoperable.

RFC 8259 states:

This specification allows implementations to set limits on the range and precision of numbers accepted. Since software that implements IEEE 754-2008 binary64 (double precision) numbers is generally available and widely used, good interoperability can be achieved by implementations that expect no more precision or range than these provide, in the sense that implementations will approximate JSON numbers within the expected precision.

This implementation does exactly follow this approach, as it uses double precision floating-point numbers. Note values smaller than #!c -1.79769313486232e+308 and values greater than #!c 1.79769313486232e+308 will be stored as NaN internally and be serialized to #!json null.

Storage Copy Section

Integer number values, unsigned integer number values, and floating-point number values are stored directly inside a basic_json type.

README CN (`docs/README-CN.md`) Copy Section

目录

• 欢迎来到 TEN
• 代理示例
• 代理示例快速上手
  • 本地环境
  • Codespaces
• 代理示例自托管
  • 使用 Docker 部署
  • 部署到其他云服务
• 保持关注
• TEN 生态
• 常见问题
• 参与贡献
  • 代码贡献者
  • 贡献指南
  • 许可证

欢迎来到 TEN Copy Chapter

TEN 是一个面向语音对话 AI 代理的开源框架。

TEN 生态 包含 TEN Framework、代理示例、VAD、Turn Detection 以及 Portal。

社区渠道	用途
	在 X 上关注 TEN Framework，获取更新与公告
	加入 Discord 社区，与开发者交流
	在 LinkedIn 上关注 TEN Framework，获取动态和公告
	加入 Hugging Face 社区，探索我们的空间与模型
	加入微信社群，与中文社区讨论

代理示例 Copy Chapter

多用途语音助手 —— 低延迟、高质量的实时助手，可通过 记忆、VAD、回合检测 等扩展能力进行增强。

详见 示例代码。

Doodler —— 将语音或文本提示转换为手绘风格涂鸦的画板，配有蜡笔调色板并支持实时绘制。

示例代码

唇形同步头像 —— 适配多个头像供应商，演示中包含 Live2D 唇形同步的动漫角色 Kei，并即将支持 Trulience、HeyGen、Tavus 等写实头像。

查看 Live2D 示例代码。

语音分离（Diarization） —— 实时检测并标记不同说话人，“Who Likes What” 游戏展示了一个交互式场景。

示例代码

SIP 通话 —— 通过 TEN 提供电话功能的 SIP 扩展。

示例代码

转写（Transcription） —— 将音频实时转换为文本的工具。

示例代码

ESP32-S3 Korvo V3 —— 在 Espressif ESP32-S3 Korvo V3 开发板上运行 TEN 代理示例，让硬件具备 LLM 驱动的交互能力。

更多细节请参阅 集成指南。

代理示例快速上手 Copy Chapter

本地环境 Copy Section

步骤 ⓵ - 前置条件

如果在国内，我们强烈建议在 SSH 中把代理打开，下载和安装的依赖的时候会更加丝滑。

# 如果用的代理软件没有增强模式的话， 建议手动把所有代理协议都打开
# export 的有效期为一个 session
export https_proxy=http://127.0.0.1:<port>
export http_proxy=http://127.0.0.1:<port>
export all_proxy=socks5://127.0.0.1:<port>

# Docker
export https_proxy=http://host.docker.internal:<port>
export http_proxy=http://host.docker.internal:<port>
export all_proxy=http://host.docker.internal:<port>

# tman 镜像设置
mkdir -p ~/.tman && echo '{
  "registry": {
    "default": {
      "index": "https://registry-ten.rtcdeveloper.cn/api/ten-cloud-store/v1/packages"
    }
  }
}' > ~/.tman/config.json

# GO 代理设置
export GOPROXY=https://goproxy.cn,direct

# pip 代理设置, 此设置需要先安装 pip
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple

步骤 ⓶ - 在虚拟机中构建代理示例

1. 克隆仓库，进入 `ai_agents`，并用 `.env.example` 创建 `.env`

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

2. 在 `.env` 中配置 Agora App ID 与 App Certificate

AGORA_APP_ID=
AGORA_APP_CERTIFICATE=

# 运行默认的语音助手示例
# Deepgram（语音转文本所需）
DEEPGRAM_API_KEY=your_deepgram_api_key_here

# OpenAI（语言模型所需）
OPENAI_API_KEY=your_openai_api_key_here
OPENAI_MODEL=gpt-4o

# ElevenLabs（语音合成所需）
ELEVENLABS_TTS_KEY=your_elevenlabs_api_key_here

3. 启动代理开发容器

docker compose up -d

4. 进入容器

docker exec -it ten_agent_dev bash

5. 使用默认示例构建代理（约 5-8 分钟）

在 agents/examples 文件夹中可以找到更多示例。
从以下默认示例之一开始：

# 使用串联语音助手
cd agents/examples/voice-assistant

# 或者使用实时语音对话助手
cd agents/examples/voice-assistant-realtime

6. 启动 Web 服务

首次启动前，以及依赖或 Go 源码发生变化后，请运行 task install。它会安装 TEN、Python 和前端依赖，并构建 Go API 服务。仅修改 Python 源码时无需重新安装。

task install
task run

7. 访问代理

启动示例后，可以访问以下界面：

• TMAN Designer：http://localhost:49483
• 代理示例界面：http://localhost:3000

步骤 ⓷ - 自定义代理示例

1. 打开 localhost:49483。
2. 右键单击 STT、LLM、TTS 扩展。
3. 在属性面板中填写对应的 API Key。
4. 提交更改后，即可在 localhost:3000 查看更新效果。

在不使用 Docker 的情况下从 TEN Manager 运行转录应用（Beta）

TEN 还提供了一个转录应用，无需 Docker 即可直接在 TEN Manager 中运行。

详情请查看快速入门指南。

Codespaces Copy Section

GitHub 为每个仓库提供免费的 Codespaces。无需 Docker 即可运行代理示例，并且通常比本地 Docker 环境启动更快。

更多细节请查看这篇指南。

代理示例自托管 Copy Chapter

使用 Docker 部署 Copy Section

当你通过 TMAN Designer 或直接编辑 property.json 自定义完代理后，可以为服务构建发布用的 Docker 镜像并部署。

以 Docker 镜像方式发布

注意：以下命令需在 Docker 容器外部执行。

构建镜像

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

运行

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

部署到其他云服务 Copy Section

若需将 TEN 部署到 Vercel、Netlify 等平台，可以拆分为前后端两部分：

1. 在任意支持容器的平台（Docker 主机、Fly.io、Render、ECS、Cloud Run 等）运行 TEN 后端。直接使用示例镜像，开放 8080 端口。
2. 仅部署前端到 Vercel 或 Netlify。将项目根目录指向 ai_agents/agents/examples/<example>/frontend，执行 pnpm install（或 bun install）与 pnpm build（或 bun run build），并保留默认 .next 输出。
3. 在托管平台的环境变量面板设置 AGENT_SERVER_URL 指向后端 URL，同时配置前端需要的 NEXT_PUBLIC_* 变量（例如需要暴露给浏览器的 Agora 凭据）。
4. 确保后端允许来自前端域名的请求，可通过开放 CORS 或使用内置代理中间件。

这样后端负责长时间运行的工作进程，托管前端只需将 API 请求转发给后端即可。

保持关注 Copy Chapter

实时获取版本更新与最新动态。你的支持能帮助 TEN 变得更好！

TEN 生态 Copy Chapter

项目	预览
️TEN Framework面向对话式 AI 代理的开源框架。
TEN VAD低延迟、轻量且高性能的流式语音活动检测。
️TEN Turn Detection实现全双工对话的回合检测。
TEN Agent Examples基于 TEN 的多种应用示例。
TEN PortalTEN 官方站点，提供文档与博客。

常见问题 Copy Chapter

TEN Framework 也可通过以下 AI 驱动的问答平台获取信息，它们支持多语言检索，覆盖从基础配置到高级实践的内容。

服务	链接
DeepWiki
ReadmeX

参与贡献 Copy Chapter

欢迎所有形式的开源协作！无论是修复缺陷、添加功能、改进文档还是分享创意，你的参与都能推动个性化 AI 工具向前发展。访问 GitHub Issues 与 Projects 寻找合适的任务，展示你的技能，让我们一起构建更出色的 TEN！

[!TIP]

欢迎所有类型的贡献 🙏

帮助我们让 TEN 变得更好！从代码到文档，每一次贡献都弥足珍贵。也欢迎在社交平台分享你的 TEN 代理项目，激励更多创作者。

可以通过 𝕏 上的 @elliotchen200 或 GitHub 上的 @cyfyifanchen 与维护者联系，获取项目动态、讨论与合作机会。

代码贡献者 Copy Section

贡献指南 Copy Section

欢迎贡献！在提交之前，请先阅读贡献指南。

许可证 Copy Section

1. 除下列目录外，TEN Framework 均以 Apache License 2.0（附加条款）发布，详见根目录下的 LICENSE 文件。
2. packages 目录中的组件以 Apache License 2.0 发布，详情请参考各组件根目录内的 LICENSE 文件。
3. TEN Framework 使用的第三方库均在 third_party 目录中列出并说明。

README ES (`docs/README-ES.md`) Copy Section

Tabla de contenido

• Bienvenido a TEN
• Ejemplos de agente
• Inicio rápido con los ejemplos de agente
  • Entorno local
  • Codespaces
• Auto-hospedaje de los ejemplos de agente
  • Implementar con Docker
  • Implementar en otros servicios en la nube
• Mantente al día
• Ecosistema TEN
• Preguntas
• Cómo contribuir
  • Personas contribuidoras
  • Guía de contribución
  • Licencia

Bienvenido a TEN Copy Chapter

TEN es un marco de código abierto para agentes conversacionales de voz impulsados por IA.

El ecosistema TEN incluye TEN Framework, Ejemplos de agente, VAD, Turn Detection y Portal.

Canal de la comunidad	Propósito
	Sigue TEN Framework en X para enterarte de novedades y anuncios
	Únete a la comunidad de Discord y conecta con otras personas desarrolladoras
	Sigue TEN Framework en LinkedIn para recibir actualizaciones y noticias
	Explora nuestros espacios y modelos en la comunidad de Hugging Face
	Únete al grupo de WeChat para conversar con la comunidad china

Ejemplos de agente Copy Chapter

Asistente de voz multipropósito — Un asistente en tiempo real, de baja latencia y alta calidad que puedes ampliar con memoria, VAD, detección de turnos y otras extensiones.

Consulta el código de ejemplo para obtener más detalles.

Doodler — Un tablero de garabatos que convierte indicaciones habladas o escritas en bocetos sencillos a mano, con una paleta de crayones y dibujo en tiempo real.

Código de ejemplo

Avatares con sincronización labial — Compatible con múltiples proveedores de avatares. La demo incluye a Kei, un personaje anime con sincronización labial gracias a Live2D, y pronto añadirá avatares realistas de Trulience, HeyGen y Tavus.

Revisa el código de ejemplo para Live2D.

Diarización de voz — Detección y etiquetado de hablantes en tiempo real. El juego "Who Likes What" muestra un caso de uso interactivo.

Código de ejemplo

Llamada SIP — Extensión SIP que habilita llamadas telefónicas impulsadas por TEN.

Código de ejemplo

Transcripción — Herramienta de transcripción que convierte audio en texto.

Código de ejemplo

ESP32-S3 Korvo V3 — Ejecuta el ejemplo de TEN Agent en la placa de desarrollo Espressif ESP32-S3 Korvo V3 para integrar comunicación impulsada por LLM con hardware.

Consulta la guía de integración para conocer más.

Inicio rápido con los ejemplos de agente Copy Chapter

Entorno local Copy Section

Paso ⓵ - Requisitos previos

Paso ⓶ - Compila los ejemplos dentro de una VM

1. Clona el repositorio, entra en `ai_agents` y crea un `.env` a partir de `.env.example`

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

2. Configura el Agora App ID y App Certificate en `.env`

AGORA_APP_ID=
AGORA_APP_CERTIFICATE=

# Ejecutar el ejemplo predeterminado del asistente de voz
# Deepgram (requerido para STT)
DEEPGRAM_API_KEY=your_deepgram_api_key_here

# OpenAI (requerido para el modelo de lenguaje)
OPENAI_API_KEY=your_openai_api_key_here
OPENAI_MODEL=gpt-4o

# ElevenLabs (requerido para TTS)
ELEVENLABS_TTS_KEY=your_elevenlabs_api_key_here

3. Inicia los contenedores de desarrollo del agente

docker compose up -d

4. Entra en el contenedor

docker exec -it ten_agent_dev bash

5. Compila el agente con el ejemplo predeterminado (≈5‑8 min)

En la carpeta agents/examples encontrarás más muestras.
Empieza con una de estas opciones:

# Usa el asistente de voz encadenado
cd agents/examples/voice-assistant

# O usa el asistente voz-a-voz en tiempo real
cd agents/examples/voice-assistant-realtime

6. Inicia el servidor web

Ejecuta task install antes del primer inicio y después de cambiar las dependencias o el código fuente de Go. Este comando instala las dependencias de TEN, Python y frontend, y compila el servidor API de Go. Los cambios que solo afectan a Python no requieren reinstalación.

task install
task run

7. Accede al agente

Cuando el ejemplo esté en marcha podrás usar estas interfaces:

• TMAN Designer: http://localhost:49483
• UI de ejemplos de agente: http://localhost:3000

Paso ⓷ - Personaliza tu ejemplo de agente

1. Abre localhost:49483.
2. Haz clic derecho en las extensiones STT, LLM y TTS.
3. Rellena sus propiedades con las API keys correspondientes.
4. Envía los cambios; el ejemplo actualizado aparecerá en localhost:3000.

Ejecuta una app de transcripción desde TEN Manager sin Docker (Beta)

TEN también ofrece una app de transcripción que puedes ejecutar en TEN Manager sin usar Docker.

Consulta la guía de inicio rápido para más detalles.

Codespaces Copy Section

GitHub ofrece Codespaces gratuitos para cada repositorio. Puedes ejecutar los ejemplos de agente allí sin usar Docker, y normalmente inicia más rápido que un entorno local con contenedores.

Consulta esta guía para obtener más detalles.

Auto-hospedaje de los ejemplos de agente Copy Chapter

Implementar con Docker Copy Section

Cuando personalices tu agente (ya sea con TMAN Designer o editando property.json), crea una imagen de Docker lista para producción y despliega tu servicio.

Publicar como imagen de Docker

Nota: Ejecuta estos comandos fuera de cualquier contenedor Docker.

Compilar la imagen

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

Ejecutar

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

Implementar en otros servicios en la nube Copy Section

Puedes dividir el despliegue en dos partes si deseas alojar TEN en proveedores como Vercel o Netlify.

1. Ejecuta el backend de TEN en cualquier plataforma preparada para contenedores (una VM con Docker, Fly.io, Render, ECS, Cloud Run, etc.). Usa la imagen de ejemplo sin modificar y expón el puerto 8080.
2. Despliega solo el frontend en Vercel o Netlify. Apunta la raíz del proyecto a ai_agents/agents/examples/<example>/frontend, ejecuta pnpm install (o bun install), luego pnpm build (o bun run build) y conserva el directorio de salida .next predeterminado.
3. Configura las variables de entorno en el panel de tu hosting. AGENT_SERVER_URL debe apuntar al backend y añade cualquier clave NEXT_PUBLIC_* necesaria (por ejemplo, credenciales de Agora visibles para el navegador).
4. Asegúrate de que tu backend acepte solicitudes desde el origen del frontend, ya sea mediante CORS abierto o usando el middleware proxy incluido.

Con esta arquitectura, el backend gestiona los procesos de larga duración y el frontend alojado solo reenvía el tráfico al backend.

Mantente al día Copy Chapter

Recibe notificaciones instantáneas sobre nuevas versiones y actualizaciones. Tu apoyo nos ayuda a seguir mejorando TEN.

Ecosistema TEN Copy Chapter

Proyecto	Vista previa
️TEN FrameworkMarco de código abierto para agentes conversacionales.
TEN VADDetector de actividad de voz (VAD) en streaming, ligero y de baja latencia.
️TEN Turn DetectionPermite diálogo full-duplex mediante detección de turnos.
TEN Agent ExamplesCasos de uso impulsados por TEN.
TEN PortalSitio oficial con documentación y blog.

Preguntas Copy Chapter

TEN Framework también está disponible en plataformas de preguntas y respuestas impulsadas por IA. Ofrecen soporte multilingüe para todo, desde la configuración básica hasta la implementación avanzada.

Servicio	Enlace
DeepWiki
ReadmeX

Cómo contribuir Copy Chapter

¡Toda forma de colaboración de código abierto es bienvenida! Ya sea que corrijas bugs, agregues funciones, mejores la documentación o compartas ideas, tus aportes ayudan a impulsar herramientas de IA personalizadas. Revisa los Issues y Projects de GitHub para encontrar oportunidades y mostrar tus habilidades. ¡Construyamos juntas y juntos algo increíble!

[!TIP]

Agradecemos todo tipo de contribuciones 🙏

Acompáñanos a mejorar TEN. Cada PR, issue o guía suma. Comparte tus proyectos con TEN Agent en redes sociales para inspirar a la comunidad.

Ponte en contacto con la persona mantenedora @elliotchen200 en 𝕏 o @cyfyifanchen en GitHub para recibir novedades, debatir ideas y explorar colaboraciones.

Personas contribuidoras Copy Section

Guía de contribución Copy Section

¡Contribuye cuando quieras! Lee primero la guía de contribución.

Licencia Copy Section

1. Todo TEN Framework, salvo los directorios listados más abajo, se publica bajo la licencia Apache 2.0 con restricciones adicionales. Consulta el archivo LICENSE en la raíz del proyecto.
2. Los componentes dentro de packages se liberan bajo Apache License 2.0. Cada paquete contiene su propio archivo LICENSE con los detalles.
3. Las dependencias de terceros que usa TEN Framework se describen en la carpeta third_party.

README FR (`docs/README-FR.md`) Copy Section

Table des matières

• Bienvenue chez TEN
• Exemples d’agents
• Démarrage rapide avec les exemples d’agents
  • En local
  • Codespaces
• Auto-hébergement des exemples d’agents
  • Déployer avec Docker
  • Déployer sur d’autres services cloud
• Restez informé·e
• Écosystème TEN
• Questions
• Contribuer
  • Contributrices et contributeurs
  • Guide de contribution
  • Licence

Bienvenue chez TEN Copy Chapter

TEN est un framework open source pour créer des agents conversationnels vocaux pilotés par l’IA.

L’écosystème TEN comprend TEN Framework, les Exemples d’agents, VAD, Turn Detection et Portal.

Canal communautaire	Objectif
	Suivez TEN Framework sur X pour connaître les nouveautés et annonces
	Rejoignez notre communauté Discord pour échanger avec d’autres développeurs
	Abonnez-vous sur LinkedIn afin de recevoir nos actualités
	Découvrez nos espaces et modèles sur Hugging Face
	Rejoignez le groupe WeChat pour discuter avec la communauté chinoise

Exemples d’agents Copy Chapter

Assistant vocal polyvalent — Assistant temps réel, basse latence et haute qualité, extensible avec des modules de mémoire, de VAD, de détection de tours, etc.

Consultez le code d’exemple pour en savoir plus.

Doodler — Un tableau de gribouillage qui transforme des prompts parlés ou saisis en croquis simples dessinés à la main, avec une palette de crayons et un dessin en temps réel.

Code d’exemple

Avatars avec synchronisation labiale — Compatible avec plusieurs fournisseurs d’avatars. La démo met en scène Kei, un personnage animé avec synchronisation labiale Live2D, et proposera bientôt des avatars réalistes de Trulience, HeyGen et Tavus.

Voir le code d’exemple Live2D.

Diarisation vocale — Détection et étiquetage des locuteurs en temps réel. Le jeu "Who Likes What" illustre un cas d’usage interactif.

Code d’exemple

Appels SIP — Extension SIP qui permet d’effectuer des appels téléphoniques propulsés par TEN.

Code d’exemple

Transcription — Outil de transcription qui convertit la voix en texte.

Code d’exemple

ESP32-S3 Korvo V3 — Fait tourner un exemple TEN Agent sur la carte de développement Espressif ESP32-S3 Korvo V3 pour relier communication LLM et matériel.

Voir le guide d’intégration pour plus d’informations.

Démarrage rapide avec les exemples d’agents Copy Chapter

En local Copy Section

Étape ⓵ - Prérequis

Étape ⓶ - Compiler les exemples dans une VM

1. Clonez le dépôt, placez-vous dans `ai_agents` et créez `.env` à partir de `.env.example`

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

2. Configurez Agora App ID et App Certificate dans `.env`

AGORA_APP_ID=
AGORA_APP_CERTIFICATE=

# Exécuter l’exemple d’assistant vocal par défaut
# Deepgram (requis pour la transcription)
DEEPGRAM_API_KEY=your_deepgram_api_key_here

# OpenAI (requis pour le modèle de langage)
OPENAI_API_KEY=your_openai_api_key_here
OPENAI_MODEL=gpt-4o

# ElevenLabs (requis pour la synthèse vocale)
ELEVENLABS_TTS_KEY=your_elevenlabs_api_key_here

3. Lancez les conteneurs de développement

docker compose up -d

4. Entrez dans le conteneur

docker exec -it ten_agent_dev bash

5. Compilez l’agent avec l’exemple par défaut (~5-8 min)

D’autres exemples sont disponibles dans agents/examples.
Commencez par l’une des options suivantes :

# Assistant vocal chaîné
cd agents/examples/voice-assistant

# Assistant voix-à-voix temps réel
cd agents/examples/voice-assistant-realtime

6. Démarrez le serveur web

Exécutez task install avant le premier lancement et après toute modification des dépendances ou du code source Go. Cette commande installe les dépendances TEN, Python et frontend, puis compile le serveur API Go. Les modifications portant uniquement sur Python ne nécessitent pas de nouvelle installation.

task install
task run

7. Accédez à l’agent

Une fois l’exemple démarré, ces interfaces sont disponibles :

• TMAN Designer : http://localhost:49483
• Interface des exemples : http://localhost:3000

Étape ⓷ - Personnaliser votre exemple

1. Ouvrez localhost:49483.
2. Cliquez droit sur les extensions STT, LLM et TTS.
3. Renseignez les clés API correspondantes.
4. Validez : la mise à jour apparaît sur localhost:3000.

Exécuter une application de transcription depuis TEN Manager sans Docker (Beta)

TEN propose aussi une application de transcription que vous pouvez lancer dans TEN Manager sans utiliser Docker.

Consultez le guide de démarrage rapide pour en savoir plus.

Codespaces Copy Section

GitHub fournit des Codespaces gratuits par dépôt. Vous pouvez exécuter les exemples d’agents sans Docker, avec des temps de démarrage souvent plus courts qu’en local.

Consultez ce guide pour plus d’informations.

Auto-hébergement des exemples d’agents Copy Chapter

Déployer avec Docker Copy Section

Après avoir personnalisé votre agent (via TMAN Designer ou en modifiant property.json), générez une image Docker prête pour la production et déployez votre service.

Publier en image Docker

Remarque : exécutez ces commandes hors de tout conteneur Docker.

Construire l’image

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

Exécuter

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

Déployer sur d’autres services cloud Copy Section

Divisez le déploiement en deux parties pour héberger TEN sur des plateformes comme Vercel ou Netlify.

1. Exécutez le backend TEN sur une plateforme compatible conteneurs (VM Docker, Fly.io, Render, ECS, Cloud Run, etc.). Utilisez l’image fournie et exposez le port 8080.
2. Déployez uniquement le frontend sur Vercel ou Netlify. Pointez la racine du projet vers ai_agents/agents/examples/<example>/frontend, lancez pnpm install (ou bun install) puis pnpm build (ou bun run build) et conservez le répertoire .next par défaut.
3. Dans le tableau de bord d’hébergement, définissez AGENT_SERVER_URL vers l’URL du backend et ajoutez les variables NEXT_PUBLIC_* nécessaires (comme les identifiants Agora côté navigateur).
4. Autorisez le frontend à contacter le backend via CORS ouvert ou le middleware proxy intégré.

Ainsi, le backend gère les workers longue durée tandis que le frontend hébergé achemine simplement les requêtes.

Restez informé·e Copy Chapter

Recevez instantanément les nouvelles versions et les mises à jour. Votre soutien nous aide à faire grandir TEN.

Écosystème TEN Copy Chapter

Projet	Aperçu
️TEN FrameworkFramework open source pour agents conversationnels.
TEN VADDétecteur d’activité vocale (VAD) léger et à faible latence.
️TEN Turn DetectionPermet des dialogues full-duplex grâce à la détection de tours.
TEN Agent ExamplesCas d'usage construits avec TEN.
TEN PortalSite officiel avec documentation et blog.

Questions Copy Chapter

TEN Framework est présent sur des plateformes de questions/réponses alimentées par l’IA. Elles fournissent des réponses multilingues, de la configuration de base aux cas avancés.

Service	Lien
DeepWiki
ReadmeX

Contribuer Copy Chapter

Nous accueillons toute forme de collaboration open source ! Corrections de bugs, nouvelles fonctionnalités, documentation ou idées : vos contributions font progresser les outils d’IA personnalisés. Consultez les Issues et Projects GitHub pour trouver des sujets sur lesquels intervenir et montrer votre expertise. Ensemble, faisons grandir TEN !

[!TIP]

Toutes les contributions comptent 🙏

Aidez-nous à améliorer TEN. Du code à la doc, chaque partage est précieux. Publiez vos projets TEN Agent sur les réseaux pour inspirer la communauté.

Contactez un mainteneur, @elliotchen200 sur 𝕏 ou @cyfyifanchen sur GitHub, pour suivre les actualités, échanger et collaborer.

Contributrices et contributeurs Copy Section

Guide de contribution Copy Section

Les contributions sont les bienvenues ! Lisez d’abord le guide de contribution.

Licence Copy Section

1. L’ensemble de TEN Framework (hors dossiers listés ci-dessous) est publié sous licence Apache 2.0 avec restrictions additionnelles. Voir le fichier LICENSE à la racine.
2. Les composants du dossier packages sont publiés sous Apache 2.0. Référez-vous au fichier LICENSE propre à chaque package.
3. Les bibliothèques tierces utilisées par TEN Framework sont référencées dans le dossier third_party.

README IT (`docs/README-IT.md`) Copy Section

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 Copy Chapter

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 Copy Chapter

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 Copy Chapter

Ambiente locale Copy Section

Passaggio ⓵ - Prerequisiti

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 install prima del primo avvio e dopo aver modificato le dipendenze o il codice sorgente Go. Questo comando installa le dipendenze TEN, Python e frontend e compila il server API Go. Le modifiche al solo codice Python non richiedono una nuova installazione.

task install
task run

7. Accedi all’agente

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

• 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 Copy Section

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 Copy Chapter

Distribuire con Docker Copy Section

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 Copy Section

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 Copy Chapter

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

Ecosistema TEN Copy Chapter

Progetto	Anteprima
️TEN FrameworkFramework open source per agenti conversazionali.
TEN VADRilevatore di attività vocale in streaming, leggero e a bassa latenza.
️TEN Turn DetectionAbilita dialoghi full-duplex tramite rilevamento dei turni.
TEN Agent ExamplesCasi d'uso costruiti con TEN.
TEN PortalSito ufficiale con documentazione e blog.

Domande Copy Chapter

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 Copy Chapter

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!

[!TIP]

Ogni contributo è importante 🙏

Aiutaci a migliorare TEN: dal codice alla documentazione, tutto conta. Condividi i tuoi progetti TEN Agent sui social per ispirare altre persone.

Contatta un maintainer — @elliotchen200 su 𝕏 o @cyfyifanchen su GitHub — per aggiornamenti, discussioni e collaborazioni.

Contributor del codice Copy Section

Linee guida per contribuire Copy Section

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

Licenza Copy Section

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.

README JP (`docs/README-JP.md`) Copy Section

目次

• TEN へようこそ
• エージェント事例
• エージェント事例のクイックスタート
  • ローカル環境
  • Codespaces
• エージェント事例のセルフホスティング
  • Docker でデプロイ
  • その他のクラウドサービスへデプロイ
• 最新情報
• TEN エコシステム
• 質問
• コントリビュート
  • コードコントリビューター
  • 貢献ガイドライン
  • ライセンス

TEN へようこそ Copy Chapter

TEN は音声会話型 AI エージェント向けのオープンソースフレームワークです。

TEN エコシステム には TEN Framework、エージェント事例、VAD、Turn Detection、Portal が含まれます。

コミュニティ	目的
	X で TEN Framework をフォローして最新情報をチェック
	Discord コミュニティに参加し、開発者同士で交流
	LinkedIn で TEN Framework をフォローし、ニュースを受け取る
	Hugging Face コミュニティでスペースやモデルを探索
	中国語コミュニティ向けの WeChat グループに参加

エージェント事例 Copy Chapter

多目的ボイスアシスタント — 低レイテンシ・高品質のリアルタイムアシスタント。メモリ、VAD、ターン検出 などの拡張機能を追加できます。

詳細は サンプルコード を参照してください。

Doodler — 音声またはテキストのプロンプトを手描き風のシンプルなスケッチに変換するお絵かきボード。クレヨンのパレットとリアルタイム描画を備えています。

サンプルコード

リップシンク対応アバター — 複数のアバタープロバイダーに対応。デモでは Live2D のリップシンクを備えたアニメキャラクター Kei を紹介し、今後 Trulience、HeyGen、Tavus のリアルアバターにも対応予定です。

Live2D 用サンプルコード

話者分離（Diarization） — 話者をリアルタイムで検出・ラベル付けします。ゲーム「Who Likes What」でインタラクティブな活用例を紹介しています。

サンプルコード

SIP 通話 — TEN で電話を実現する SIP 拡張機能です。

サンプルコード

文字起こし — 音声をテキストへ変換するトランスクリプションツール。

サンプルコード

ESP32-S3 Korvo V3 — Espressif ESP32-S3 Korvo V3 開発ボード上で TEN Agent のサンプルを動作させ、LLM ベースのコミュニケーションをハードウェアに組み込みます。

統合ガイド を参照してください。

エージェント事例のクイックスタート Copy Chapter

ローカル環境 Copy Section

ステップ ⓵ - 事前準備

ステップ ⓶ - VM 内でサンプルをビルド

1. リポジトリをクローンし、`ai_agents` に移動して `.env.example` から `.env` を作成

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

2. `.env` に Agora App ID と App Certificate を設定

AGORA_APP_ID=
AGORA_APP_CERTIFICATE=

# デフォルトのボイスアシスタント例を実行
# Deepgram（音声認識に必須）
DEEPGRAM_API_KEY=your_deepgram_api_key_here

# OpenAI（言語モデルに必須）
OPENAI_API_KEY=your_openai_api_key_here
OPENAI_MODEL=gpt-4o

# ElevenLabs（音声合成に必須）
ELEVENLABS_TTS_KEY=your_elevenlabs_api_key_here

3. 開発用コンテナを起動

docker compose up -d

4. コンテナに入る

docker exec -it ten_agent_dev bash

5. デフォルトサンプルでエージェントをビルド（約 5〜8 分）

agents/examples ディレクトリには他のサンプルもあります。
以下のいずれかで開始できます：

# チェーン型ボイスアシスタント
cd agents/examples/voice-assistant

# リアルタイムの音声対音声アシスタント
cd agents/examples/voice-assistant-realtime

6. Web サーバーを起動

初回起動前、および依存関係や Go のソースコードを変更した後は task install を実行してください。このコマンドは TEN、Python、フロントエンドの依存関係をインストールし、Go API サーバーをビルドします。Python のソースコードのみを変更した場合、再インストールは不要です。

task install
task run

7. エージェントにアクセス

サンプルが起動すると次の UI を利用できます。

• TMAN Designer: http://localhost:49483
• エージェント事例 UI: http://localhost:3000

ステップ ⓷ - サンプルをカスタマイズ

1. localhost:49483 を開く。
2. STT・LLM・TTS 拡張を右クリック。
3. プロパティで対応する API キーを入力。
4. 変更を保存すると localhost:3000 で更新内容を確認できます。

Docker なしで TEN Manager からトランスクリプションアプリを実行 (Beta)

TEN には、Docker を使わずに TEN Manager から実行できるトランスクリプションアプリも用意されています。

詳しくはクイックスタートガイドをご覧ください。

Codespaces Copy Section

GitHub はリポジトリごとに無料の Codespaces を提供しています。Docker を使わずにエージェント事例を実行でき、通常ローカル環境よりも起動が速くなります。

詳細はこちらのガイドをご覧ください。

エージェント事例のセルフホスティング Copy Chapter

Docker でデプロイ Copy Section

TMAN Designer でカスタマイズするか property.json を編集したら、本番用の Docker イメージを作成してサービスをデプロイしましょう。

Docker イメージとして公開

注意: 以下のコマンドは Docker コンテナの外で実行してください。

イメージをビルド

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

実行

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

その他のクラウドサービスへデプロイ Copy Section

TEN を Vercel や Netlify などでホストする場合、バックエンドとフロントエンドを分けて配置できます。

1. Docker 対応の任意のプラットフォーム（Docker が動く VM、Fly.io、Render、ECS、Cloud Run など）で TEN バックエンドを実行。用意されたサンプルイメージをそのまま使い、ポート 8080 を公開します。
2. フロントエンドのみ Vercel / Netlify にデプロイします。プロジェクトルートを ai_agents/agents/examples/<example>/frontend に設定し、pnpm install（または bun install）→ pnpm build（または bun run build）を実行し、デフォルトの .next 出力を保持します。
3. ホスティング側の環境変数で AGENT_SERVER_URL をバックエンド URL に設定し、必要な NEXT_PUBLIC_* キー（ブラウザで使う Agora 資格情報など）を追加します。
4. CORS を開放する、または内蔵のプロキシミドルウェアを使うなどして、フロントエンドのオリジンからバックエンドへのリクエストを許可します。

この構成では、バックエンドがワーカー処理を担い、ホストしたフロントエンドは API リクエストを転送するだけで済みます。

最新情報 Copy Chapter

新しいリリースやアップデートを即座に受け取れます。あなたのサポートが TEN を成長させます！

TEN エコシステム Copy Chapter

プロジェクト	プレビュー
️TEN Framework会話型 AI エージェント向けオープンソースフレームワーク。
TEN VAD低遅延・軽量・高性能なストリーミング音声活動検出。
️TEN Turn Detection全二重会話を可能にするターン検出。
TEN Agent ExamplesTEN を使ったユースケース集。
TEN Portal公式サイト。ドキュメントとブログを掲載。

質問 Copy Chapter

TEN Framework は AI 駆動の Q&A プラットフォームにも掲載されています。マルチリンガルでの検索が可能で、初期設定から高度な実装までサポートします。

サービス	リンク
DeepWiki
ReadmeX

コントリビュート Copy Chapter

バグ修正、機能追加、ドキュメント改善、アイデア共有など、あらゆる OSS での協力を歓迎します。GitHub の Issues や Projects をチェックして活躍の場を見つけ、スキルを発揮してください。一緒に TEN をより良いものにしましょう！

[!TIP]

すべてのコントリビューションに感謝します 🙏

コードでもドキュメントでも、どんな貢献も力になります。TEN Agent プロジェクトを SNS で紹介し、コミュニティを盛り上げましょう。

メンテナー @elliotchen200（𝕏）や @cyfyifanchen（GitHub）に連絡すると、最新情報や議論、コラボの機会を得られます。

コードコントリビューター Copy Section

貢献ガイドライン Copy Section

いつでも歓迎です！まずは貢献ガイドラインをご確認ください。

ライセンス Copy Section

1. 下記のディレクトリを除き、TEN Framework 全体は追加条件付きの Apache License 2.0 で配布されています。プロジェクトルートの LICENSE を参照してください。
2. packages 配下のコンポーネントも Apache License 2.0 で提供されます。各パッケージの LICENSE ファイルをご確認ください。
3. TEN Framework が利用するサードパーティライブラリは third_party ディレクトリで一覧化されています。

README KR (`docs/README-KR.md`) Copy Section

목차

• TEN 소개
• 에이전트 예시
• 에이전트 예시 빠른 시작
  • 로컬 환경
  • Codespaces
• 에이전트 예시 셀프 호스팅
  • Docker 배포
  • 기타 클라우드 제공업체 배포
• 소식 받기
• TEN 에코시스템
• 질문
• 기여하기
  • 코드 기여자
  • 기여 가이드
  • 라이선스

TEN 소개 Copy Chapter

TEN은 음성 대화형 AI 에이전트를 위한 오픈소스 프레임워크입니다.

TEN 에코시스템에는 TEN Framework, 에이전트 예시, VAD, Turn Detection, Portal 이 포함됩니다.

커뮤니티 채널	설명
	X에서 TEN Framework 소식을 받아보세요
	Discord 커뮤니티에 참여해 개발자들과 교류하세요
	LinkedIn에서 업데이트와 공지를 확인하세요
	Hugging Face 커뮤니티에서 스페이스와 모델을 살펴보세요
	중국 커뮤니티와 대화할 수 있는 WeChat 그룹

에이전트 예시 Copy Chapter

멀티 퍼포즈 보이스 어시스턴트 — 저지연·고품질 실시간 어시스턴트로, 메모리, VAD, 턴 감지 등으로 확장할 수 있습니다.

자세한 내용은 예시 코드를 확인하세요.

Doodler — 음성 또는 텍스트 프롬프트를 손그림 스케치로 바꾸는 낙서 보드로, 크레용 팔레트와 실시간 드로잉을 제공합니다.

예시 코드

립싱크 아바타 — 다양한 아바타 공급업체를 지원합니다. 데모에서는 Live2D 립싱크를 갖춘 애니메이션 캐릭터 Kei를 소개하며, 곧 Trulience, HeyGen, Tavus의 실사 아바타도 지원할 예정입니다.

Live2D 예시 코드

음성 화자 분리 — 실시간으로 화자를 감지하고 라벨링합니다. "Who Likes What" 게임에서 인터랙티브한 사용 사례를 확인할 수 있습니다.

예시 코드

SIP 통화 — TEN 기반 전화 통화를 가능하게 하는 SIP 확장입니다.

예시 코드

전사(Transcription) — 오디오를 텍스트로 변환하는 전사 도구입니다.

예시 코드

ESP32-S3 Korvo V3 — Espressif ESP32-S3 Korvo V3 개발 보드에서 TEN Agent 예시를 실행해 LLM 기반 커뮤니케이션을 하드웨어와 통합합니다.

통합 가이드를 참고하세요.

에이전트 예시 빠른 시작 Copy Chapter

로컬 환경 Copy Section

단계 ⓵ - 준비 사항

단계 ⓶ - VM 안에서 예시 빌드

1. 저장소를 클론하고 `ai_agents`로 이동한 뒤 `.env.example`로부터 `.env` 생성

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

2. `.env`에 Agora App ID / App Certificate 설정

AGORA_APP_ID=
AGORA_APP_CERTIFICATE=

# 기본 보이스 어시스턴트 예시 실행
# Deepgram (STT 필수)
DEEPGRAM_API_KEY=your_deepgram_api_key_here

# OpenAI (LLM 필수)
OPENAI_API_KEY=your_openai_api_key_here
OPENAI_MODEL=gpt-4o

# ElevenLabs (TTS 필수)
ELEVENLABS_TTS_KEY=your_elevenlabs_api_key_here

3. 개발용 컨테이너 시작

docker compose up -d

4. 컨테이너 접속

docker exec -it ten_agent_dev bash

5. 기본 예시로 에이전트 빌드 (약 5~8분)

agents/examples 폴더에서 다른 샘플도 확인할 수 있습니다.
다음 중 하나부터 시작하세요:

# 체이닝형 보이스 어시스턴트
cd agents/examples/voice-assistant

# 실시간 음성-음성 어시스턴트
cd agents/examples/voice-assistant-realtime

6. 웹 서버 시작

처음 실행하기 전과 종속성 또는 Go 소스 코드를 변경한 후에는 task install을 실행하세요. 이 명령은 TEN, Python, 프런트엔드 종속성을 설치하고 Go API 서버를 빌드합니다. Python 소스 코드만 변경한 경우에는 다시 설치할 필요가 없습니다.

task install
task run

7. 에이전트 접속

예시가 실행되면 아래 인터페이스를 이용할 수 있습니다.

• TMAN Designer: http://localhost:49483
• 에이전트 예시 UI: http://localhost:3000

단계 ⓷ - 예시 커스터마이징

1. localhost:49483에 접속합니다.
2. STT, LLM, TTS 확장을 우클릭합니다.
3. 속성 창에서 해당 API 키를 입력합니다.
4. 저장 후 localhost:3000에서 변경된 결과를 확인합니다.

Docker 없이 TEN Manager에서 전사 앱 실행 (Beta)

TEN은 Docker 없이 TEN Manager에서 바로 실행할 수 있는 전사 앱도 제공합니다.

자세한 내용은 빠른 시작 가이드를 확인하세요.

Codespaces Copy Section

GitHub는 저장소마다 무료 Codespaces를 제공합니다. Docker 없이도 에이전트 예시를 실행할 수 있으며, 일반적으로 로컬 Docker 환경보다 빠르게 시작됩니다.

자세한 내용은 이 가이드를 참고하세요.

에이전트 예시 셀프 호스팅 Copy Chapter

Docker 배포 Copy Section

TMAN Designer 또는 property.json 수정으로 에이전트를 커스터마이징했다면, 서비스용 Docker 릴리스 이미지를 만들어 배포할 수 있습니다.

Docker 이미지로 배포

주의: 아래 명령은 Docker 컨테이너 밖에서 실행하세요.

이미지 빌드

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

실행

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

기타 클라우드 제공업체 배포 Copy Section

TEN을 Vercel이나 Netlify 같은 플랫폼에 호스팅할 때는 백엔드와 프런트엔드를 분리할 수 있습니다.

1. Docker를 지원하는 플랫폼(도커 가능한 VM, Fly.io, Render, ECS, Cloud Run 등)에서 TEN 백엔드를 실행합니다. 예시 이미지를 그대로 사용하고 포트 8080을 개방하세요.
2. 프런트엔드는 Vercel 또는 Netlify에만 배포합니다. 프로젝트 루트를 ai_agents/agents/examples/<example>/frontend로 지정하고 pnpm install(또는 bun install) 후 pnpm build(또는 bun run build)를 실행하며 기본 .next 출력 디렉터리를 유지합니다.
3. 호스팅 대시보드에서 AGENT_SERVER_URL을 백엔드 주소로 설정하고, 브라우저에서 필요한 NEXT_PUBLIC_* 환경 변수를 추가합니다(예: Agora 자격 증명).
4. 백엔드가 프런트엔드 오리진을 허용하도록 CORS를 열거나 기본 제공 프록시 미들웨어를 사용하세요.

이 구조에서는 백엔드가 장기 실행 작업을 처리하고, 호스팅된 프런트엔드는 API 요청을 전달하기만 하면 됩니다.

소식 받기 Copy Chapter

새 릴리스와 업데이트를 즉시 받아보세요. 여러분의 응원이 TEN을 성장시킵니다!

TEN 에코시스템 Copy Chapter

프로젝트	미리보기
️TEN Framework대화형 AI 에이전트를 위한 오픈소스 프레임워크.
TEN VAD저지연·경량·고성능 스트리밍 음성 활동 감지.
️TEN Turn Detection풀 듀플렉스 대화를 지원하는 턴 감지.
TEN Agent ExamplesTEN 기반 활용 사례 모음.
TEN Portal문서와 블로그를 제공하는 공식 사이트.

질문 Copy Chapter

TEN Framework는 AI 기반 Q&A 플랫폼에서도 만나볼 수 있습니다. 멀티랭귀지를 지원하며 기본 설정부터 고급 구현까지 빠르게 답을 찾을 수 있습니다.

서비스	링크
DeepWiki
ReadmeX

기여하기 Copy Chapter

버그 수정, 기능 추가, 문서 개선, 아이디어 공유 등 모든 형태의 오픈소스 협업을 환영합니다. GitHub Issues와 Projects에서 참여할 작업을 찾아 능력을 보여주세요. 함께 멋진 TEN을 만들어봅시다!

[!TIP]

어떤 형태의 기여든 환영합니다 🙏

코드부터 문서까지, 모든 기여가 TEN을 더 좋게 만듭니다. TEN Agent 프로젝트를 SNS에 공유해 다른 제작자에게 영감을 주세요.

𝕏의 @elliotchen200 또는 GitHub의 @cyfyifanchen에게 연락하면 업데이트, 토론, 협업 기회를 얻을 수 있습니다.

코드 기여자 Copy Section

기여 가이드 Copy Section

기여를 환영합니다! 먼저 기여 가이드를 읽어 주세요.

라이선스 Copy Section

1. 아래에 명시된 디렉터리를 제외한 TEN Framework 전체는 추가 제한이 포함된 Apache License 2.0으로 배포됩니다. 루트 디렉터리의 LICENSE를 참고하세요.
2. packages 디렉터리의 구성요소 역시 Apache License 2.0으로 배포되며, 각 패키지 루트의 LICENSE 파일에서 세부 내용을 확인할 수 있습니다.
3. TEN Framework에서 사용하는 서드파티 라이브러리는 third_party 폴더에 정리되어 있습니다.

Ai L0 Repo Card (`docs/ai/L0_repo_card.md`) Copy Section

TEN Framework — Repo Card

Open-source platform for building real-time multimodal AI agents

Identity Copy Chapter

L1 Index Copy Chapter

Api Log.Cn (`docs/api/log.cn.md`) Copy Section

title: 日志 _portal_target: api/log.cn.md Copy Chapter

TEN framework 允许使用不同语言开发的 extension 在同一进程中运行。这使得需要以统一的日志格式和信息在统一的日志中查看所有这些 extension 的日志，从而简化调试。

为了解决这个问题，ten_env 提供了一个日志 API。在 extension 的每个回调中，都可以访问 ten_env 的实例。使用此实例，您可以调用日志 API，将使用各种语言开发的 extension 的日志输出到统一的日志输出中。

日志级别 Copy Chapter

TEN framework 支持以下日志级别，按严重程度递增：

• DEBUG (1): 调试信息
• INFO (2): 一般信息
• WARN (3): 警告信息
• ERROR (4): 错误信息

API 接口 Copy Chapter

C++ 语言 Copy Section

#include "ten_runtime/binding/cpp/ten.h"

class Extension {
public:
    void on_cmd(ten::ten_env_t& ten_env, std::unique_ptr<ten::cmd_t> cmd) {
        // 使用便捷宏
        TEN_ENV_LOG_DEBUG(ten_env, "Processing command");
        TEN_ENV_LOG_INFO(ten_env, "Command name: " + cmd->get_name());
        TEN_ENV_LOG_WARN(ten_env, "Warning message");
        TEN_ENV_LOG_ERROR(ten_env, "Error occurred");

        // 直接调用方法，支持 category 和 fields 参数
        ten_env.log(TEN_LOG_LEVEL_INFO, __func__, __FILE__, __LINE__,
                   "Direct log call", nullptr, nullptr);
    }
};

C++ 提供了以下便捷宏：

• TEN_ENV_LOG_DEBUG(ten_env, msg)
• TEN_ENV_LOG_INFO(ten_env, msg)
• TEN_ENV_LOG_WARN(ten_env, msg)
• TEN_ENV_LOG_ERROR(ten_env, msg)

Python 语言 Copy Section

from ten_runtime import Extension, TenEnv

class MyExtension(Extension):
    def on_cmd(self, ten_env: TenEnv, cmd):
        # 使用不同级别的日志方法
        ten_env.log_debug("调试信息")
        ten_env.log_info("一般信息")
        ten_env.log_warn("警告信息")
        ten_env.log_error("错误信息")

        # 支持格式化字符串和额外参数
        test_value = "example"
        ten_env.log_info(f"处理命令，测试值: {test_value}")

        # 支持 category 和 fields 参数
        ten_env.log_info("带分类的日志", category="my_extension")

Python 提供了以下方法：

• log_debug(msg: str, category: str = None, fields: Value = None) -> Optional[TenError]
• log_info(msg: str, category: str = None, fields: Value = None) -> Optional[TenError]
• log_warn(msg: str, category: str = None, fields: Value = None) -> Optional[TenError]
• log_error(msg: str, category: str = None, fields: Value = None) -> Optional[TenError]

Go 语言 Copy Section

package main

import "ten_runtime/ten"

type MyExtension struct {
    ten.DefaultExtension
}

func (ext *MyExtension) OnCmd(tenEnv ten.TenEnv, cmd ten.Cmd) {
    // 使用不同级别的日志方法
    tenEnv.LogDebug("调试信息")
    tenEnv.LogInfo("一般信息")
    tenEnv.LogWarn("警告信息")
    tenEnv.LogError("错误信息")

    // 支持格式化
    cmdName := cmd.GetName()
    tenEnv.LogInfo("处理命令: " + cmdName)

    // 使用完整的 Log 方法支持更多参数
    category := "my_extension"
    tenEnv.Log(ten.LogLevelInfo, "带分类的日志", &category, nil, nil)
}

Go 提供了以下方法：

• LogDebug(msg string) error
• LogInfo(msg string) error
• LogWarn(msg string) error
• LogError(msg string) error
• Log(level LogLevel, msg string, category *string, fields *Value, option *TenLogOption) error

Node.js/TypeScript 语言 Copy Section

import { Extension, TenEnv, Cmd } from "ten-runtime-nodejs";

class MyExtension extends Extension {
    async onCmd(tenEnv: TenEnv, cmd: Cmd): Promise<void> {
        // 使用不同级别的日志方法
        tenEnv.logDebug("调试信息");
        tenEnv.logInfo("一般信息");
        tenEnv.logWarn("警告信息");
        tenEnv.logError("错误信息");

        // 支持字符串拼接
        const cmdName = cmd.getName();
        tenEnv.logInfo("处理命令: " + cmdName);

        // 支持 category 和 fields 参数
        tenEnv.logInfo("带分类的日志", "my_extension");
    }
}

Node.js 提供了以下方法：

• logDebug(message: string, category?: string, fields?: Value): TenError | undefined
• logInfo(message: string, category?: string, fields?: Value): TenError | undefined
• logWarn(message: string, category?: string, fields?: Value): TenError | undefined
• logError(message: string, category?: string, fields?: Value): TenError | undefined

使用示例 Copy Chapter

基本使用 Copy Section

# Python 示例
def on_start(self, ten_env: TenEnv):
    ten_env.log_info("extension 启动")
    ten_env.on_start_done()

def on_cmd(self, ten_env: TenEnv, cmd):
    cmd_name = cmd.get_name()
    ten_env.log_debug(f"收到命令: {cmd_name}")

    # 处理命令逻辑
    if cmd_name == "hello":
        ten_env.log_info("处理 hello 命令", category="command_handler")
        # ... 处理逻辑
    else:
        ten_env.log_warn(f"未知命令: {cmd_name}")

在线程中使用 Copy Section

import threading
import time

def log_routine(self, ten_env: TenEnv):
    """在单独线程中记录日志"""
    while not self.stop_flag:
        self.log_count += 1
        ten_env.log_info(f"日志消息 {self.log_count}")
        time.sleep(0.05)

def on_start(self, ten_env: TenEnv):
    # 启动日志线程
    self.log_thread = threading.Thread(
        target=self.log_routine, args=(ten_env,)
    )
    self.log_thread.start()
    ten_env.on_start_done()

错误处理 Copy Section

def on_cmd(self, ten_env: TenEnv, cmd):
    try:
        # 业务逻辑
        result = self.process_command(cmd)
        ten_env.log_info("命令处理成功")
    except ValueError as e:
        ten_env.log_error(f"参数错误: {str(e)}", category="error_handling")
    except Exception as e:
        ten_env.log_error(f"严重错误: {str(e)}", category="error_handling")
        raise

日志格式和输出 Copy Chapter

TEN framework 的日志系统会自动包含以下信息：

• 时间戳: 日志记录的时间
• 日志级别: DEBUG、INFO、WARN、ERROR
• 函数名: 调用日志的函数名（如果可用）
• 文件名: 调用日志的源文件名（如果可用）
• 行号: 调用日志的代码行号（如果可用）
• 分类: 可选的日志分类信息
• 消息内容: 用户提供的日志消息

输出格式类似：

2025-01-01 12:00:00.123 [INFO] [[email protected]:123] [category] 用户日志消息

高级日志配置 Copy Chapter

TEN framework 支持通过 property.json 文件配置高级日志功能。这允许您自定义日志的输出格式、目标和过滤规则。

配置结构 Copy Section

在 property.json 文件中，您可以在 ten.log 部分定义高级日志配置：

{
  "ten": {
    "log": {
      "handlers": [
        {
          "matchers": [
            {
              "level": "debug",
              "category": "my_extension"
            }
          ],
          "formatter": {
            "type": "plain",
            "colored": true
          },
          "emitter": {
            "type": "console",
            "config": {
              "stream": "stdout"
            }
          }
        }
      ]
    }
  }
}

配置组件说明 Copy Section

1. 日志处理器 (Handlers)

每个处理器包含三个主要组件：

• matchers: 定义哪些日志消息会被此处理器处理
• formatter: 定义日志的输出格式
• emitter: 定义日志的输出目标

2. 匹配器 (Matchers)

匹配器用于过滤日志消息：

{
  "level": "info",      // 日志级别: "off", "debug", "info", "warn", "error"
  "category": "auth"    // 可选：日志分类（字符串）
}

支持的日志级别：

• "off": 关闭日志
• "debug": 调试级别
• "info": 信息级别
• "warn": 警告级别
• "error": 错误级别

3. 格式器 (Formatter)

控制日志的输出格式：

{
  "type": "plain",      // 格式类型: "plain" 或 "json"
  "colored": true       // 可选：是否启用颜色输出（仅对 plain 格式有效）
}

• plain: 人类可读的纯文本格式
• json: JSON 结构化格式，便于日志分析工具处理

4. 发射器 (Emitter)

定义日志的输出目标：

控制台输出

{
  "type": "console",
  "config": {
    "stream": "stdout",  // "stdout" 或 "stderr"
    "encryption": {      // 可选：加密配置
      "enabled": true,
      "algorithm": "AES-CTR",
      "params": {
        "key": "your-encryption-key",
        "nonce": "your-nonce"
      }
    }
  }
}

文件输出

{
  "type": "file",
  "config": {
    "path": "/path/to/logfile.log",  // 日志文件路径
    "encryption": {                  // 可选：加密配置
      "enabled": true,
      "algorithm": "AES-CTR",
      "params": {
        "key": "your-encryption-key",
        "nonce": "your-nonce"
      }
    }
  }
}

OTLP 输出

OTLP (OpenTelemetry Protocol) 输出允许您将日志发送到支持 OpenTelemetry 的后端系统，如 Jaeger、Prometheus、Grafana 等。

{
  "type": "otlp",
  "config": {
    "endpoint": "http://localhost:4317",  // OTLP 接收端点地址
    "protocol": "grpc",                   // 可选：传输协议，"grpc"（默认）或 "http"
    "headers": {                          // 可选：自定义 HTTP 头
      "Authorization": "Bearer token",
      "X-Custom-Header": "value"
    },
    "service_name": "my-service"          // 可选：服务名称，用于标识日志来源
  }
}

配置参数说明：

• endpoint: OTLP 接收端点的 URL（必需）
• protocol: 传输协议，支持 "grpc" 或 "http"，默认为 "grpc"
• headers: 自定义 HTTP 请求头，用于认证或其他元数据传递（可选）
• service_name: 服务名称，用于在日志聚合系统中标识不同的服务（可选）

配置示例 Copy Section

示例 1: 多级别日志分离

{
  "ten": {
    "log": {
      "handlers": [
        {
          "matchers": [
            {
              "level": "error"
            }
          ],
          "formatter": {
            "type": "json"
          },
          "emitter": {
            "type": "file",
            "config": {
              "path": "/var/log/app/errors.log"
            }
          }
        },
        {
          "matchers": [
            {
              "level": "info"
            }
          ],
          "formatter": {
            "type": "plain",
            "colored": true
          },
          "emitter": {
            "type": "console",
            "config": {
              "stream": "stdout"
            }
          }
        }
      ]
    }
  }
}

示例 2: 按分类分离日志

{
  "ten": {
    "log": {
      "handlers": [
        {
          "matchers": [
            {
              "level": "debug",
              "category": "database"
            }
          ],
          "formatter": {
            "type": "json"
          },
          "emitter": {
            "type": "file",
            "config": {
              "path": "/var/log/app/database.log"
            }
          }
        },
        {
          "matchers": [
            {
              "level": "info",
              "category": "api"
            }
          ],
          "formatter": {
            "type": "plain"
          },
          "emitter": {
            "type": "console",
            "config": {
              "stream": "stdout"
            }
          }
        }
      ]
    }
  }
}

示例 3: 加密日志输出

{
  "ten": {
    "log": {
      "handlers": [
        {
          "matchers": [
            {
              "level": "info"
            }
          ],
          "formatter": {
            "type": "json"
          },
          "emitter": {
            "type": "file",
            "config": {
              "path": "/secure/logs/app.log",
              "encryption": {
                "enabled": true,
                "algorithm": "AES-CTR",
                "params": {
                  "key": "your-32-character-encryption-key",
                  "nonce": "your-16-character-nonce"
                }
              }
            }
          }
        }
      ]
    }
  }
}

示例 4: OTLP 日志输出到 OpenTelemetry 收集器

{
  "ten": {
    "log": {
      "handlers": [
        {
          "matchers": [
            {
              "level": "info"
            }
          ],
          "formatter": {
            "type": "json"
          },
          "emitter": {
            "type": "otlp",
            "config": {
              "endpoint": "http://localhost:4317",
              "protocol": "grpc",
              "service_name": "ten-framework-app"
            }
          }
        },
        {
          "matchers": [
            {
              "level": "error"
            }
          ],
          "formatter": {
            "type": "json"
          },
          "emitter": {
            "type": "otlp",
            "config": {
              "endpoint": "https://api.monitoring.example.com/v1/logs",
              "protocol": "http",
              "headers": {
                "Authorization": "Bearer your-api-token",
                "X-Environment": "production"
              },
              "service_name": "ten-framework-app"
            }
          }
        }
      ]
    }
  }
}

配置注意事项 Copy Section

1. 多个处理器: 可以定义多个处理器来实现复杂的日志路由策略
2. 匹配优先级: 按照配置文件中的顺序匹配处理器
3. 加密安全: 加密密钥和 nonce 应该安全存储，不要硬编码在配置文件中
4. 文件权限: 确保日志文件路径具有适当的写入权限
5. 性能考虑: JSON 格式可能会比 plain 格式产生更大的日志文件
6. OTLP 端点:
   • 使用 gRPC 协议时，默认端口通常为 4317
   • 使用 HTTP 协议时，默认端口通常为 4318
   • 确保 OTLP 收集器端点可访问且配置正确
7. 认证: 使用 OTLP 时，如果后端需要认证，请在 headers 中添加相应的认证信息

最佳实践 Copy Chapter

1. 选择合适的日志级别：

   • 使用 DEBUG 记录详细的调试信息
   • 使用 INFO 记录正常的业务流程
   • 使用 WARN 记录潜在问题
   • 使用 ERROR 记录错误信息

2. 提供有意义的日志消息：

   • 包含上下文信息（如命令名称、参数值等）
   • 使用描述性的消息而不是简单的标识符
   • 合理使用 category 参数对日志进行分类

3. 避免过度日志记录：

   • 不要在高频循环中使用过多的日志
   • 在生产环境中适当调整日志级别
   • 使用高级日志配置的匹配器来过滤不必要的日志

4. 线程安全：

   • TEN framework 的日志 API 是线程安全的
   • 可以在任何线程中安全调用日志方法

5. 高级配置建议：

   • 为不同的模块使用不同的 category 便于日志分析
   • 在生产环境中考虑使用文件输出以便于日志持久化
   • 对敏感日志使用加密功能
   • 定期轮转日志文件以控制磁盘使用
   • 使用 JSON 格式便于与日志分析工具集成
   • 考虑使用 OTLP 输出将日志集成到现代可观测性平台（如 Grafana、Jaeger、Datadog 等）
   • OTLP 输出与 OpenTelemetry 生态系统无缝集成，便于实现分布式追踪和日志关联

整体效果如下图所示：

Api Log (`docs/api/log.md`) Copy Section

title: Log _portal_target: api/log.md Copy Chapter

The TEN framework allows extensions developed in different languages to run within the same process. This creates a need to view logs from all these extensions in a unified log with a consistent format and information, making debugging easier.

To address this, the ten_env provides a logging API. Within each callback of an extension, an instance of ten_env can be accessed. Using this instance, you can call the logging API to output logs from extensions developed in various languages to a unified log output.

Log Levels Copy Chapter

The TEN framework supports the following log levels in increasing order of severity:

• DEBUG (1): Debug information
• INFO (2): General information
• WARN (3): Warning information
• ERROR (4): Error information

API Interface Copy Chapter

C++ Language Copy Section

#include "ten_runtime/binding/cpp/ten.h"

class Extension {
public:
    void on_cmd(ten::ten_env_t& ten_env, std::unique_ptr<ten::cmd_t> cmd) {
        // Using convenience macros
        TEN_ENV_LOG_DEBUG(ten_env, "Processing command");
        TEN_ENV_LOG_INFO(ten_env, "Command name: " + cmd->get_name());
        TEN_ENV_LOG_WARN(ten_env, "Warning message");
        TEN_ENV_LOG_ERROR(ten_env, "Error occurred");

        // Direct method call with category and fields support
        ten_env.log(TEN_LOG_LEVEL_INFO, __func__, __FILE__, __LINE__,
                   "Direct log call", nullptr, nullptr);
    }
};

C++ provides the following convenience macros:

• TEN_ENV_LOG_DEBUG(ten_env, msg)
• TEN_ENV_LOG_INFO(ten_env, msg)
• TEN_ENV_LOG_WARN(ten_env, msg)
• TEN_ENV_LOG_ERROR(ten_env, msg)

Python Language Copy Section

from ten_runtime import Extension, TenEnv

class MyExtension(Extension):
    def on_cmd(self, ten_env: TenEnv, cmd):
        # Using different log level methods
        ten_env.log_debug("Debug information")
        ten_env.log_info("General information")
        ten_env.log_warn("Warning information")
        ten_env.log_error("Error information")

        # Supports formatted strings and additional parameters
        test_value = "example"
        ten_env.log_info(f"Processing command, test value: {test_value}")

        # Supports category and fields parameters
        ten_env.log_info("Log with category", category="my_extension")

Python provides the following methods:

• log_debug(msg: str, category: str = None, fields: Value = None) -> Optional[TenError]
• log_info(msg: str, category: str = None, fields: Value = None) -> Optional[TenError]
• log_warn(msg: str, category: str = None, fields: Value = None) -> Optional[TenError]
• log_error(msg: str, category: str = None, fields: Value = None) -> Optional[TenError]

Go Language Copy Section

package main

import "ten_runtime/ten"

type MyExtension struct {
    ten.DefaultExtension
}

func (ext *MyExtension) OnCmd(tenEnv ten.TenEnv, cmd ten.Cmd) {
    // Using different log level methods
    tenEnv.LogDebug("Debug information")
    tenEnv.LogInfo("General information")
    tenEnv.LogWarn("Warning information")
    tenEnv.LogError("Error information")

    // Supports formatting
    cmdName := cmd.GetName()
    tenEnv.LogInfo("Processing command: " + cmdName)

    // Using the full Log method for additional parameters
    category := "my_extension"
    tenEnv.Log(ten.LogLevelInfo, "Log with category", &category, nil, nil)
}

Go provides the following methods:

• LogDebug(msg string) error
• LogInfo(msg string) error
• LogWarn(msg string) error
• LogError(msg string) error
• Log(level LogLevel, msg string, category *string, fields *Value, option *TenLogOption) error

Node.js/TypeScript Language Copy Section

import { Extension, TenEnv, Cmd } from "ten-runtime-nodejs";

class MyExtension extends Extension {
    async onCmd(tenEnv: TenEnv, cmd: Cmd): Promise<void> {
        // Using different log level methods
        tenEnv.logDebug("Debug information");
        tenEnv.logInfo("General information");
        tenEnv.logWarn("Warning information");
        tenEnv.logError("Error information");

        // Supports string concatenation
        const cmdName = cmd.getName();
        tenEnv.logInfo("Processing command: " + cmdName);

        // Supports category and fields parameters
        tenEnv.logInfo("Log with category", "my_extension");
    }
}

Node.js provides the following methods:

• logDebug(message: string, category?: string, fields?: Value): TenError | undefined
• logInfo(message: string, category?: string, fields?: Value): TenError | undefined
• logWarn(message: string, category?: string, fields?: Value): TenError | undefined
• logError(message: string, category?: string, fields?: Value): TenError | undefined

Usage Examples Copy Chapter

Basic Usage Copy Section

# Python example
def on_start(self, ten_env: TenEnv):
    ten_env.log_info("Extension starting")
    ten_env.on_start_done()

def on_cmd(self, ten_env: TenEnv, cmd):
    cmd_name = cmd.get_name()
    ten_env.log_debug(f"Received command: {cmd_name}")

    # Command processing logic
    if cmd_name == "hello":
        ten_env.log_info("Processing hello command", category="command_handler")
        # ... processing logic
    else:
        ten_env.log_warn(f"Unknown command: {cmd_name}")

Using in Threads Copy Section

import threading
import time

def log_routine(self, ten_env: TenEnv):
    """Log messages in a separate thread"""
    while not self.stop_flag:
        self.log_count += 1
        ten_env.log_info(f"Log message {self.log_count}")
        time.sleep(0.05)

def on_start(self, ten_env: TenEnv):
    # Start logging thread
    self.log_thread = threading.Thread(
        target=self.log_routine, args=(ten_env,)
    )
    self.log_thread.start()
    ten_env.on_start_done()

Error Handling Copy Section

def on_cmd(self, ten_env: TenEnv, cmd):
    try:
        # Business logic
        result = self.process_command(cmd)
        ten_env.log_info("Command processed successfully")
    except ValueError as e:
        ten_env.log_error(f"Parameter error: {str(e)}", category="error_handling")
    except Exception as e:
        ten_env.log_error(f"Fatal error: {str(e)}", category="error_handling")
        raise

Log Format and Output Copy Chapter

The TEN framework's logging system automatically includes the following information:

• Timestamp: Time when the log was recorded
• Log Level: DEBUG, INFO, WARN, ERROR
• Function Name: Name of the function that called the log (if available)
• File Name: Source file name where the log was called (if available)
• Line Number: Code line number where the log was called (if available)
• Category: Optional log category information
• Message Content: User-provided log message

The output format is similar to:

2025-01-01 12:00:00.123 [INFO] [[email protected]:123] [category] User log message

Advanced Log Configuration Copy Chapter

The TEN framework supports advanced logging functionality through the property.json file configuration. This allows you to customize the log output format, destination, and filtering rules.

Configuration Structure Copy Section

In the property.json file, you can define advanced log configuration in the ten.log section:

{
  "ten": {
    "log": {
      "handlers": [
        {
          "matchers": [
            {
              "level": "debug",
              "category": "my_extension"
            }
          ],
          "formatter": {
            "type": "plain",
            "colored": true
          },
          "emitter": {
            "type": "console",
            "config": {
              "stream": "stdout"
            }
          }
        }
      ]
    }
  }
}

Configuration Components Copy Section

1. Log Handlers

Each handler contains three main components:

• matchers: Define which log messages will be processed by this handler
• formatter: Define the log output format
• emitter: Define the log output destination

2. Matchers

Matchers are used to filter log messages:

{
  "level": "info",      // Log level: "off", "debug", "info", "warn", "error"
  "category": "auth"    // Optional: log category (string)
}

Supported log levels:

• "off": Disable logging
• "debug": Debug level
• "info": Info level
• "warn": Warning level
• "error": Error level

3. Formatter

Controls the log output format:

{
  "type": "plain",      // Format type: "plain" or "json"
  "colored": true       // Optional: enable colored output (only for plain format)
}

• plain: Human-readable plain text format
• json: JSON structured format, convenient for log analysis tools

4. Emitter

Defines the log output destination:

Console Output

{
  "type": "console",
  "config": {
    "stream": "stdout",  // "stdout" or "stderr"
    "encryption": {      // Optional: encryption configuration
      "enabled": true,
      "algorithm": "AES-CTR",
      "params": {
        "key": "your-encryption-key",
        "nonce": "your-nonce"
      }
    }
  }
}

File Output

{
  "type": "file",
  "config": {
    "path": "/path/to/logfile.log",  // Log file path
    "encryption": {                  // Optional: encryption configuration
      "enabled": true,
      "algorithm": "AES-CTR",
      "params": {
        "key": "your-encryption-key",
        "nonce": "your-nonce"
      }
    }
  }
}

OTLP Output

OTLP (OpenTelemetry Protocol) output allows you to send logs to OpenTelemetry-compatible backend systems, such as Jaeger, Prometheus, Grafana, and more.

{
  "type": "otlp",
  "config": {
    "endpoint": "http://localhost:4317",  // OTLP receiver endpoint URL
    "protocol": "grpc",                   // Optional: transport protocol, "grpc" (default) or "http"
    "headers": {                          // Optional: custom HTTP headers
      "Authorization": "Bearer token",
      "X-Custom-Header": "value"
    },
    "service_name": "my-service"          // Optional: service name for identifying log source
  }
}

Configuration parameters:

• endpoint: OTLP receiver endpoint URL (required)
• protocol: Transport protocol, supports "grpc" or "http", defaults to "grpc"
• headers: Custom HTTP request headers for authentication or metadata (optional)
• service_name: Service name for identifying different services in log aggregation systems (optional)

Configuration Examples Copy Section

Example 1: Multi-level Log Separation

{
  "ten": {
    "log": {
      "handlers": [
        {
          "matchers": [
            {
              "level": "error"
            }
          ],
          "formatter": {
            "type": "json"
          },
          "emitter": {
            "type": "file",
            "config": {
              "path": "/var/log/app/errors.log"
            }
          }
        },
        {
          "matchers": [
            {
              "level": "info"
            }
          ],
          "formatter": {
            "type": "plain",
            "colored": true
          },
          "emitter": {
            "type": "console",
            "config": {
              "stream": "stdout"
            }
          }
        }
      ]
    }
  }
}

Example 2: Category-based Log Separation

{
  "ten": {
    "log": {
      "handlers": [
        {
          "matchers": [
            {
              "level": "debug",
              "category": "database"
            }
          ],
          "formatter": {
            "type": "json"
          },
          "emitter": {
            "type": "file",
            "config": {
              "path": "/var/log/app/database.log"
            }
          }
        },
        {
          "matchers": [
            {
              "level": "info",
              "category": "api"
            }
          ],
          "formatter": {
            "type": "plain"
          },
          "emitter": {
            "type": "console",
            "config": {
              "stream": "stdout"
            }
          }
        }
      ]
    }
  }
}

Example 3: Encrypted Log Output

{
  "ten": {
    "log": {
      "handlers": [
        {
          "matchers": [
            {
              "level": "info"
            }
          ],
          "formatter": {
            "type": "json"
          },
          "emitter": {
            "type": "file",
            "config": {
              "path": "/secure/logs/app.log",
              "encryption": {
                "enabled": true,
                "algorithm": "AES-CTR",
                "params": {
                  "key": "your-32-character-encryption-key",
                  "nonce": "your-16-character-nonce"
                }
              }
            }
          }
        }
      ]
    }
  }
}

Example 4: OTLP Log Output to OpenTelemetry Collector

{
  "ten": {
    "log": {
      "handlers": [
        {
          "matchers": [
            {
              "level": "info"
            }
          ],
          "formatter": {
            "type": "json"
          },
          "emitter": {
            "type": "otlp",
            "config": {
              "endpoint": "http://localhost:4317",
              "protocol": "grpc",
              "service_name": "ten-framework-app"
            }
          }
        },
        {
          "matchers": [
            {
              "level": "error"
            }
          ],
          "formatter": {
            "type": "json"
          },
          "emitter": {
            "type": "otlp",
            "config": {
              "endpoint": "https://api.monitoring.example.com/v1/logs",
              "protocol": "http",
              "headers": {
                "Authorization": "Bearer your-api-token",
                "X-Environment": "production"
              },
              "service_name": "ten-framework-app"
            }
          }
        }
      ]
    }
  }
}

Configuration Notes Copy Section

1. Multiple Handlers: You can define multiple handlers to implement complex log routing strategies
2. Matching Priority: Handlers are matched in the order they appear in the configuration file
3. Encryption Security: Encryption keys and nonces should be stored securely, not hardcoded in configuration files
4. File Permissions: Ensure log file paths have appropriate write permissions
5. Performance Considerations: JSON format may produce larger log files than plain format
6. OTLP Endpoints:
   • When using gRPC protocol, the default port is typically 4317
   • When using HTTP protocol, the default port is typically 4318
   • Ensure the OTLP collector endpoint is accessible and properly configured
7. Authentication: When using OTLP, if the backend requires authentication, add appropriate credentials in the headers

Best Practices Copy Chapter

1. Choose appropriate log levels:

   • Use DEBUG for detailed debugging information
   • Use INFO for normal business processes
   • Use WARN for potential issues
   • Use ERROR for error information

2. Provide meaningful log messages:

   • Include contextual information (such as command names, parameter values, etc.)
   • Use descriptive messages rather than simple identifiers
   • Use the category parameter appropriately to classify logs

3. Avoid excessive logging:

   • Don't use too many logs in high-frequency loops
   • Appropriately adjust log levels in production environments
   • Use advanced log configuration matchers to filter unnecessary logs

4. Thread safety:

   • The TEN framework's logging API is thread-safe
   • Log methods can be safely called from any thread

5. Advanced configuration recommendations:

   • Use different categories for different modules to facilitate log analysis
   • Consider using file output in production environments for log persistence
   • Use encryption functionality for sensitive logs
   • Regularly rotate log files to control disk usage
   • Use JSON format for easier integration with log analysis tools
   • Consider using OTLP output to integrate logs into modern observability platforms (e.g., Grafana, Jaeger, Datadog)
   • OTLP output seamlessly integrates with the OpenTelemetry ecosystem, enabling distributed tracing and log correlation

The overall effect is shown in the image below:

Code Of Conduct Contributing (`docs/code-of-conduct/contributing.md`) Copy Section

Contributing to TEN Framework

Welcome to the TEN Framework community! We're excited to have you contribute to building the future of real-time conversational AI agents. This guide will help you get started with contributing to the project.

🌟 Ways to Contribute Copy Chapter

We welcome all forms of contributions:

• Code contributions: Bug fixes, new features, performance improvements
• Documentation: Improving docs, tutorials, examples
• Bug reports: Identifying and reporting issues
• Feature requests: Suggesting new functionality
• Community support: Helping others in discussions and issues
• Extensions: Creating new extensions for the ecosystem

📋 Before You Start Copy Chapter

Required Reading Copy Section

1. Read our Code of Conduct - all contributors must follow our community guidelines
2. Sign the Contributor License Agreement (CLA) - required for all contributions
3. Review the project README to understand the architecture

Prerequisites Copy Section

Make sure you have the required tools installed:

• Docker / Docker Compose (for development environment)
• Node.js v20+ (for frontend development)
• Python 3.8+ (for AI agent development)
• Go (for backend server development)
• Task (task runner - install via npm install @go-task/cli)

🚀 Getting Started Copy Chapter

1. Fork and Clone Copy Section

# Fork the repository on GitHub first, then:
git clone https://github.com/YOUR_USERNAME/ten-framework.git
cd ten-framework

2. Set Up Development Environment Copy Section

# Navigate to AI agents directory
cd ai_agents

# Copy environment template
cp .env.example .env

# Edit .env file with your API keys:
# - AGORA_APP_ID and AGORA_APP_CERTIFICATE
# - OpenAI, Deepgram, ElevenLabs API keys as needed

# Start development containers
docker compose up -d

# Enter the container
docker exec -it ten_agent_dev bash

# Build the agent (takes 5-8 minutes)
task use

# Build and run
task build
task run

3. Development Workflow Copy Section

The project uses Task as the build system. Key commands:

# Core development commands
task build          # Build the project
task test           # Run all tests
task lint           # Run linting
task format         # Format code
task clean          # Clean build artifacts

# AI Agents specific
task use AGENT=agents/examples/demo    # Switch to different agent
task run-server     # Run backend server
task run-gd-server  # Run graph designer

🏗️ Project Structure Copy Chapter

ten-framework/
├── ai_agents/              # AI Agent implementations
│   ├── agents/             # Agent examples and configurations
│   ├── playground/         # Frontend playground (Next.js)
│   ├── server/             # Backend server (Go)
│   └── Taskfile.yml        # Build configuration
├── core/                   # TEN Framework core
├── packages/               # Framework packages
├── docs/                   # Documentation
├── tests/                  # Test suites
└── third_party/            # Third-party dependencies

🔧 Making Changes Copy Chapter

Code Guidelines Copy Section

1. Follow existing patterns: Review similar code before implementing
2. Use existing libraries: Check if the codebase already uses needed dependencies
3. Security first: Never expose secrets or credentials
4. No hardcoded comments: Don't add unnecessary code comments unless requested

Language-Specific Guidelines Copy Section

Python (AI Agents)

• Follow PEP 8 style guide
• Use Black formatter: task format
• Run pylint: task lint
• Add type hints where appropriate

TypeScript/JavaScript (Playground)

• Use existing ESLint configuration
• Follow React best practices
• Use TypeScript for new code

Go (Server)

• Follow Go conventions
• Use gofmt for formatting
• Add proper error handling

Commit Guidelines Copy Section

We use conventional commits:

feat: add new ASR integration
fix: resolve memory leak in audio processing  
docs: update installation instructions
test: add integration tests for TTS module
refactor: improve error handling in server

🧪 Testing Copy Chapter

Running Tests Copy Section

# Run all tests
task test

# Test specific extension
task test-extension EXTENSION=agents/ten_packages/extension/elevenlabs_tts_python

# Test server only
task test-server

# Test agent extensions
task test-agent-extensions

Writing Tests Copy Section

• Add unit tests for new functionality
• Include integration tests for complex features
• Ensure tests pass before submitting PRs
• Test configurations are in tests/configs/ directories

📝 Documentation Copy Chapter

• Update documentation for new features
• Include code examples where helpful
• Update README if adding new dependencies
• Document breaking changes clearly

🔄 Pull Request Process Copy Chapter

Before Submitting Copy Section

1. Test your changes: Ensure all tests pass
2. Format code: Run task format
3. Lint code: Run task lint
4. Update docs: Include any necessary documentation updates
5. Rebase on main: Ensure your branch is up to date

PR Guidelines Copy Section

1. Clear title: Use descriptive, conventional commit style
2. Detailed description: Explain what, why, and how
3. Link issues: Reference related issues with "Fixes #123"
4. Screenshots: Include for UI changes
5. Breaking changes: Clearly document any breaking changes

PR Template Copy Section

## Summary
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature  
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring

## Testing
- [ ] Tests added/updated
- [ ] All tests pass
- [ ] Manual testing completed

## Documentation
- [ ] Documentation updated
- [ ] Examples provided if needed

## Breaking Changes
List any breaking changes and migration steps

🐛 Reporting Issues Copy Chapter

Bug Reports Copy Section

Use the issue template and include:

• Environment: OS, versions, Docker info
• Steps to reproduce: Clear, minimal reproduction steps
• Expected vs actual: What should happen vs what happens
• Logs: Include relevant error messages
• Screenshots: For UI issues

Feature Requests Copy Section

• Use case: Explain the problem you're solving
• Proposed solution: Describe your ideal solution
• Alternatives: Consider other approaches
• Examples: Reference similar implementations if possible

🏆 Recognition Copy Chapter

Contributors are recognized in multiple ways:

• Contributors graph: Automatic GitHub recognition
• Release notes: Significant contributions mentioned
• Social media: Major features highlighted on @TenFramework
• Community showcase: Featured implementations

📞 Getting Help Copy Chapter

Community Channels Copy Section

• Discord: Join TEN Community
• GitHub Discussions: For questions and ideas
• GitHub Issues: For bugs and feature requests
• WeChat: Chinese community group

Maintainer Contact Copy Section

• Twitter: @elliotchen100
• GitHub: @cyfyifanchen

📜 License Copy Chapter

By contributing to TEN Framework, you agree that your contributions will be licensed under the Apache License v2.0 with additional conditions.

Your contributions must:

• Be your original work or properly attributed
• Not include any proprietary or confidential information
• Comply with the project's licensing terms

❤️ Thank You Copy Chapter

Every contribution, no matter how small, helps make TEN Framework better for everyone. We appreciate your time and effort in making this project successful!

Happy Contributing! 🚀

Development How To Develop With Ext.Cn (`docs/development/how_to_develop_with_ext.cn.md`) Copy Section

title: TEN 扩展开发完整指南 _portal_target: development/how_to_develop_with_ext.cn.md Copy Chapter

TEN Framework 提供了丰富的扩展模板，帮助开发者快速创建扩展并完成从开发到测试的完整流程。本指南将通过实际操作演示，详细介绍如何使用 C++，Go，Python，Node.js 四种语言进行扩展开发的全流程。

开发前准备 Copy Chapter

环境要求 Copy Section

在开始扩展开发之前，请确保您的开发环境已正确配置。通过以下命令验证安装：

tman --version

正常情况下，您应该看到类似以下的版本信息输出：

TEN Framework version: <version>

重要提示：请确保您使用的 tman 版本 >= 0.10.12，如果版本过低，请参考 快速入门指南 安装最新版本。

开发流程概览 Copy Section

无论使用哪种编程语言，TEN 扩展开发都遵循以下标准化流程：

1. 项目创建 - 使用官方模板生成扩展项目骨架
2. 依赖安装 - 配置运行环境并安装必要的依赖包
3. 核心开发 - 实现扩展的业务逻辑和功能代码
4. 构建测试 - 编译项目（如需要）并执行单元测试
5. 调试优化 - 使用专业调试工具定位并解决问题

C++ 扩展开发 Copy Chapter

C++ 扩展适用于对性能要求极高的应用场景，如实时音视频处理、高频数据计算、底层系统操作等。

创建项目 Copy Section

使用 TEN 官方提供的 C++ 扩展模板快速创建新项目：

tman create extension my_example_ext_cpp --template default_extension_cpp

项目创建成功后，您会得到以下完整的项目结构：

my_example_ext_cpp/
├── BUILD.gn              # GN 构建系统配置文件
├── manifest.json         # 扩展元数据和配置信息
├── property.json         # 扩展属性和参数配置
├── src/
│   └── main.cc           # 扩展核心实现代码
├── tests/
│   ├── basic.cc          # 基础功能测试用例
│   └── gtest_main.cc     # 测试框架程序入口
├── include/              # 头文件存放目录
├── tools/                # 辅助工具和脚本
└── .vscode/
    └── launch.json       # VSCode 调试配置文件

环境配置验证 Copy Section

进入项目目录并验证构建工具是否正常工作：

cd my_example_ext_cpp
tgn --version

期望输出：

0.1.0

如果命令无法执行，请参考 快速入门指南 检查 TEN Framework 开发环境是否正确安装。

依赖包安装 Copy Section

安装扩展运行时所需的全部依赖包：

tman install --standalone

安装成功后，您将看到类似以下的详细安装日志：

📦  Get all installed packages...
🔍  Filter compatible packages...
🔒  Creating manifest-lock.json...
📥  Installing packages...
  [00:00:00] [########################################]       3/3       Done

🏆  Install successfully in 1 second

项目构建 Copy Section

TEN framework 提供了两种便捷的构建方式供您选择：

方式一：手动分步构建

# 第一步：生成构建配置文件（启用独立测试模式）
tgn gen linux x64 debug -- ten_enable_standalone_test=true

# 第二步：执行项目构建
tgn build linux x64 debug

方式二：使用 tman 快捷命令

tman run build

构建完成后，检查生成的可执行测试文件：

ls -la bin/
# 应该能看到：my_example_ext_cpp_test

运行测试 Copy Section

验证扩展功能是否正常工作：

方式一：直接执行测试文件

./bin/my_example_ext_cpp_test

方式二：使用 tman 统一命令

tman run test

测试执行成功时的输出示例：

Running main() from ../../../tests/gtest_main.cc
[==========] Running 1 test from 1 test case.
[----------] 1 test from Test
[ RUN      ] Test.Basic
[       OK ] Test.Basic (20 ms)
[==========] 1 test from 1 test case ran. (79 ms total)
[  PASSED  ] 1 test.

成功标志：当您看到 [ PASSED ] 1 test. 时表示测试全部通过。

核心代码结构详解 Copy Section

扩展主体实现（src/main.cc）

C++ 扩展的核心类需要继承自 ten::extension_t 基类，并实现完整的生命周期管理方法：

class my_example_ext_cpp_t : public ten::extension_t {
 public:
  // 扩展初始化阶段 - 进行基础配置和资源预分配
  void on_init(ten::ten_env_t &ten_env) override;

  // 扩展启动阶段 - 正式开始处理业务逻辑
  void on_start(ten::ten_env_t &ten_env) override;

  // 命令处理器 - 处理来自其他扩展或应用的命令请求
  void on_cmd(ten::ten_env_t &ten_env, std::unique_ptr<ten::cmd_t> cmd) override;

  // 数据处理器 - 处理通用数据流
  void on_data(ten::ten_env_t &ten_env, std::unique_ptr<ten::data_t> data) override;

  // 音频帧处理器 - 处理实时音频流数据
  void on_audio_frame(ten::ten_env_t &ten_env, std::unique_ptr<ten::audio_frame_t> frame) override;

  // 视频帧处理器 - 处理实时视频流数据
  void on_video_frame(ten::ten_env_t &ten_env, std::unique_ptr<ten::video_frame_t> frame) override;

  // 扩展停止阶段 - 清理资源和优雅关闭
  void on_stop(ten::ten_env_t &ten_env) override;
};

测试框架实现（tests/basic.cc）

使用 TEN 专用测试框架编写完整的单元测试：

class my_example_ext_cpp_tester : public ten::extension_tester_t {
 public:
  void on_start(ten::ten_env_tester_t &ten_env) override {
    // 创建测试用的命令对象
    auto new_cmd = ten::cmd_t::create("foo");

    // 发送命令到扩展并验证响应结果
    ten_env.send_cmd(std::move(new_cmd), [](/* callback parameters */) {
      // 在这里验证测试结果的正确性
    });
  }
};

调试环境配置 Copy Section

VSCode 集成调试

1. 安装 VSCode 的 CodeLLDB 扩展插件
2. 在源代码中设置断点
3. 选择 "standalone test (lldb, launch)" 调试配置
4. 按 F5 键启动调试会话

调试配置文件 .vscode/launch.json 的内容：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "standalone test (lldb, launch)",
      "type": "lldb",
      "request": "launch",
      "program": "${workspaceFolder}/bin/my_example_ext_cpp_test",
      "cwd": "${workspaceFolder}"
    }
  ]
}

命令行调试

使用经典的 GDB 调试器进行命令行调试：

gdb ./bin/my_example_ext_cpp_test
(gdb) run
(gdb) bt  # 查看完整的函数调用栈

Go 扩展开发 Copy Chapter

Go 扩展在高性能和开发效率之间提供了很好的平衡，特别适合构建网络服务、并发处理、微服务架构等应用场景。

创建项目 Copy Section

使用 Go 扩展模板创建新项目：

tman create extension my_example_ext_go --template default_extension_go --template-data class_name_prefix=Example

项目创建成功后会显示：

🏆  Package 'extension:my_example_ext_go' created successfully in '/path/to/your/project' in 1 second.

完整的项目结构如下：

my_example_ext_go/
├── extension.go             # 扩展核心实现代码
├── go.mod                   # Go 模块依赖管理配置
├── manifest.json            # 扩展元数据信息
├── property.json            # 扩展属性配置
├── README.md                # 项目说明文档
├── tests/                   # 测试相关文件
│   ├── basic_tester.go      # 测试逻辑实现
│   ├── basic_tester_test.go # 测试用例定义
│   ├── main_test.go         # 测试程序入口
│   └── bin/start            # 测试启动脚本
└── .vscode/launch.json      # VSCode 调试配置

依赖包安装 Copy Section

安装项目运行所需的依赖包：

tman install --standalone

运行测试 Copy Section

验证扩展功能的正确性：

方式一：使用启动脚本

./tests/bin/start

方式二：使用 tman 命令

tman run test

测试成功执行的输出示例：

=== RUN   TestBasicExtensionTester
--- PASS: TestBasicExtensionTester (0.01s)
PASS

核心代码结构详解 Copy Section

扩展实现（extension.go）

Go 扩展的核心实现结构：

import (
    ten "ten_framework/ten_runtime"
)

type ExampleExtension struct {
    ten.DefaultExtension
}

// 扩展启动生命周期
func (e *ExampleExtension) OnStart(tenEnv ten.TenEnv) {
    tenEnv.LogDebug("OnStart")
    tenEnv.OnStartDone()
}

// 命令处理逻辑
func (e *ExampleExtension) OnCmd(tenEnv ten.TenEnv, cmd ten.Cmd) {
    tenEnv.LogDebug("OnCmd")
    cmdResult, _ := ten.NewCmdResult(ten.StatusCodeOk, cmd)
    tenEnv.ReturnResult(cmdResult, nil)
}

// 扩展停止生命周期
func (e *ExampleExtension) OnStop(tenEnv ten.TenEnv) {
    tenEnv.LogDebug("OnStop")
    tenEnv.OnStopDone()
}

测试框架（tests/basic_tester.go）

Go 扩展的测试框架实现：

type BasicExtensionTester struct {
    ten.DefaultExtensionTester
}

func (tester *BasicExtensionTester) OnStart(tenEnvTester ten.TenEnvTester) {
    // 创建用于测试的命令对象
    cmdTest, _ := ten.NewCmd("test")

    // 发送命令并处理响应结果
    tenEnvTester.SendCmd(cmdTest, func(tet ten.TenEnvTester, cr ten.CmdResult, err error) {
        if err != nil {
            panic(err)
        }
        statusCode, _ := cr.GetStatusCode()
        if statusCode != ten.StatusCodeOk {
            panic(statusCode)
        }
        tenEnvTester.StopTest(nil)
    })

    tenEnvTester.OnStartDone()
}

开发环境优化 Copy Section

为了提升开发体验和调试便利性，建议在扩展根目录创建 go.work 工作空间文件：

go 1.18

use (
    .
    .ten/app/ten_packages/system/ten_runtime_go/interface
)

调试环境配置 Copy Section

VSCode 集成调试

确保已安装 Go 官方扩展，然后使用以下调试配置：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "standalone test (go, launch)",
      "type": "go",
      "request": "launch",
      "mode": "test",
      "program": "${workspaceFolder}/tests/",
      "env": {
        "CGO_LDFLAGS": "-L${workspaceFolder}/.ten/app/ten_packages/system/ten_runtime/lib -L${workspaceFolder}/.ten/app/ten_packages/system/ten_runtime_go/lib -lten_runtime -lten_runtime_go",
        "LD_LIBRARY_PATH": "${workspaceFolder}/.ten/app/ten_packages/system/ten_runtime/lib:${workspaceFolder}/.ten/app/ten_packages/system/ten_runtime_go/lib"
      },
      "args": ["-test.v"]
    }
  ]
}

Python 扩展开发 Copy Chapter

Python 扩展具有最高的开发效率，特别适合快速原型开发、AI/ML 应用集成、复杂业务逻辑实现等场景。

创建项目 Copy Section

使用 Python 异步扩展模板创建项目：

tman create extension my_example_ext_python --template default_async_extension_python --template-data class_name_prefix=Example

完整的项目结构：

my_example_ext_python/
├── extension.py         # 扩展核心实现代码
├── addon.py             # 扩展插件注册入口
├── __init__.py          # Python 包初始化文件
├── requirements.txt     # Python 依赖包清单
├── manifest.json        # 扩展元数据配置
├── property.json        # 扩展属性配置
├── tests/               # 测试相关文件
│   ├── test_basic.py    # 基础测试用例
│   ├── conftest.py      # pytest 配置文件
│   └── bin/start        # 测试启动脚本
└── .vscode/launch.json  # VSCode 调试配置

依赖包安装 Copy Section

安装项目所需的 Python 依赖包：

tman install --standalone

运行测试 Copy Section

验证 Python 扩展的功能：

方式一：使用启动脚本

./tests/bin/start

方式二：使用 tman 命令

tman run test

测试成功执行的输出示例：

============================================ test session starts ============================================
platform linux -- Python 3.10.17, pytest-8.3.4, pluggy-1.5.0
tests/test_basic.py .                                                                                [100%]
============================================ 1 passed in 0.04s =======================================

核心代码结构详解 Copy Section

扩展实现（extension.py）

Python 扩展推荐使用现代异步编程模式，以获得更好的性能和并发处理能力：

from ten_runtime import (
    AudioFrame, VideoFrame, AsyncExtension, AsyncTenEnv,
    Cmd, StatusCode, CmdResult, Data
)

class ExampleExtension(AsyncExtension):
    async def on_init(self, ten_env: AsyncTenEnv) -> None:
        ten_env.log_debug("on_init")

    async def on_start(self, ten_env: AsyncTenEnv) -> None:
        ten_env.log_debug("on_start")
        # TODO: 在这里读取配置文件，初始化必要的资源

    async def on_cmd(self, ten_env: AsyncTenEnv, cmd: Cmd) -> None:
        cmd_name = cmd.get_name()
        ten_env.log_debug(f"on_cmd name {cmd_name}")

        # TODO: 在这里实现具体的业务逻辑处理
        cmd_result = CmdResult.create(StatusCode.OK, cmd)
        await ten_env.return_result(cmd_result)

    async def on_stop(self, ten_env: AsyncTenEnv) -> None:
        ten_env.log_debug("on_stop")
        # TODO: 在这里清理资源，进行优雅关闭

插件注册入口（addon.py）

扩展插件的注册和创建逻辑：

from ten_runtime import Addon, register_addon_as_extension, TenEnv
from .extension import ExampleExtension

@register_addon_as_extension("my_example_ext_python")
class ExampleExtensionAddon(Addon):
    def on_create_instance(self, ten_env: TenEnv, name: str, context) -> None:
        ten_env.log_info("on_create_instance")
        ten_env.on_create_instance_done(ExampleExtension(name), context)

测试实现（tests/test_basic.py）

完整的异步测试框架实现：

from ten_runtime import (
    AsyncExtensionTester, AsyncTenEnvTester, Cmd, StatusCode,
    TenError, TenErrorCode
)

class ExtensionTesterBasic(AsyncExtensionTester):
    async def on_start(self, ten_env: AsyncTenEnvTester) -> None:
        # 创建用于测试的命令对象
        new_cmd = Cmd.create("hello_world")

        ten_env.log_debug("send hello_world")
        result, err = await ten_env.send_cmd(new_cmd)

        # 验证测试结果的正确性
        if (err is not None or result is None
            or result.get_status_code() != StatusCode.OK):
            ten_env.stop_test(TenError.create(
                TenErrorCode.ErrorCodeGeneric,
                "Failed to send hello_world"
            ))
        else:
            ten_env.stop_test()

def test_basic():
    tester = ExtensionTesterBasic()
    tester.set_test_mode_single("my_example_ext_python")
    err = tester.run()
    if err is not None:
        assert False, err.error_message()

调试环境配置 Copy Section

VSCode 集成调试

确保已安装 Python 扩展和 debugpy 调试器，使用以下配置进行调试：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "standalone test (debugpy, launch)",
      "type": "debugpy",
      "request": "launch",
      "python": "/usr/bin/python3",
      "module": "pytest",
      "args": ["-s", "${workspaceFolder}/tests/test_basic.py"],
      "env": {
        "TEN_ENABLE_PYTHON_DEBUG": "true",
        "PYTHONPATH": "${workspaceFolder}/.ten/app/ten_packages/system/ten_runtime_python/lib:${workspaceFolder}/.ten/app/ten_packages/system/ten_runtime_python/interface:${workspaceFolder}"
      },
      "console": "integratedTerminal"
    }
  ]
}

Node.js 扩展开发 Copy Chapter

Node.js 扩展提供了现代 JavaScript/TypeScript 开发体验，特别适合 Web 应用集成、快速原型开发、前端技术栈扩展等场景。得益于 Node.js 的异步特性和丰富的生态系统，开发者可以轻松构建高效的实时应用。

创建项目 Copy Section

使用 TEN 官方提供的 Node.js 扩展模板快速创建新项目：

tman create extension my_example_ext_nodejs --template default_extension_nodejs --template-data class_name_prefix=Example

项目创建成功后，您会得到以下完整的项目结构：

my_example_ext_nodejs/
├── manifest.json         # 扩展元数据和配置信息
├── property.json         # 扩展属性和参数配置
├── package.json          # Node.js 依赖包管理配置
├── tsconfig.json         # TypeScript 编译器配置
├── src/
│   └── index.ts          # 扩展核心实现代码
├── tests/                # 测试相关文件
│   ├── src/
│   │   ├── index.ts      # 测试器实现
│   │   ├── index.spec.ts # 测试用例定义
│   │   └── main.spec.ts  # 测试框架配置
│   ├── bin/start         # 测试启动脚本
│   ├── package.json      # 测试依赖配置
│   └── tsconfig.json     # 测试 TypeScript 配置
├── tools/                # 辅助工具和脚本
└── .vscode/
    └── launch.json       # VSCode 调试配置文件

环境配置验证 Copy Section

进入项目目录并验证开发环境：

cd my_example_ext_nodejs
node --version
npm --version

期望输出：

v18.0.0 或更高版本
8.0.0 或更高版本

依赖包安装 Copy Section

安装扩展运行时所需的全部依赖包：

tman install --standalone

安装成功后，您将看到类似以下的详细安装日志：

📦  Get all installed packages...
🔍  Filter compatible packages...
🔒  Creating manifest-lock.json...
📥  Installing packages...
  [00:00:00] [########################################]       2/2       Done

🏆  Install successfully in 1 second

重要提示：tman install --standalone 会在项目目录下创建 .ten/app/ten_packages/extension/my_example_ext_nodejs/ 目录，后续的构建和测试操作都需要在这个目录下进行。

项目构建 Copy Section

Node.js 扩展使用 TypeScript 进行开发，需要先安装独立模式依赖，然后编译为 JavaScript：

方式一：手动构建

# 进入扩展的安装目录
cd .ten/app/ten_packages/extension/my_example_ext_nodejs

# 安装独立模式的 Node.js 依赖
npm run standalone-install

# 编译 TypeScript 代码
npm run build

方式二：使用 tman 快捷命令

tman run build

构建完成后，检查生成的编译结果：

ls -la .ten/app/ten_packages/extension/my_example_ext_nodejs/build/
# 应该能看到：index.js 和相关映射文件

运行测试 Copy Section

验证扩展功能是否正常工作：

方式一：使用启动脚本

# 进入扩展的安装目录
cd .ten/app/ten_packages/extension/my_example_ext_nodejs

# 运行测试
./tests/bin/start

方式二：使用 tman 统一命令

tman run test

测试执行成功时的输出示例：

MyExtensionTester onStart
MyExtensionTester onStop
MyExtensionTester onDeinit
deinit done
  ✓ case1 (1010ms)
MyExtensionTester onStart
MyExtensionTester onStop
MyExtensionTester onDeinit
deinit done
  ✓ case2 (1010ms)

  2 passing (2s)

成功标志：当您看到所有测试用例显示 ✓ 并且最后显示 passing 时表示测试全部通过。

核心代码结构详解 Copy Section

扩展主体实现（src/index.ts）

Node.js 扩展的核心类需要继承自 Extension 基类，并实现完整的生命周期管理方法：

import {
  Addon,
  RegisterAddonAsExtension,
  Extension,
  TenEnv,
  Cmd,
  CmdResult,
  StatusCode,
} from "ten-runtime-nodejs";

class DefaultExtension extends Extension {
  constructor(name: string) {
    super(name);
  }

  // 扩展配置阶段 - 进行配置参数的读取和验证
  async onConfigure(_tenEnv: TenEnv): Promise<void> {
    console.log("DefaultExtension onConfigure");
  }

  // 扩展初始化阶段 - 进行基础配置和资源预分配
  async onInit(_tenEnv: TenEnv): Promise<void> {
    console.log("DefaultExtension onInit");
  }

  // 扩展启动阶段 - 正式开始处理业务逻辑
  async onStart(_tenEnv: TenEnv): Promise<void> {
    console.log("DefaultExtension onStart");
  }

  // 命令处理器 - 处理来自其他扩展或应用的命令请求
  async onCmd(tenEnv: TenEnv, cmd: Cmd): Promise<void> {
    console.log("DefaultExtension onCmd", cmd.getName());

    const cmdResult = CmdResult.Create(StatusCode.OK, cmd);
    cmdResult.setPropertyString("detail", "This is a demo");
    tenEnv.returnResult(cmdResult);
  }

  // 扩展停止阶段 - 清理资源和优雅关闭
  async onStop(_tenEnv: TenEnv): Promise<void> {
    console.log("DefaultExtension onStop");
  }

  // 扩展销毁阶段 - 最终清理和资源释放
  async onDeinit(_tenEnv: TenEnv): Promise<void> {
    console.log("DefaultExtension onDeinit");
  }
}

插件注册入口

扩展插件的注册和创建逻辑：

@RegisterAddonAsExtension("default_extension_nodejs")
class DefaultExtensionAddon extends Addon {
  async onCreateInstance(
    _tenEnv: TenEnv,
    instanceName: string,
  ): Promise<Extension> {
    return new DefaultExtension(instanceName);
  }
}

测试框架实现（tests/src/index.ts）

使用 TEN 专用测试框架编写完整的单元测试：

import { ExtensionTester, TenEnvTester } from "ten-runtime-nodejs";

export class MyExtensionTester extends ExtensionTester {
  async onStart(tenEnvTester: TenEnvTester) {
    console.log("MyExtensionTester onStart");

    // 模拟异步操作和测试逻辑
    new Promise((resolve) => {
      setTimeout(() => {
        resolve(true);
      }, 1000);
    }).then(() => {
      // 停止测试并返回结果
      tenEnvTester.stopTest();
    });
  }

  async onStop(tenEnvTester: TenEnvTester) {
    console.log("MyExtensionTester onStop");
  }

  async onDeinit(tenEnvTester: TenEnvTester) {
    console.log("MyExtensionTester onDeinit");
  }
}

测试用例定义（tests/src/index.spec.ts）

使用 Mocha 测试框架编写具体的测试用例：

import assert from "assert";
import { MyExtensionTester } from "./index.js";

const test_addon_name = "default_extension_nodejs";

describe("MyExtensionTester", () => {
  it("case1", async () => {
    const extensionTester = new MyExtensionTester();
    extensionTester.setTestModeSingle(test_addon_name, "{}");
    const result = await extensionTester.run();
    assert(result === null, "result should be null");

    console.log("deinit done");
  });

  it("case2", async () => {
    const extensionTester = new MyExtensionTester();
    extensionTester.setTestModeSingle(test_addon_name, "{}");
    const result = await extensionTester.run();
    assert(result === null, "result should be null");

    console.log("deinit done");
  });
});

TypeScript 配置 Copy Section

Node.js 扩展使用现代 TypeScript 配置，支持最新的语言特性：

{
  "compilerOptions": {
    "allowJs": false,
    "composite": true,
    "module": "NodeNext",
    "target": "es6",
    "moduleResolution": "NodeNext",
    "outDir": "build",
    "removeComments": false,
    "sourceMap": true,
    "noImplicitAny": true,
    "noImplicitThis": true,
    "noImplicitReturns": true,
    "strictNullChecks": true,
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "rootDir": "src",
    "strict": true,
    "forceConsistentCasingInFileNames": true,
  },
  "exclude": [
    "node_modules"
  ],
  "include": [
    "src/**/*"
  ]
}

调试环境配置 Copy Section

VSCode 集成调试

确保已安装 Node.js 官方扩展，然后使用以下调试配置：

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "standalone test (nodejs) (mocha, launch)",
      "type": "node",
      "request": "launch",
      "program": "node_modules/mocha/bin/_mocha",
      "stopOnEntry": true,
      "args": [
        "--no-timeouts",
        "--package",
        "package.json",
      ],
      "cwd": "${workspaceFolder}/tests",
      "env": {
        "NODE_PATH": "../.ten/app/ten_packages/system/ten_runtime_nodejs/lib:$NODE_PATH",
      },
      "runtimeArgs": [
        "--expose-gc",
        "--loader",
        "ts-node/esm",
        "--no-warnings",
      ]
    }
  ]
}

命令行调试

使用 Node.js 内置调试器进行命令行调试：

# 进入扩展的安装目录
cd .ten/app/ten_packages/extension/my_example_ext_nodejs

# 启动调试模式
node --inspect-brk ./tests/bin/start

# 或者使用 Chrome DevTools
node --inspect ./tests/bin/start

完整开发流程总结 Copy Section

为了帮助开发者快速上手，这里提供一个完整的 Node.js 扩展开发流程总结：

# 1. 创建扩展项目
tman create extension my_example_ext_nodejs --template default_extension_nodejs --template-data class_name_prefix=Example

# 2. 进入项目目录
cd my_example_ext_nodejs

# 3. 安装依赖
tman install --standalone

# 4. 进入扩展安装目录
cd .ten/app/ten_packages/extension/my_example_ext_nodejs

# 5. 安装独立模式依赖
npm run standalone-install

# 6. 构建项目
npm run build

# 7. 运行测试
./tests/bin/start

工作目录说明：

• 扩展源代码位于项目根目录的 src/ 文件夹
• 实际的构建、测试和运行操作都在 .ten/app/ten_packages/extension/my_example_ext_nodejs/ 目录下进行
• 这种设计确保了扩展的独立性和依赖管理的正确性

开发最佳实践 Copy Section

异步编程

Node.js 扩展充分利用异步编程模式，提供更好的性能：

// 推荐：使用 async/await
async onCmd(tenEnv: TenEnv, cmd: Cmd): Promise<void> {
  try {
    const result = await processCommand(cmd);
    const cmdResult = CmdResult.Create(StatusCode.OK, cmd);
    cmdResult.setPropertyString("result", result);
    tenEnv.returnResult(cmdResult);
  } catch (error) {
    const cmdResult = CmdResult.Create(StatusCode.ERROR, cmd);
    cmdResult.setPropertyString("error", error.message);
    tenEnv.returnResult(cmdResult);
  }
}

错误处理

实现完善的错误处理机制：

async onCmd(tenEnv: TenEnv, cmd: Cmd): Promise<void> {
  try {
    // 业务逻辑处理
    const result = await this.handleBusinessLogic(cmd);

    const cmdResult = CmdResult.Create(StatusCode.OK, cmd);
    cmdResult.setPropertyString("data", JSON.stringify(result));
    tenEnv.returnResult(cmdResult);
  } catch (error) {
    console.error("Command processing error:", error);

    const cmdResult = CmdResult.Create(StatusCode.ERROR, cmd);
    cmdResult.setPropertyString("error", error.message);
    tenEnv.returnResult(cmdResult);
  }
}

开发总结 Copy Chapter

通过遵循本指南提供的完整开发流程，您可以高效地进行 TEN 扩展的开发、测试和调试工作。无论选择 C++，Go，Python 还是 Node.js，TEN Framework 都为您提供了完整的工具链和最佳实践，帮助您充分发挥 TEN Framework 的强大功能，构建出高性能、高可靠性的扩展应用。

每种语言都有其独特的优势和适用场景：

• C++：适用于对性能要求极高的场景，如实时音视频处理、高频计算
• Go：在高性能和开发效率之间提供平衡，适合网络服务、并发处理
• Python：具有最高的开发效率，特别适合AI/ML应用、快速原型开发
• Node.js：提供现代 Web 开发体验，适用于前端技术栈扩展、实时应用

请根据您的具体需求和团队技术栈选择最合适的开发方案。在开发过程中，建议充分利用 TEN Framework 提供的调试工具和测试框架，以确保扩展的质量和稳定性。

Development How To Develop With Ext (`docs/development/how_to_develop_with_ext.md`) Copy Section

title: Complete Guide to TEN Extension Development _portal_target: development/how_to_develop_with_ext.md Copy Chapter

TEN Framework provides rich extension templates to help developers quickly create extensions and complete the entire process from development to testing. This guide will demonstrate in detail how to use C++, Go, Python, and Node.js for the complete extension development workflow through practical operations.

Pre-development Preparation Copy Chapter

Environment Requirements Copy Section

Before starting extension development, please ensure your development environment is properly configured. Verify the installation with the following command:

tman --version

Under normal circumstances, you should see version information output similar to the following:

TEN Framework version: <version>

Important Note: Please ensure you are using tman version >= 0.10.12. If your version is too low, please refer to the Quick Start Guide to install the latest version.

Development Workflow Overview Copy Section

Regardless of which programming language you use, TEN extension development follows the following standardized workflow:

1. Project Creation - Generate extension project skeleton using official templates
2. Dependency Installation - Configure runtime environment and install necessary dependency packages
3. Core Development - Implement extension business logic and functional code
4. Build and Test - Compile project (if needed) and execute unit tests
5. Debug and Optimize - Use professional debugging tools to locate and solve problems

C++ Extension Development Copy Chapter

C++ extensions are suitable for application scenarios with extremely high performance requirements, such as real-time audio and video processing, high-frequency data computation, low-level system operations, etc.

Create Project Copy Section

Use the official C++ extension template provided by TEN to quickly create a new project:

tman create extension my_example_ext_cpp --template default_extension_cpp

After successful project creation, you will get the following complete project structure:

my_example_ext_cpp/
├── BUILD.gn              # GN build system configuration file
├── manifest.json         # Extension metadata and configuration information
├── property.json         # Extension properties and parameter configuration
├── src/
│   └── main.cc           # Extension core implementation code
├── tests/
│   ├── basic.cc          # Basic functionality test cases
│   └── gtest_main.cc     # Test framework program entry
├── include/              # Header file storage directory
├── tools/                # Auxiliary tools and scripts
└── .vscode/
    └── launch.json       # VSCode debugging configuration file

Environment Configuration Verification Copy Section

Enter the project directory and verify that the build tools are working properly:

cd my_example_ext_cpp
tgn --version

Expected Output:

0.1.0

If the command cannot be executed, please refer to the Quick Start Guide to check whether the TEN Framework development environment is correctly installed.

Dependency Package Installation Copy Section

Install all dependency packages required for extension runtime:

tman install --standalone

After successful installation, you will see detailed installation logs similar to the following:

📦  Get all installed packages...
🔍  Filter compatible packages...
🔒  Creating manifest-lock.json...
📥  Installing packages...
  [00:00:00] [########################################]       3/3       Done

🏆  Install successfully in 1 second

Project Build Copy Section

TEN framework provides two convenient build methods for you to choose from:

Method 1: Manual Step-by-step Build

# Step 1: Generate build configuration files (enable standalone test mode)
tgn gen linux x64 debug -- ten_enable_standalone_test=true

# Step 2: Execute project build
tgn build linux x64 debug

Method 2: Use tman Shortcut Command

tman run build

After the build is complete, check the generated executable test file:

ls -la bin/
# You should see: my_example_ext_cpp_test

Run Tests Copy Section

Verify that the extension functionality is working properly:

Method 1: Execute Test File Directly

./bin/my_example_ext_cpp_test

Method 2: Use tman Unified Command

tman run test

Example output when tests execute successfully:

Running main() from ../../../tests/gtest_main.cc
[==========] Running 1 test from 1 test case.
[----------] 1 test from Test
[ RUN      ] Test.Basic
[       OK ] Test.Basic (20 ms)
[==========] 1 test from 1 test case ran. (79 ms total)
[  PASSED  ] 1 test.

Success Indicator: When you see [ PASSED ] 1 test. it means all tests have passed.

Core Code Structure Explanation Copy Section

Extension Main Implementation (src/main.cc)

The core class of C++ extensions needs to inherit from the ten::extension_t base class and implement complete lifecycle management methods:

class my_example_ext_cpp_t : public ten::extension_t {
 public:
  // Extension initialization phase - basic configuration and resource pre-allocation
  void on_init(ten::ten_env_t &ten_env) override;

  // Extension startup phase - officially start processing business logic
  void on_start(ten::ten_env_t &ten_env) override;

  // Command handler - handle command requests from other extensions or applications
  void on_cmd(ten::ten_env_t &ten_env, std::unique_ptr<ten::cmd_t> cmd) override;

  // Data handler - handle general data flow
  void on_data(ten::ten_env_t &ten_env, std::unique_ptr<ten::data_t> data) override;

  // Audio frame handler - handle real-time audio stream data
  void on_audio_frame(ten::ten_env_t &ten_env, std::unique_ptr<ten::audio_frame_t> frame) override;

  // Video frame handler - handle real-time video stream data
  void on_video_frame(ten::ten_env_t &ten_env, std::unique_ptr<ten::video_frame_t> frame) override;

  // Extension stop phase - clean up resources and graceful shutdown
  void on_stop(ten::ten_env_t &ten_env) override;
};

Test Framework Implementation (tests/basic.cc)

Use TEN-specific test framework to write complete unit tests:

class my_example_ext_cpp_tester : public ten::extension_tester_t {
 public:
  void on_start(ten::ten_env_tester_t &ten_env) override {
    // Create command object for testing
    auto new_cmd = ten::cmd_t::create("foo");

    // Send command to extension and verify response results
    ten_env.send_cmd(std::move(new_cmd), [](/* callback parameters */) {
      // Verify the correctness of test results here
    });
  }
};

Debug Environment Configuration Copy Section

VSCode Integrated Debugging

1. Install the CodeLLDB extension plugin for VSCode
2. Set breakpoints in source code
3. Select the "standalone test (lldb, launch)" debug configuration
4. Press F5 to start debugging session

Debug configuration file .vscode/launch.json content:

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "standalone test (lldb, launch)",
      "type": "lldb",
      "request": "launch",
      "program": "${workspaceFolder}/bin/my_example_ext_cpp_test",
      "cwd": "${workspaceFolder}"
    }
  ]
}

Command Line Debugging

Use the classic GDB debugger for command-line debugging:

gdb ./bin/my_example_ext_cpp_test
(gdb) run
(gdb) bt  # View complete function call stack

Go Extension Development Copy Chapter

Go extensions provide a good balance between high performance and development efficiency, particularly suitable for building network services, concurrent processing, microservice architecture and other application scenarios.

Create Project Copy Section