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-08-28] We made a live sharing updates about DeepSeek-V3.1 and how to apply it in the Youtu-agent framework. Here is the documentation.

🌟 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:

Setup

Clone the repository and install dependencies:

git clone https://github.com/Tencent/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/Tencent/Youtu-agent}},
}

⭐ Star History