# ten-framework/ten-agent architecture

> Architecture diagram of the GitHub repository ten-framework/ten-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ten-framework/ten-agent
- Repository: https://github.com/ten-framework/ten-agent

## Overview

Based on our analysis of both the file tree and the README, TEN Agent is a modular and multi-component agent framework that combines a robust, agent-driven backend (written in Go with additional support modules using Python and other languages) with one or more frontends (demo and playground folders are based on Next.js). Its purpose is to provide a flexible AI agent framework that integrates multiple APIs (such as Agora, Deepgram, Elevenlabs, and Trulience) and offers ready-to-use extensions for diverse capabilities like voice, real‑time collaboration, multimedia interactions, and even hardware integrations (as evident by the esp32-client).

- Agent Core: Represented by the “agents” folder which contains the main Go code (e.g., main.go and various scripts) as well as configuration files (e.g., session_control.conf) and integration support.
- Extension Modules: Under “agents/ten_packages” there are multiple submodules (each with manifest.json and property.json) that indicate a plugin architecture. Each extension (e.g. for TTS, ASR, LLM integrations) should be depicted as individual components or a grouped “Extensions” module.
- Server Component: The “server” folder contains its own Go-based HTTP server and middleware modules. This is likely used to expose APIs for agent control or configuration.
- Hardware Clients: Include the “esp32-client” which demonstrates integration on embedded hardware for real-time responses.
- Supporting Artifacts: Dockerfiles, Taskfiles, CI/CD configuration, and development container setups indicate a containerized, cloud/deployment-friendly architecture.

##### Relationships and Data Flow
- If applicable, outline any event-driven or real‑time communication flows (RTM/RTC) between components – for example, between the demo UI’s real‑time video/audio streams and the internal agent handling these streams.

##### Important Architectural Patterns
- Modular Architecture: Emphasize the plugin system where flexible extension modules (each with its own configuration) are integrated into the agent core.
- Separation of Concerns: Clearly demarcate the backend (agent core, server) from the frontend (demo, playground) and from hardware clients (esp32-client).
- Microservices/Multi-language Integration: Note that while many parts are in Go, there is a mix of Python and other languages, promoting a loosely-coupled design.
- Containerization and CI/CD: Include components showing that Docker, GitHub workflows, and Taskfile automation are used for development, testing, and deployment.

##### Technologies and Frameworks
- Backend: Go (main agent core & server), Python (for some extensions), and a variety of extension-specific libraries based on the manifest & property files.
- Frontend: Next.js, TypeScript, Tailwind CSS, and other modern web technologies evident from the demo and playground directories.
- DevOps: Docker, Docker Compose, Taskfile for builds, and CI/CD pipelines defined in GitHub workflows.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Frontend Layer"
        DF["Demo Frontend"]:::frontend
        PF["Playground Frontend"]:::frontend
    end

    subgraph "Backend Layer"
        AC["TEN Agent Core"]:::backend
        SC["Server API"]:::backend
        EM["Extensions Modules"]:::extension
        EA["Third-Party APIs (Agora,Deepgram,Elevenlabs,Trulience)"]:::external
        HC["ESP32 Client"]:::hardware
    end

    subgraph "Deployment & CI/CD"
        CI["Containerization & CI/CD (Docker,GitHub Workflows,Taskfile)"]:::container
    end

    %% Data Flow Connections
    DF -->|"REST_calls"| SC
    PF -->|"REST_calls"| SC
    SC -->|"delegates_requests"| AC
    AC -->|"integrates_modules"| EM
    EM -->|"calls_APIs"| EA
    HC -->|"real-time_data"| AC
    CI --> AC
    CI --> SC
    CI --> EM

    %% Click Events
    click AC "https://github.com/ten-framework/ten-agent/blob/main/agents/main.go"
    click EM "https://github.com/ten-framework/ten-agent/tree/main/agents/ten_packages"
    click DF "https://github.com/ten-framework/ten-agent/tree/main/demo"
    click PF "https://github.com/ten-framework/ten-agent/tree/main/playground"
    click SC "https://github.com/ten-framework/ten-agent/tree/main/server"
    click HC "https://github.com/ten-framework/ten-agent/tree/main/esp32-client"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef backend fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef extension fill:#DDA0DD,stroke:#000,stroke-width:2px;
    classDef hardware fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef container fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef external fill:#FFB6C1,stroke:#000,stroke-width:2px;
```
