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

| 中文 | 日本語 | 🌟 Performance | 💡 Examples | ✨ Features | 🚀 Getting Started | 📢 Join Community

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-09] We hosted a live sharing the design philosophy and basic usage of Youtu-Agent. [video] [documentation].
• 🎁 [2025-09-02] Tencent Cloud International offers new users of the DeepSeek API 3 million free tokens (Sep 1 – Oct 31, 2025). Try it out for free if you want to use DeepSeek models in Youtu-Agent! For enterprise agent solutions, also check out Agent Development Platform (ADP).
• 📺 [2025-08-28] We hosted a live sharing updates about DeepSeek-V3.1 and how to use it in the Youtu-Agent framework. [video] [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_v2s.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

Note

See the examples directory and documentation for more details.

🤖 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

Note

See documentation for more details.

✨ 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

Source Code Deployment

Note

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

First, make sure Python and uv are installed.

Then clone the repository and sync 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  # NOTE: You should then config the necessary API keys.

After copying the .env.example file, you need to fill in the necessary keys in the .env file, e.g. LLM API keys. For example:

# llm requires OpenAI API format compatibility
# setup your LLM config , ref https://api-docs.deepseek.com/
UTU_LLM_TYPE=chat.completions
UTU_LLM_MODEL=deepseek-chat
UTU_LLM_BASE_URL=https://api.deepseek.com/v1
UTU_LLM_API_KEY=replace-to-your-api-key

Tencent Cloud International offers new users of the DeepSeek API 3 million free tokens (Sep 1 – Oct 31, 2025). Try it out for free. Once you’ve applied, replace the API key in the .env file below:

# llm
# setup your LLM config , ref https://www.tencentcloud.com/document/product/1255/70381
UTU_LLM_TYPE=chat.completions
UTU_LLM_MODEL=deepseek-v3
UTU_LLM_BASE_URL=https://api.lkeap.cloud.tencent.com/v1
UTU_LLM_API_KEY=replace-with-your-api-key

Docker Deployment

Please refer to docker/README.md for a streamlined Docker-based setup with interactive frontend.

Quick Start

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/[email protected]
  - _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:

# NOTE: You need to set `SERPER_API_KEY` and `JINA_API_KEY` in `.env` for web search access.
# (We plan to replace these with free alternatives in the future)
python scripts/cli_chat.py --stream --config default
# To avoid using the search toolkit, you can run:
python scripts/cli_chat.py --stream --config base

📖 More details: Quickstart Documentation

Explore More Examples

The repository provides multiple ready-to-use examples. Some examples require the agent to have internet search capabilities, so you’ll need to configure the tool APIs in the .env file under the tools module:

# tools
# serper api key, ref https://serper.dev/playground
SERPER_API_KEY=<Access the URL in the comments to get the API Key>
# jina api key, ref https://jina.ai/reader
JINA_API_KEY=<Access the URL in the comments to get the API Key>

For example, to enable the agent to automatically search online for information and generate an SVG image on the topic of “DeepSeek V3.1 New Features,” run the following command:

python examples/svg_generator/main.py

If you want to visualize the agent’s runtime status using the web UI, download the frontend package from the Youtu-Agent releases and install it locally:

# Download the frontend package
curl -LO https://github.com/Tencent/Youtu-agent/releases/download/frontend%2Fv0.2.0/utu_agent_ui-0.2.0-py3-none-any.whl

# Install the frontend package
uv pip install utu_agent_ui-0.2.0-py3-none-any.whl

Next, run the web version of the SVG image generation command:

python examples/svg_generator/main_web.py

Once the terminal shows the following message, the deployment is successful. You can access the project by clicking the local link:

Server started at http://127.0.0.1:8848/

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. This script will download and process WebWalkerQA dataset, and save it to DB.
python scripts/data/process_web_walker_qa.py

# Run evaluation with config `ww.yaml` with your custom `exp_id`. We choose the sampled small dataset `WebWalkerQA_15` for quick evaluation.
# NOTE: `JUDGE_LLM_TYPE, JUDGE_LLM_MODEL, JUDGE_LLM_BASE_URL, JUDGE_LLM_API_KEY` should be set in `.env`. Ref `.env.full`.
python scripts/run_eval.py --config_name ww --exp_id <your_exp_id> --dataset WebWalkerQA_15 --concurrency 5

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

📖 Learn more: Evaluation Documentation

📖 Dive Deeper

After getting started, you can learn more about the framework and its capabilities through our full documentation:

• 📖 Full Documentation: Explore the core concepts, architecture, and advanced features.
• 🚀 Quickstart Guide: A detailed guide to get you up and running.
• ❓ FAQ: Find answers to common questions and issues.

🙏 Acknowledgements

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

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

🙌 Contributing

We welcome contributions from the community! If you'd like to help improve Youtu-Agent, please read our Contributing Guidelines to get started.

📚 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