# tencentcloudadp/youtu-agent architecture

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

- Interactive diagram: https://gitdiagram.com/tencentcloudadp/youtu-agent
- Repository: https://github.com/tencentcloudadp/youtu-agent

## Overview

##### Project type and purpose
- This is a full-stack, open-source “agent framework” (called **Youtu-Agent**) written in Python, with two separate frontends (a Next.js app for evaluation analysis, and a generic web/Gradio UI for interactive agents).
- Its core purpose is to build, run, and evaluate autonomous LLM-powered agents with configurable toolkits, environments, and tracing, all driven by YAML configs.

##### File structure
- **Core library (utu/)**: Python packages for agents (`utu/agents`), configs (`utu/config`), contexts (`utu/context`), environments (`utu/env`), evaluation pipelines (`utu/eval`), tools (`utu/tools`), tracing (`utu/tracing`), UI helper (`utu/ui`), and utilities (`utu/utils`).
- **Scripts**: CLI entrypoints (`scripts/cli_chat.py`), data preparation, evaluation runners, agent generators.
- **Configs**: YAML definitions for agents (`configs/agents`), benchmarks (`configs/eval`).
- **Examples**: Ready-to-run demos illustrating common use cases (data analysis, file management, research, SVG generation).
- **Frontends**:
- `frontend/exp_analysis`: Next.js-based dashboard for viewing evaluation results.
- **Tests**, **CI workflows**, **Docker** files, and **documentation** under `docs/`.

##### Insights from the README
- Core technical stack: Python 3.12+, asynchronous (asyncio), SQLModel/SQLite or external DB, OpenTelemetry + custom DB tracer, openai-agents SDK, Next.js + Drizzle ORM for the evaluation UI, Vite + React for the chat UI.
- Key workflows:
- **Agent runtime** (CLI or web) → loads YAML config → instantiates Agent/ContextManager/Environment/Toolkit → calls LLM API → triggers tool invocations → possibly interacts with file system or browser/env → streams responses back to UI.

a. **Main components**
1. **Agent Core (Python library)**
- Config Loader & Meta-Agent
- Agent class (loop + streaming)
- ContextManager
- Environment implementations (shell, browser, mcp client)
- Toolkits (search, file, Python executor, audio, image, etc.)
- Tracing subsystem (OTEL + DBTracingProcessor)
2. **Persistence & Tracing**
- SQLModel-backed DB for evaluation datapoints, tool cache, trace logs
3. **CLI interface**
- `scripts/cli_chat.py`, `gen_simple_agent.py`, `run_eval.py`
4. **Web UIs**
- **Agent Chat UI** (`utu/ui/frontend`)
- WebSocket service → Python back end
- **Evaluation Dashboard** (`frontend/exp_analysis`)
- Next.js API routes → Drizzle-managed DB connection
- Pages for experiments list, per-run stats, traces
5. **External Services**
- LLM providers (DeepSeek, OpenAI-compatible endpoints)
- Third-party tool APIs (Serper, Jina, file storage)

b. **Relationships & interactions**
- **User** interacts via CLI or Web UI → sends requests to Python back end.
- **Back end** loads **agent config** → orchestrates **LLM calls** and **toolkits** → updates **ContextManager** → emits events.
- **Tracing** captures each tool/LLM call → stores in **DB**.
- **Evaluation runner** scripts push read/write to the same DB.
- **Evaluation UI** queries DB via Next.js API → renders graphs, tables.

c. **Architectural patterns & design principles**
- **Modular architecture**: clear separation of agent logic, environment, tools, context, and tracing.
- **Config-driven**: YAML files define agents, models, tools without code changes.
- **Asynchronous pipelines**: concurrent agent rollouts, non-blocking I/O.
- **Adapter pattern** for external LLMs & tools, enabling swap-in of different providers.
- **Client-server** split between back end (Python) and two front ends (Next.js, React/Vite).

d. **Key technologies**
- Python asyncio, SQLModel, FastAPI-style API routes (Next.js), Drizzle ORM, Next.js 13+, Vite, React, WebSocket.
- Docker for containerization.
- OpenTelemetry and custom DB tracer for observability.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User
    User["User"]:::user

    %% Clients
    subgraph "Clients"
        CLI["CLI Interfaces & Scripts"]:::cli
        ChatUI["Agent Chat UI"]:::frontend
        EvalUI["Evaluation Dashboard"]:::frontend
    end

    %% Python Backend
    subgraph "Python Backend"
        subgraph "Config & Meta"
            ConfigLoader["Config Loader (YAML)"]:::core
            MetaAgent["Meta-Agent Generator"]:::core
        end
        subgraph "Agent Core"
            BaseAgent["BaseAgent"]:::core
            LLMAgent["LLMAgent"]:::core
            SimpleAgent["SimpleAgent"]:::core
            OrchestraAgent["OrchestraAgent"]:::core
        end
        subgraph "Context Manager"
            BaseCtx["BaseContextManager"]:::core
            EnvCtx["EnvContextManager"]:::core
        end
        subgraph "Environments"
            BaseEnv["BaseEnv"]:::core
            BrowserEnv["BrowserEnv"]:::core
            ShellEnv["ShellLocalEnv"]:::core
            DockerMgr["DockerManager"]:::core
            MCPClient["MCPClient"]:::core
        end
        subgraph "Toolkits"
            ArxivTool["ArxivToolkit"]:::core
            AudioTool["AudioToolkit"]:::core
            BashTool["BashToolkit"]:::core
            PythonExec["PythonExecutorToolkit"]:::core
            SearchTool["SearchToolkit"]:::core
            ImageTool["ImageToolkit"]:::core
            TabularTool["TabularDataToolkit"]:::core
        end
        subgraph "Tracing"
            OTELInstr["OTelAgentsInstrumentor"]:::core
            OTELProc["OTelAgentsProcessor"]:::core
            DBTracer["DBTracer"]:::core
        end
        subgraph "Utilities"
            Utils["Utilities & Helpers"]:::core
        end
    end

    %% Persistence
    DB["SQLite/SQLModel DB"]:::persistence

    %% External
    subgraph "External Services"
        LLM["LLM Providers"]:::external
        SearchAPI["Serper/Jina"]:::external
        FileStorage["File Storage"]:::external
    end

    %% Connections
    User --> CLI
    User --> ChatUI
    User --> EvalUI

    CLI --> ConfigLoader
    ChatUI -->|"WebSocket"| ConfigLoader
    EvalUI -->|"Next.js API"| DB

    ConfigLoader --> BaseAgent
    ConfigLoader --> LLMAgent
    MetaAgent --> SimpleAgent
    BaseAgent --> ContextManager
    LLMAgent --> ContextManager
    SimpleAgent --> ContextManager
    OrchestraAgent --> ContextManager

    ContextManager --> BaseCtx
    ContextManager --> EnvCtx

    BaseAgent --> OTELInstr
    OTELInstr --> OTELProc
    OTELProc --> DBTracer
    DBTracer --> DB

    BaseAgent --> LLM
    BaseAgent --> Toolkits

    Toolkits --> ArxivTool
    Toolkits --> AudioTool
    Toolkits --> BashTool
    Toolkits --> PythonExec
    Toolkits --> SearchTool
    Toolkits --> ImageTool
    Toolkits --> TabularTool

    ArxivTool --> SearchAPI
    AudioTool --> FileStorage

    %% Click Events
    click BaseAgent "https://github.com/tencentcloudadp/youtu-agent/blob/main/utu/agents/base_agent.py"
    click LLMAgent "https://github.com/tencentcloudadp/youtu-agent/blob/main/utu/agents/llm_agent.py"
    click SimpleAgent "https://github.com/tencentcloudadp/youtu-agent/blob/main/utu/agents/simple_agent.py"
    click OrchestraAgent "https://github.com/tencentcloudadp/youtu-agent/blob/main/utu/agents/orchestra_agent.py"
    click ConfigLoader "https://github.com/tencentcloudadp/youtu-agent/blob/main/utu/config/loader.py"
    click MetaAgent "https://github.com/tencentcloudadp/youtu-agent/blob/main/utu/meta/simple_agent_generator.py"
    click BaseCtx "https://github.com/tencentcloudadp/youtu-agent/blob/main/utu/context/base_context_manager.py"
    click EnvCtx "https://github.com/tencentcloudadp/youtu-agent/blob/main/utu/context/env_context_manager.py"
    click BaseEnv "https://github.com/tencentcloudadp/youtu-agent/blob/main/utu/env/base_env.py"
    click BrowserEnv "https://github.com/tencentcloudadp/youtu-agent/blob/main/utu/env/browser_env.py"
    click ShellEnv "https://github.com/tencentcloudadp/youtu-agent/blob/main/utu/env/shell_local_env.py"
    click DockerMgr "https://github.com/tencentcloudadp/youtu-agent/blob/main/utu/env/utils/docker_manager.py"
    click MCPClient "https://github.com/tencentcloudadp/youtu-agent/blob/main/utu/env/utils/mcp_client.py"
    click ArxivTool "https://github.com/tencentcloudadp/youtu-agent/blob/main/utu/tools/arxiv_toolkit.py"
    click AudioTool "https://github.com/tencentcloudadp/youtu-agent/blob/main/utu/tools/audio_toolkit.py"
    click BashTool "https://github.com/tencentcloudadp/youtu-agent/blob/main/utu/tools/bash_toolkit.py"
    click PythonExec "https://github.com/tencentcloudadp/youtu-agent/blob/main/utu/tools/python_executor_toolkit.py"
    click SearchTool "https://github.com/tencentcloudadp/youtu-agent/blob/main/utu/tools/search_toolkit.py"
    click ImageTool "https://github.com/tencentcloudadp/youtu-agent/blob/main/utu/tools/image_toolkit.py"
    click TabularTool "https://github.com/tencentcloudadp/youtu-agent/blob/main/utu/tools/tabular_data_toolkit.py"
    click OTELInstr "https://github.com/tencentcloudadp/youtu-agent/blob/main/utu/tracing/otel_agents_instrumentor.py"
    click OTELProc "https://github.com/tencentcloudadp/youtu-agent/blob/main/utu/tracing/otel_agents_processor.py"
    click DBTracer "https://github.com/tencentcloudadp/youtu-agent/blob/main/utu/tracing/db_tracer.py"
    click ChatUI "https://github.com/tencentcloudadp/youtu-agent/tree/main/utu/ui/frontend"
    click EvalUI "https://github.com/tencentcloudadp/youtu-agent/tree/main/frontend/exp_analysis"

    %% Styles
    classDef user fill:#f0f0f0,stroke:#333,stroke-width:1px
    classDef cli fill:#fff2cc,stroke:#e6b800,stroke-width:1px
    classDef frontend fill:#d1e7dd,stroke:#0f5132,stroke-width:1px
    classDef core fill:#cfe2ff,stroke:#084298,stroke-width:1px
    classDef persistence fill:#ffe5d9,stroke:#b02a2a,stroke-width:1px
    classDef external fill:#e2e3e5,stroke:#6c757d,stroke-width:1px
```
