Youtu-agent: A simple yet powerful agent framework that delivers with open-source models

| 中文版 | 🌟 Performance | 💡 Examples | ✨ Features | 🚀 Getting Started |

Youtu-agent is a flexible, high-performance framework for building, running, and evaluating autonomous agents. Beyond topping the benchmarks, this framework delivers powerful agent capabilities, e.g. data analysis, file processing, and deep research, all with open-source models.

Key highlights:

• Verified performance: Achieved 71.47% on WebWalkerQA (pass@1) and 72.8% on GAIA (text-only subset, pass@1), using purely DeepSeek-V3 series models (without Claude or GPT), establishing a strong open-source starting point.
• Open-source friendly & cost-aware: Optimized for accessible, low-cost deployment without reliance on closed models.
• Practical use cases: Out-of-the-box support for tasks like CSV analysis, literature review, personal file organization, and podcast and video generation (coming soon).
• Flexible architecture: Built on openai-agents, with extensible support for diverse model APIs (form DeepSeek to gpt-oss), tool integrations, and framework implementations.
• Automation & simplicity: YAML-based configs, auto agent generation, and streamlined setup reduce manual overhead.

🗞️ News

• 🎁 [2025-09-02] To help you build chat applications with Youtu-agent more easily, Tencent Cloud International is offering a limited-time free benefit for users who access the DeepSeek API service for the first time: a total of 3 million tokens of DeepSeek model usage quota. Promotion Period: September 1, 2025 – October 31, 2025. Feel free to try it! If you're further interested in the Agent business direction and seeking an enterprise solution, feel free to use Tencent Cloud Agent Development Platform (ADP)!
• 📺 [2025-08-28] We made a live sharing updates about DeepSeek-V3.1 and how to use it in the Youtu-agent framework. We share the used documentations.

🌟 Benchmark Performance

Youtu-agent is built on open-source models and lightweight tools, demonstrating strong results on challenging deep search and tool use benchmarks.

• WebWalkerQA: Achieved 60.71% accuracy with DeepSeek-V3-0324， using new released DeepSeek-V3.1 can further improve to 71.47%, setting a new SOTA performance.
• GAIA: Achieved 72.8% pass@1 on the text-only validation subset using DeepSeek-V3-0324 (including models used within tools). We are actively extending evaluation to the full GAIA benchmark with multimodal tools, and will release the trajectories in the near future. Stay tuned! ✨

💡 Examples

Click on the images to view detailed videos.

Data Analysis Analyzes a CSV file and generates an HTML report.	File Management Renames and categorizes local files for the user.
case_da.mov	case_fs.mov
Wide Research Gathers extensive information to generate a comprehensive report, replicating the functionality of Manus.	Paper Analysis Parses a given paper, performs analysis, and compiles related literature to produce a final result.
case_wide.mov	case_paper.mov

🤖 Automatic Agent Generation

A standout feature of Youtu-agent is its ability to automatically generate agent configurations. In other frameworks, defining a task-specific agent often requires writing code or carefully crafting prompts. In contrast, Youtu-agent uses simple YAML-based configs, which enables streamlined automation: a built-in "meta-agent" chats with you to capture requirements, then generates and saves the config automatically.

# Interactively clarify your requirements and auto-generate a config
python scripts/gen_simple_agent.py

# Run the generated config
python scripts/cli_chat.py --stream --config generated/xxx

Automatic Agent Generation Interactively clarify your requirements, automatically generate the agent configuration, and run it right away.

gen-1.mp4

For more detailed examples and advanced use-cases, please refer to the examples directory and our comprehensive documentation at docs/examples.md.

✨ Features

Design Philosophy

• Minimal design: We try to keep the framework simple and easy to use, avoiding unnecessary overhead.
• Modular & configurable: Flexible customization and easy integration of new components.
• Open-source model support & low-cost: Promotes accessibility and cost-effectiveness for various applications.

Core Features

• Built on openai-agents: Leveraging the foundation of openai-agents SDK, our framework inherits streaming, tracing, and agent-loop capabilities, ensuring compatibility with both responses and chat.completions APIs for seamless adaptation to diverse models like gpt-oss.
• Fully asynchronous: Enables high-performance and efficient execution, especially beneficial for evaluating benchmarks.
• Tracing & analysis system: Beyond OTEL, our DBTracingProcessor system provides in-depth analysis of tool calls and agent trajectories. (will be released soon)

Automation

• YAML based configuration: Structured and easily manageable agent configurations.
• Automatic agent generation: Based on user requirements, agent configurations can be automatically generated.
• Tool generation & optimization: Tool evaluation and automated optimization, and customized tool generation will be supported in the future.

Use Cases

• Deep / Wide research: Covers common search-oriented tasks.
• Webpage generation: Examples include generating web pages based on specific inputs.
• Trajectory collection: Supports data collection for training and research purposes.

🤔 Why Choose Youtu-agent?

Youtu-agent is designed to provide significant value to different user groups:

For Agents Researchers & LLM Trainers

• A simple yet powerful baseline that is stronger than basic ReAct, serving as an excellent starting point for model training and ablation studies.
• One-click evaluation scripts to streamline the experimental process and ensure consistent benchmarking.

For Agent Application Developers

• A proven and portable scaffolding for building real-world agent applications.
• Ease of Use: Get started quickly with simple scripts and a rich set of built-in toolkits.
• Modular Design: Key components like Environment and ContextManager are encapsulated yet highly customizable.

For AI & Agent Enthusiasts

• Practical Use Cases: The /examples directory includes tasks like deep research report generation, data analysis, and personal file organization.
• Simplicity & Debuggability: A rich toolset and visual tracing tools make development and debugging intuitive and straightforward.

🧩 Core Concepts

• Agent: An LLM configured with specific prompts, tools, and an environment.
• Toolkit: An encapsulated set of tools that an agent can use.
• Environment: The world in which the agent operates (e.g., a browser, a shell).
• ContextManager: A configurable module for managing the agent's context window.
• Benchmark: An encapsulated workflow for a specific dataset, including preprocessing, rollout, and judging logic.

For more design and implementation details, please refer to our technical documentation.

🚀 Getting Started

Youtu-agent provides complete code and examples to help you get started quickly. Follow the steps below to run your first agent, or refer to docker/README.md for a streamlined Docker-based setup with interactive frontend.

Setup

Clone the repository and install dependencies:

git clone https://github.com/TencentCloudADP/Youtu-agent.git
cd Youtu-agent
uv sync  # or, `make sync`
source ./.venv/bin/activate
cp .env.example .env  # config necessary keys...

Note

The project requires Python 3.12+. We recommend using uv for dependency management.

Quickstart

Youtu-agent ships with built-in configurations. For example, the default config (configs/agents/default.yaml) defines a simple agent equipped with a search tool:

defaults:
  - /model/base
  - /tools/search@toolkits.search
  - _self_

agent:
  name: simple-tool-agent
  instructions: "You are a helpful assistant that can search the web."

You can launch an interactive CLI chatbot with this agent by running:

python scripts/cli_chat.py --stream --config default

📖 More details: Quickstart Documentation

Explore examples

The repository provides multiple ready-to-use examples. For instance, you can generate an SVG infographic based on a research topic:

python examples/svg_generator/main_web.py

Note

To use the WebUI, you need to install the utu_agent_ui package. Refer to documentation for more details.

Given a research topic, the agent will automatically search the web, collect relevant information, and output an SVG visualization.

📖 Learn more: Examples Documentation

Run evaluations

Youtu-agent also supports benchmarking on standard datasets. For example, to evaluate on WebWalkerQA:

# prepare dataset
python scripts/data/process_web_walker_qa.py
# run evaluation with config ww.yaml with your custom exp_id
python scripts/run_eval.py --config_name ww --exp_id <your_exp_id> --dataset WebWalkerQA --concurrency 5

Results are stored and can be further analyzed in the evaluation platform.

📖 Learn more: Evaluation Documentation

🙏 Acknowledgements

This project builds upon the excellent work of several open-source projects:

• openai-agents
• mkdocs-material
• model-context-protocol

📚 Citation

If you find this work useful, please consider citing:

@misc{youtu-agent-2025,
  title={Youtu-agent: A Simple yet Powerful Agent Framework},
  author={Tencent Youtu Lab},
  year={2025},
  publisher = {GitHub},
  journal = {GitHub repository},
  howpublished = {\url{https://github.com/TencentCloudADP/Youtu-agent}},
}

⭐ Star History