How tencentcloudadp/youtu-agent works
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.