### Clone Repository and Setup Environment Variables Source: https://github.com/ten-framework/portal/blob/main/content/docs/ten_agent/getting_started.mdx This snippet demonstrates how to clone the TEN framework repository, navigate to the ai-agents directory, and copy the example environment file to create a new .env file for configuration. ```bash cd ai_agents cp ./.env.example ./.env ``` -------------------------------- ### Start TEN Agent Development Containers Source: https://github.com/ten-framework/portal/blob/main/content/docs/ten_agent/getting_started.mdx This command initiates the Docker Compose setup to start the development containers for the TEN agent. ```bash docker compose up -d ``` -------------------------------- ### Build and Use TEN Agents Source: https://github.com/ten-framework/portal/blob/main/content/docs/ten_agent/getting_started.mdx This snippet illustrates how to build a TEN agent using the default graph or specify a particular agent from the examples directory. It includes commands to select an agent and run it. ```bash # use the default agent task use # this is equivalent to following command task use AGENT=agents/examples/voice-assistant # you can also change the command to setup other examples task use AGENT=agents/examples/ ``` -------------------------------- ### Clone TEN Agent Repository Source: https://github.com/ten-framework/portal/blob/main/content/docs/ten_agent/getting_started.cn.mdx Clones the TEN Agent repository from GitHub to start the setup process. ```sh git clone https://github.com/TEN-framework/TEN-Agent.git ``` -------------------------------- ### Run TEN Agent Web Server Source: https://github.com/ten-framework/portal/blob/main/content/docs/ten_agent/getting_started.mdx This command starts the web server for the TEN framework, making the agent accessible via a web interface. ```bash task run ``` -------------------------------- ### Install Dependencies and Run Development Server (Bun) Source: https://github.com/ten-framework/portal/blob/main/README.md This snippet shows how to install project dependencies using Bun and then start the development server for the TEN Portal. It assumes Bun is already installed. ```bash # install dependencies # refer to https://bun.sh/ for bun installation bun i # run the development server bun dev ``` -------------------------------- ### Start Development Server Source: https://github.com/ten-framework/portal/blob/main/CONTRIBUTING.md Starts the local development server for the Ten Framework Portal. Requires Node.js 22+ and Bun 1.1+. ```bash bun dev ``` -------------------------------- ### Full Start Graph Command Example Source: https://github.com/ten-framework/portal/blob/main/content/docs/ten_framework/graph/graph.cn.md This example demonstrates a complete `start_graph` command, including the `type` and detailed `nodes` and `connections` for the graph to be created. It shows how to define extensions and their interconnections. ```json { "ten": { "type": "start_graph", "nodes": [ { "type": "extension", "name": "simple_http_server_cpp", "addon": "simple_http_server_cpp", "extension_group": "default_extension_group", "property": { "root_key": "player", "extra_keys": ["playerName"] } } ], "connections": [ { "app": "msgpack://127.0.0.1:8001/", "extension": "simple_http_server_cpp", "cmd": [ { "name": "start", "dest": [ { "app": "msgpack://127.0.0.1:8001/", "extension": "gateway" } ] }, { "name": "stop", "dest": [ { "app": "msgpack://127.0.0.1:8001/", "extension": "gateway" } ] } ] }, { "extension": "gateway", "cmd": [ { "name": "push_status_online", "dest": [ { "extension": "uap" } ] } ] } ] } } ``` -------------------------------- ### Go Extension Dependency Installation Source: https://github.com/ten-framework/portal/blob/main/content/docs/ten_framework/development/how_to_develop_with_ext.md Command to install the necessary dependency packages for a Go extension project to run. ```bash tman install --standalone ``` -------------------------------- ### Run Demo from Source Code Source: https://github.com/ten-framework/portal/blob/main/content/docs/ten_agent/demo/index.md These commands guide you through running the TEN-Agent demo from its source code. It involves navigating to the demo directory, installing dependencies using pnpm, and starting the demo server. ```shell cd demo pnpm install pnpm dev ``` -------------------------------- ### Start Front-end UI in Codespace Source: https://github.com/ten-framework/portal/blob/main/content/docs/ten_agent/setup_development_env/setting_up_development_inside_codespace.md Instructions for starting the front-end UI in a GitHub Codespace environment. This involves navigating to the playground directory, installing dependencies using pnpm, and starting the development server. ```typescript cd playground pnpm install pnpm dev ``` -------------------------------- ### Create .env File Source: https://github.com/ten-framework/portal/blob/main/content/docs/ten_agent/getting_started.cn.mdx Copies the example environment file to create the actual .env file for configuration. ```sh cp ./.env.example ./.env ``` -------------------------------- ### Install Dependencies Source: https://github.com/ten-framework/portal/blob/main/CONTRIBUTING.md Installs project dependencies using Bun. Ensure Node.js 22+ and Bun 1.1+ are installed beforehand. ```bash bun install ``` -------------------------------- ### Install Dependency Packages Source: https://github.com/ten-framework/portal/blob/main/content/docs/ten_framework/development/how_to_develop_with_ext.md Installs all necessary dependency packages for the extension's runtime using the `tman install --standalone` command. This process creates a `.ten/app/ten_packages/extension/` directory. ```bash tman install --standalone ``` -------------------------------- ### Start and Run Ubuntu Docker Container Source: https://github.com/ten-framework/portal/blob/main/content/docs/ten_framework/preparation.md Starts a Docker container for building the TEN framework on Ubuntu 22.04 in detached mode and then runs the build environment within that container. ```shell docker-compose up -d docker-compose run ten-building-ubuntu-2204 ``` -------------------------------- ### Install Git using Homebrew Source: https://github.com/ten-framework/portal/blob/main/content/blog/exploring-the-ai-sales-avatar.mdx Installs Git, a version control system essential for managing the TEN framework codebase, using the Homebrew package manager. Verifies the installation by checking the Git version. ```bash brew install git git -v ``` -------------------------------- ### Ubuntu Docker Container Setup and Execution Source: https://github.com/ten-framework/portal/blob/main/content/docs/ten_framework/preparation.cn.md Commands to set up and run a Docker container for building the TEN framework on Ubuntu 22.04. It first starts the container in detached mode and then executes the build environment within it. ```shell docker-compose up -d docker-compose run ten-building-ubuntu-2204 ``` -------------------------------- ### macOS Language Bindings Installation (Golang, Python) Source: https://github.com/ten-framework/portal/blob/main/content/docs/ten_framework/preparation.cn.md Installs Go and Python using Homebrew on macOS to support the development of various language bindings for the TEN framework. This command ensures the necessary language runtimes are available. ```shell brew install python golang ``` -------------------------------- ### Install TEN Extension Dependencies (Bash) Source: https://github.com/ten-framework/portal/blob/main/content/docs/ten_framework/development/how_to_develop_with_ext.md Installs all necessary dependency packages for the TEN extension runtime in standalone mode. This ensures the extension has the required libraries to function. ```bash tman install --standalone ``` -------------------------------- ### Configure API Keys in .env File Source: https://github.com/ten-framework/portal/blob/main/content/docs/ten_agent/getting_started.mdx This snippet shows the structure of the .env file for configuring API keys required by various TEN framework extensions, including Agora, ElevenLabs TTS, and Deepgram ASR. ```bash # Agora App ID # Agora App Certificate(only required if enabled in the Agora Console) AGORA_APP_ID= AGORA_APP_CERTIFICATE= # Extension: elevenlabs_tts # ElevenLabs TTS key ELEVENLABS_TTS_KEY= # Extension: deepgram_asr # Deepgram ASR key DEEPGRAM_API_KEY= ``` -------------------------------- ### Run Go Extension Tests Source: https://github.com/ten-framework/portal/blob/main/content/docs/ten_framework/development/how_to_develop_with_ext.cn.md Demonstrates two methods for running tests on a Go extension: using a local start script or the 'tman run test' command. Includes an example of successful test output. ```bash ./tests/bin/start ``` ```bash tman run test ``` ```bash === RUN TestBasicExtensionTester --- PASS: TestBasicExtensionTester (0.01s) PASS ``` -------------------------------- ### macOS Development Environment Setup (Homebrew) Source: https://github.com/ten-framework/portal/blob/main/content/docs/ten_framework/preparation.cn.md Installs essential development tools on macOS using Homebrew, including LLVM, Google Test, Doxygen, Ninja, clang-format, and include-what-you-use. This is a prerequisite for building the TEN framework on macOS. ```shell brew install llvm googletest doxygen ninja clang-format brew install include-what-you-use ``` -------------------------------- ### Run Tests Manually (Node.js Extension) Source: https://github.com/ten-framework/portal/blob/main/content/docs/ten_framework/development/how_to_develop_with_ext.md Executes the tests for a Node.js extension using the provided startup script `./tests/bin/start`. This command should be run from within the extension's installation directory. ```bash # Enter the extension installation directory cd .ten/app/ten_packages/extension/my_example_ext_nodejs # Run tests ./tests/bin/start ``` -------------------------------- ### Implement Python Extension Logic Source: https://github.com/ten-framework/portal/blob/main/content/docs/ten_framework/development/how_to_develop_with_ext.md Demonstrates the structure of a Python extension using asynchronous programming patterns. It includes methods for initialization, starting, command handling, and stopping, leveraging the `AsyncExtension` class from `ten_runtime`. ```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: Read configuration files here, initialize necessary resources 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: Implement specific business logic processing here 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: Clean up resources here, perform graceful shutdown ``` -------------------------------- ### Start Docker Containers Source: https://github.com/ten-framework/portal/blob/main/content/blog/exploring-the-ai-sales-avatar.mdx Navigates to the 'ai_agents' directory and starts the Docker container services in detached mode. This command launches the main development container, an example agent instance, and the frontend interface. ```bash cd ai_agents docker compose up -d ``` -------------------------------- ### Complete start_graph Example with Nodes and Connections Source: https://github.com/ten-framework/portal/blob/main/content/docs/ten_framework/graph/graph.md A comprehensive example of the `start_graph` command, illustrating the definition of nodes (e.g., `simple_http_server_cpp`) and connections between extensions and applications, including command sequences. ```json { "ten": { "type": "start_graph", "nodes": [ { "type": "extension", "name": "simple_http_server_cpp", "addon": "simple_http_server_cpp", "extension_group": "default_extension_group", "property": { "root_key": "player", "extra_keys": ["playerName"] } } ], "connections": [ { "app": "msgpack://127.0.0.1:8001/", "extension": "simple_http_server_cpp", "cmd": [ { "name": "start", "dest": [ { "app": "msgpack://127.0.0.1:8001/", "extension": "gateway" } ] }, { "name": "stop", "dest": [ { "app": "msgpack://127.0.0.1:8001/", "extension": "gateway" } ] } ] }, { "extension": "gateway", "cmd": [ { "name": "push_status_online", "dest": [ { "extension": "uap" } ] } ] } ] } } ``` -------------------------------- ### Debugging Python in VSCode Dev Container Source: https://github.com/ten-framework/portal/blob/main/content/docs/ten_agent/setup_development_env/setting_up_vscode_for_development_inside_container.md This snippet illustrates how to configure and start a Python debugging session within a VSCode Dev Container. It assumes that the necessary Python language extensions are installed inside the container and a breakpoint has been set in the code. ```python debug python ``` -------------------------------- ### Build and Run TEN Agent in Codespace Source: https://github.com/ten-framework/portal/blob/main/content/docs/ten_agent/setup_development_env/setting_up_development_inside_codespace.md Commands to prepare the environment and build the TEN Agent within a GitHub Codespace. This includes copying an example environment file, setting API keys, building the agent, and starting the server. ```bash cp ./.env.example .env task use ``` ```bash task run ``` -------------------------------- ### Running Go Extension Tests (Startup Script) Source: https://github.com/ten-framework/portal/blob/main/content/docs/ten_framework/development/how_to_develop_with_ext.md Executes the tests for a Go extension using its provided startup script. ```bash ./tests/bin/start ``` -------------------------------- ### Go Extension Core Implementation Source: https://github.com/ten-framework/portal/blob/main/content/docs/ten_framework/development/how_to_develop_with_ext.md Provides the fundamental structure for Go extensions in the Ten Framework. It includes methods for extension startup (OnStart), command handling (OnCmd), and shutdown (OnStop), interacting with the Ten environment for logging and returning results. ```Go import ( ten "ten_framework/ten_runtime" ) type ExampleExtension struct { ten.DefaultExtension } // Extension startup lifecycle func (e *ExampleExtension) OnStart(tenEnv ten.TenEnv) { tenEnv.LogDebug("OnStart") tenEnv.OnStartDone() } // Command handling logic func (e *ExampleExtension) OnCmd(tenEnv ten.TenEnv, cmd ten.Cmd) { tenEnv.LogDebug("OnCmd") cmdResult, _ := ten.NewCmdResult(ten.StatusCodeOk, cmd) tenEnv.ReturnResult(cmdResult, nil) } // Extension stop lifecycle func (e *ExampleExtension) OnStop(tenEnv ten.TenEnv) { tenEnv.LogDebug("OnStop") tenEnv.OnStopDone() } ``` -------------------------------- ### Install Language Bindings on macOS Source: https://github.com/ten-framework/portal/blob/main/content/docs/ten_framework/preparation.md Installs Python and Go, which are required for the TEN framework's language bindings, using Homebrew. ```shell brew install python golang ``` -------------------------------- ### Run Voice Assistant Example in Node.js Source: https://github.com/ten-framework/portal/blob/main/content/blog/coding-voice-agent-using-nodejs.mdx Commands to set up and run the voice assistant example using the TEN Framework's task runner. Includes selecting the agent and running the task. ```Bash task use AGENT=agents/examples/voice-assistant-nodejs task run ``` -------------------------------- ### Run TEN Agent Web Server Source: https://github.com/ten-framework/portal/blob/main/content/docs/ten_agent/getting_started.cn.mdx Executes the 'run' task within the TEN Agent container to start the web server. ```bash task run ``` -------------------------------- ### Configure .env File for TEN Agent Source: https://github.com/ten-framework/portal/blob/main/content/docs/ten_agent/getting_started.cn.mdx Sets up environment variables in the .env file for TEN Agent, including Agora credentials and API keys for extensions like ElevenLabs TTS and Deepgram ASR. ```bash # Agora App ID # Agora App Certificate(only required if enabled in the Agora Console) AGORA_APP_ID= AGORA_APP_CERTIFICATE= # Extension: elevenlabs_tts # ElevenLabs TTS key ELEVENLABS_TTS_KEY= # Extension: deepgram_asr # Deepgram ASR key DEEPGRAM_API_KEY= ``` -------------------------------- ### Verify TEN Framework Installation (Bash) Source: https://github.com/ten-framework/portal/blob/main/content/docs/ten_framework/development/how_to_develop_with_ext.md Checks if the TEN Framework command-line tool (tman) is installed and displays its version. This is a prerequisite for extension development. ```bash tman --version ``` -------------------------------- ### Start TEN App (Shell) Source: https://github.com/ten-framework/portal/blob/main/content/docs/ten_framework/language_binding/go.md Starts the compiled TEN Go application. It is recommended to use the provided './bin/start' script to ensure all necessary environment variables are correctly set. ```shell ./bin/start ``` -------------------------------- ### Install Node.js using Homebrew Source: https://github.com/ten-framework/portal/blob/main/content/blog/exploring-the-ai-sales-avatar.mdx Installs Node.js, required for running the TEN Playground frontend locally, using the Homebrew package manager. Verifies the installation by checking the Node.js version. ```bash brew install node node -v ``` -------------------------------- ### Install Python Dependencies Source: https://github.com/ten-framework/portal/blob/main/content/docs/ten_framework/development/how_to_develop_with_ext.md Installs the necessary Python dependency packages for a Ten Framework extension project using the `tman` command-line tool in standalone mode. ```Bash tman install --standalone ``` -------------------------------- ### Start TEN Framework Services Source: https://github.com/ten-framework/portal/blob/main/content/docs/ten_agent/extension_dev/create_a_hello_world_extension.cn.mdx Starts the necessary services for the TEN framework using Docker Compose. This command ensures that the development and playground environments are running. ```Bash docker compose up -d ``` -------------------------------- ### Node.js Extension Development Process Summary Source: https://github.com/ten-framework/portal/blob/main/content/docs/ten_framework/development/how_to_develop_with_ext.md This bash script outlines the essential steps for developing a Node.js TEN framework extension. It covers project creation, dependency installation, building, and running tests, providing a streamlined workflow for developers. ```bash # 1. Create extension project tman create extension my_example_ext_nodejs --template default_extension_nodejs --template-data class_name_prefix=Example # 2. Enter project directory cd my_example_ext_nodejs # 3. Install dependencies tman install --standalone # 4. Enter extension installation directory cd .ten/app/ten_packages/extension/my_example_ext_nodejs # 5. Install standalone mode dependencies npm run standalone-install # 6. Build project npm run build # 7. Run tests ./tests/bin/start ``` -------------------------------- ### Validate Addon Installation with Mismatched URI Source: https://github.com/ten-framework/portal/blob/main/content/docs/ten_framework/ten_manager/check_graph.md This example demonstrates how to use 'tman check graph' to validate addon installation when the 'ten::uri' in property.json does not match the 'app' field in the nodes. It shows the expected output when packages are declared but not installed due to this mismatch. ```json { "ten": { "predefined_graphs": [ { "name": "default", "auto_start": false, "nodes": [ { "type": "extension", "name": "some_extension", "addon": "default_extension_go", "extension_group": "some_group" } ] } ], "uri": "http://localhost:8001" } } ``` ```shell tman check graph --app /home/TEN-Agent/agents ``` ```text Checking graph[0]... ❌. Details: The following packages are declared in nodes but not installed: [("localhost", Extension, "default_extension_go")]. All is done. ❌ Error: 1/1 graphs failed. ``` -------------------------------- ### Run Python Extension Tests (Startup Script) Source: https://github.com/ten-framework/portal/blob/main/content/docs/ten_framework/development/how_to_develop_with_ext.md Executes the tests for a Python extension by running the provided startup script located in the `tests/bin/` directory. ```Bash ./tests/bin/start ``` -------------------------------- ### Install macOS Dependencies with Homebrew Source: https://github.com/ten-framework/portal/blob/main/content/docs/ten_framework/preparation.md Installs essential development tools for the TEN framework on macOS using Homebrew, including LLVM, Google Test, Doxygen, Ninja, clang-format, and include-what-you-use. ```shell brew install llvm googletest doxygen ninja clang-format brew install include-what-you-use ``` -------------------------------- ### Successful Extension Creation Confirmation Source: https://github.com/ten-framework/portal/blob/main/content/docs/ten_agent/extension_dev/create_a_hello_world_extension.mdx This is a sample output indicating that the 'hello_world' extension package has been successfully created within the '/app' directory, along with the time taken for the operation. ```bash Package 'extension:hello_world' created successfully in '/app' in 3 seconds. ``` -------------------------------- ### Start Docker Compose in Detached Mode Source: https://github.com/ten-framework/portal/blob/main/content/docs/ten_agent/setup_development_env/setting_up_vscode_for_development_inside_container.md This command starts the Docker containers defined in the `docker-compose.yml` file in detached mode, allowing them to run in the background. This is a common practice for setting up development environments. ```shell docker compose up -d ``` -------------------------------- ### Enter TEN Agent Docker Container Source: https://github.com/ten-framework/portal/blob/main/content/docs/ten_agent/getting_started.cn.mdx Executes a command to enter the running TEN Agent development container with an interactive terminal. ```bash docker exec -it ten_agent_dev bash ``` -------------------------------- ### Validate Addon Installation When 'ten_packages' is Missing Source: https://github.com/ten-framework/portal/blob/main/content/docs/ten_framework/ten_manager/check_graph.md This example illustrates the validation process using 'tman check graph' when the 'ten_packages' directory is missing, indicating that 'tman install' has not been executed. It highlights the error output when declared addons cannot be found. ```json { "ten": { "predefined_graphs": [ { "name": "default", "auto_start": false, "nodes": [ { "type": "extension", "name": "some_extension", "addon": "default_extension_go", "extension_group": "some_group" } ] } ] } } ``` ```shell tman check graph --app /home/TEN-Agent/agents ``` ```text Checking graph[0]... ❌. Details: The following packages are declared in nodes but not installed: [("localhost", Extension, "default_extension_go")]. All is done. ❌ Error: 1/1 graphs failed. ``` -------------------------------- ### Start Servers with Docker Compose Source: https://github.com/ten-framework/portal/blob/main/content/docs/ten_agent/extension_dev/create_a_hello_world_extension.mdx This command initiates the necessary backend services for the Ten Framework development environment using Docker Compose. It ensures that the 'ten_agent_dev' and 'ten_agent_playground' services are running in detached mode. ```bash docker compose up -d ``` -------------------------------- ### Resolve clang-tidy Path on macOS Source: https://github.com/ten-framework/portal/blob/main/content/docs/ten_framework/preparation.md Ensures that CMake can locate `clang-tidy` by creating a symbolic link to the correct installation path. ```shell ln -sf /usr/local/opt/llvm/bin/clang-tidy /usr/local/bin/clang-tidy ``` -------------------------------- ### Manual Project Build (Node.js Extension) Source: https://github.com/ten-framework/portal/blob/main/content/docs/ten_framework/development/how_to_develop_with_ext.md Builds a Node.js extension by first installing standalone Node.js dependencies using `npm run standalone-install` and then compiling the TypeScript code with `npm run build`. This is done within the extension's installation directory. ```bash # Enter the extension installation directory cd .ten/app/ten_packages/extension/my_example_ext_nodejs # Install standalone mode Node.js dependencies npm run standalone-install # Compile TypeScript code npm run build ``` -------------------------------- ### Project Structure Overview Source: https://github.com/ten-framework/portal/blob/main/content/docs/ten_framework/development/how_to_develop_with_ext.md Provides a detailed breakdown of the file and directory structure for a newly created TEN Node.js extension project, including configuration files, source code, tests, and build artifacts. ```bash my_example_ext_nodejs/ ├── manifest.json # Extension metadata and configuration information ├── property.json # Extension properties and parameter configuration ├── package.json # Node.js dependency package management configuration ├── tsconfig.json # TypeScript compiler configuration ├── src/ │ └── index.ts # Extension core implementation code ├── tests/ # Test-related files │ ├── src/ │ │ ├── index.ts # Tester implementation │ │ ├── index.spec.ts # Test case definition │ │ └── main.spec.ts # Test framework configuration │ ├── bin/start # Test startup script │ ├── package.json # Test dependency configuration │ └── tsconfig.json # Test TypeScript configuration ├── tools/ # Auxiliary tools and scripts └── .vscode/ └── launch.json # VSCode debug configuration file ``` -------------------------------- ### TEN Framework C++ Property Conversion Example Source: https://github.com/ten-framework/portal/blob/main/content/docs/ten_framework/api/type_system.md Demonstrates how to set and get property values using the TEN framework's C++ API, illustrating safe and unsafe type conversions. It shows successful conversions from int32 to int64 and an example of an unsafe conversion that would result in an error. ```cpp // Set property value. The type of `property_name` in TEN runtime is `int32`. cmd.set_property("property_name", 100); // Get property value. Correct. int32_t value = cmd.get_property_int32("property_name"); // Get property value. Correct. TEN type system will automatically convert the type to `int64`. int64_t value2 = cmd.get_property_int64("property_name"); // Get property value. Incorrect, an error will be thrown because this is an unsafe conversion. int16_t error_type = cmd.get_property_int16("property_name"); ``` -------------------------------- ### Build Node.js Extension using tman Source: https://github.com/ten-framework/portal/blob/main/content/docs/ten_framework/development/how_to_develop_with_ext.md A shortcut command provided by TEN to build Node.js extensions. It automates the process of installing dependencies and compiling the code. ```bash tman run build ```