| 中文版 | 🌟 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.

• 🎁 [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 made a live sharing updates about DeepSeek-V3.1 and how to use it in the Youtu-Agent framework. We share the used documentations.

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! ✨

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.
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.

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.

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

• 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.

• 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)

• 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.

• 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.

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

• 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.

• 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.

• 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.

• 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.

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.

[!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

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

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:

# 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

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.1.5/utu_agent_ui-0.1.5-py3-none-any.whl

# Install the frontend package
uv pip install utu_agent_ui-0.1.5-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

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

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

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

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}},
}