Build your first extension

Extensions are modular components that add specific capabilities to your agent. They can process inputs, generate outputs, or connect to external services, making your agent more powerful and versatile. While TEN Agent includes many pre-built extensions for common use cases, you may need to develop your own to add custom functionality, integrate with proprietary services, or optimize for specific requirements.

This guide walks you through creating your first TEN Agent extension. You'll build a "Hello World" extension in your choice of Python, Go, or C++.

Prerequisites

Before starting:

Complete the Agent quickstart
Ensure Docker Compose is running
Understand basic container operations

Implementation

Follow these steps to create your first extension.

Start the development environment

Run the following command on your local machine:

# Run on your local machine
docker compose up

You see output similar to the following:

Attaching to ten_agent_dev, ten_agent_playground
ten_agent_dev         | cd agents && tman designer
ten_agent_dev         | :-)  Starting server at http://0.0.0.0:49483
ten_agent_playground  |   ▲ Next.js 14.2.4
ten_agent_playground  |   - Local:        http://localhost:3000
ten_agent_playground  |   - Network:      http://0.0.0.0:3000
ten_agent_playground  |
ten_agent_playground  |  ✓ Starting...
ten_agent_playground  |  ✓ Ready in 429ms
...

You now have:

Development server ten_agent_dev at http://0.0.0.0:49483
Playground interface ten_agent_playground at http://localhost:3000

Create the extension

Enter the development container:

_2# Run on your local machine _2docker exec -it ten_agent_dev bash
Navigate to the extensions directory:

_2# Run inside Docker container _2cd /app/agents/ten_packages/extension

Create your extension using the appropriate template:

Python
Go
C++

cd /app/agents/ten_packages/extension
 tman create extension hello_world --template=default_async_extension_python@0.6 --template-data class_name_prefix=HelloWorld

cd /app/agents/ten_packages/extension
 tman create extension hello_world --template=default_extension_go@0.6 --template-data class_name_prefix=HelloWorld

cd /app/agents/ten_packages/extension
 tman create extension hello_world --template=default_extension_cpp@0.6 --template-data class_name_prefix=HelloWorld

The log shows confirmation that the package was created successfully.

Package 'extension:hello_world' created successfully in '/app' in 3 seconds.

Define the extension API

Open manifest.json in the hello_world directory and add data_in and cmd_out API definitions to the file:

{
  "type": "extension",
  "name": "hello_world",
  "version": "0.3.1",
  "dependencies": [
    {
      "type": "system",
      "name": "ten_runtime_python",
      "version": "0.3.1"
    }
  ],
  "package": {
    "include": [
      "manifest.json",
      "property.json",
      "BUILD.gn",
      "**.tent",
      "**.py",
      "README.md",
      "tests/**"
    ]
  },
  "api": {
    "data_in": [ 
      { 
        "name": "text_data", 
        "property": { 
          "text": { 
            "type": "string" 
          }, 
          "is_final": { 
            "type": "bool" 
          } 
        } 
      } 
    ], 
    "cmd_out": [ 
      { 
        "name": "flush" 
      } 
    ] 
  }
}

Build and deploy

Return to the project root:

_2# Run inside Docker container _2cd /app
Build the extension:

_2# Run inside Docker container _2task use
Apply changes:
- First build: No restart needed
- Subsequent updates: Refresh the playground page. If changes do not appear, restart the server container.

Congratulations! You’ve successfully created your first extension.

Prerequisites​

Implementation​

Start the development environment​

Create the extension​

Define the extension API​

Build and deploy​