# Youtu-agent
**Repository Path**: cs_sssss/Youtu-agent
## Basic Information
- **Project Name**: Youtu-agent
- **Description**: A simple yet powerful agent framework that delivers with open-source models
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 2
- **Created**: 2025-09-08
- **Last Updated**: 2025-09-08
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# 
Youtu-Agent: 一个简单强大的智能体框架
| English
| 🌟 性能
| 💡 示例
| ✨ 特性
| 🚀 快速开始
|
`Youtu-Agent` 是一个灵活、高性能的框架，用于构建、运行和评估自主智能体。除了在基准测试中名列前茅，该框架还提供了强大的智能体能力，采用开源模型即可实现例如数据分析、文件处理、深度研究等功能。
主要亮点：
- **验证性能**：在 WebWalkerQA 上达到 71.47% 的 pass@1，在 GAIA（纯文本子集）上达到 72.8% 的 pass@1，纯粹使用 `DeepSeek-V3` 系列模型（不使用 Claude 或 GPT），建立了强大的开源起点。
- **开源友好且成本敏感**：针对可访问、低成本部署进行了优化，不依赖封闭模型。
- **实际用例**：开箱即用地支持 CSV 分析、文献综述、个人文件整理以及播客和视频生成等任务。（即将推出）
- **灵活的架构**：基于 [openai-agents](https://github.com/openai/openai-agents-python) 构建，可兼容各种模型 API（从 `DeepSeek` 到 `gpt-oss`）、工具集成和框架实现。
- **自动化与简洁性**：基于 YAML 的配置、自动智能体生成和简化的设置减少了手动开销。
## 🗞️ 新闻
- 🎁 [2025-09-02] [腾讯云国际站](https://www.tencentcloud.com/) 为 DeepSeek API 新用户提供 **300 万免费令牌**（**2025年9月1日 – 2025年10月31日**）。如果想在 `Youtu-Agent` 中使用 DeepSeek 模型，[点击免费试用](https://www.tencentcloud.com/document/product/1255/70381)！如需企业级智能体解决方案，也可查看 [智能体开发平台 ADP](https://adp.tencentcloud.com)。
- 📺 [2025-08-28] 我们围绕新发布的 DeepSeek-V3.1 模型进行了直播分享，并介绍了如何在 `Youtu-Agent` 框架中使用该模型。[点击这里](https://doc.weixin.qq.com/doc/w3_AcMATAZtAPICNvcLaY5FvTOuo7MwF) 获取所用文档。
## 🌟 基准性能
`Youtu-Agent` 基于开源模型和轻量级工具构建，在具有挑战性的深度搜索和工具使用基准测试中表现出色。
- **[WebWalkerQA](https://huggingface.co/datasets/callanwu/WebWalkerQA)**：使用 `DeepSeek-V3-0324` 实现了 60.71% 的准确率，使用新发布的 `DeepSeek-V3.1` 可进一步提升至 71.47%，创造了新的 SOTA 性能。
- **[GAIA](https://gaia-benchmark-leaderboard.hf.space/)**：使用 `DeepSeek-V3-0324`（包括工具中使用的模型）在[纯文本验证子集](https://github.com/sunnynexus/WebThinker?tab=readme-ov-file#benchmarks)上实现了 72.8% 的 pass@1。我们正在积极扩展对带有多模态工具的完整 GAIA 基准的评估，将在近期放出完整轨迹，敬请关注！✨
## 💡 使用示例
数据分析
分析 CSV 文件并生成 HTML 报告。
|
文件管理
为用户重命名和分类本地文件。
|
广度研究
收集大量信息以生成综合报告，复刻 Manus 的功能。
|
论文分析
解析给定论文，进行分析，并整理相关文献以得出最终结果。
|
### 🤖 自动智能体生成
`Youtu-Agent`的突出优势在于其**自动化生成智能体及其配置**的能力。在其他框架中，定义特定任务的智能体通常需要编写代码或是精心设计提示词，而`Youtu-Agent`采用基于 YAML 的简洁配置方案，实现了高效自动化：内置的“元智能体”与用户对话并捕获需求，然后自动生成并保存配置。
```bash
# 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
```
自动智能体生成
交互式对话的方式捕获需求，自动生成agent配置，并立即运行。
|
更详细的示例和高级用例，请参阅 [`examples`](./examples) 目录和我们的文档 [`docs/examples.md`](./docs/examples.md)。
## ✨ 特性
### 设计理念
- 极简设计：这确保了框架的精简，避免了不必要的开销。
- 模块化与可配置：这允许灵活的定制和新组件的轻松集成。
- 开源模型支持与低成本：这促进了各种应用的可访问性和成本效益。
### 核心功能
- 基于openai-agents构建：利用 [openai-agents](https://github.com/openai/openai-agents-python) SDK 作为基础，我们的框架继承了 streaming、tracing 和 agent-loop 能力，确保了与 `responses` 和 `chat.completions` API 的兼容性，无缝适应 [gpt-oss](https://github.com/openai/gpt-oss) 等多样化模型。
- 完全异步：这实现了高性能和高效执行，尤其有利于高效的评估。
- 追踪与分析系统：除了 OTEL，我们的 `DBTracingProcessor` 系统提供了对工具调用和智能体轨迹的深入分析。（即将发布）
### 自动化
- 基于 YAML 的配置：这允许结构化且易于管理的智能体配置。
- 自动智能体生成：根据用户需求，可以自动生成智能体配置。
- 工具生成与优化：工具评估和自动化优化，定制化工具生成的能力将在未来得到支持。
### 用例
- 深度/广度研究：涵盖常见的面向搜索的任务。
- 网页生成：示例包括根据特定输入生成网页。
- 轨迹收集：支持用于训练和研究目的的数据收集。
## 🤔 为何选择 Youtu-Agent？
`Youtu-Agent` 旨在为不同的用户群体提供价值：
### 对于智能体研究人员和大型语言模型训练师
- 一个**简单而强大的基线**，比基本的 ReAct 更强大，可作为模型训练和消融研究的绝佳起点。
- **一键评估脚本**用以简化实验过程，并确保一致的基准测试。
### 对于智能体应用开发者
- 一个**经过验证且可移植的脚手架**，用于构建真实的智能体应用程序。
- **易于使用**：通过简单的脚本和丰富的内置工具包快速上手。
- **模块化设计**：`Environment` 和 `ContextManager` 等关键组件被封装，但高度可定制。
### 对于人工智能和智能体爱好者
- **实际用例**：`/examples` 目录包含深度研究报告生成、数据分析和个人文件整理等任务。
- **简单性与可调试性**：丰富的工具集和可视化追踪工具使开发和调试直观而直接。
## 🧩 核心概念
- **智能体（Agent）**：一个配置了提示词、工具和环境的大语言模型。
- **工具包（Toolkit）**：智能体可以使用的封装工具集。
- **环境（Environment）**：智能体操作的世界（例如，浏览器、shell）。
- **上下文管理器（ContextManager）**：一个可配置模块，用于管理智能体的上下文窗口。
- **基准（Benchmark）**：一个针对特定数据集的封装工作流，包括预处理、执行和判断逻辑。
更多的设计与实现细节，请参阅我们的[在线文档](https://tencentcloudadp.github.io/youtu-agent/)。
## 🚀 快速上手
Youtu-Agent 提供了完整的代码与示例，帮助你快速开始使用。按照以下步骤即可运行你的第一个智能体，或者参考 [`docker/README.md`](./docker/README.md) 使用Docker快速运行一个带交互网页的样例.
### 环境准备
克隆仓库并安装依赖：
> [!NOTE]
> 本项目使用 **Python 3.12+**。推荐使用 [uv](https://github.com/astral-sh/uv) 进行依赖管理。
首先请确保已在环境安装 Python 和 uv，然后参考以下步骤克隆本项目并同步项目依赖。
```bash
git clone https://github.com/TencentCloudADP/youtu-agent.git
cd youtu-agent
uv sync
source ./.venv/bin/activate
cp .env.example .env # NOTE: 你需要配置相关环境变量!
```
> [!NOTE]
> 请配置 `.env` 文件中的相关环境变量，例如 LLM API keys。
### 快速开始
Youtu-Agent 内置了配置文件。例如，默认配置文件 (`configs/agents/default.yaml`) 定义了一个带有搜索工具的简单 Agent：
```yaml
defaults:
- /model/base
- /tools/search@toolkits.search
- _self_
agent:
name: simple-tool-agent
instructions: "You are a helpful assistant that can search the web."
```
你可以通过以下命令启动交互式 CLI 聊天机器人：
```bash
# NOTE: 你需要在 .env 中配置 `SERPER_API_KEY` 和 `JINA_API_KEY` (我们计划在未来替换为免费工具)
python scripts/cli_chat.py --stream --config default
# 如果你不想使用搜索工具，可以运行
python scripts/cli_chat.py --stream --config base
```
📖 更多内容请参考：[快速开始文档](https://tencentcloudadp.github.io/youtu-agent/quickstart)
### 示例探索
本仓库提供了多个可直接运行的示例。例如，你可以基于某个研究主题自动生成一张 **SVG 信息图**：
```bash
python examples/svg_generator/main_web.py
```
> [!NOTE]
> 要使用 WebUI，你需要安装 `utu_agent_ui` 包。参考 [文档](https://tencentcloudadp.github.io/youtu-agent/frontend/#installation)。
给定一个研究主题后，Agent 会自动执行网络搜索，收集相关信息，并输出一张 SVG 可视化图。
📖 更多示例请参考：[示例文档](https://tencentcloudadp.github.io/youtu-agent/examples)
### 运行评测
Youtu-agent 还支持在标准数据集上进行基准测试。例如，在 **WebWalkerQA** 上运行评测：
```bash
# 数据集预处理. 该脚本会下载并处理 WebWalkerQA 数据集，然后保存到数据库中。
python scripts/data/process_web_walker_qa.py
# 使用配置 ww.yaml 运行评测. 我们选择采样小数据集 WebWalkerQA_15 用于快速评测。
# NOTE: 需要在 `.env` 中配置 `JUDGE_LLM_TYPE, JUDGE_LLM_MODEL, JUDGE_LLM_BASE_URL, JUDGE_LLM_API_KEY`，参考 `.env.full`。
python scripts/run_eval.py --config_name ww --exp_id --dataset WebWalkerQA_15 --concurrency 5
```
结果会保存到本地，并可在分析平台中进一步查看。详见 [评测分析](./frontend/exp_analysis/README.md)。
📖 更多内容请参考：[评测文档](https://tencentcloudadp.github.io/youtu-agent/eval)
## 🙏 致谢
本项目基于以下优秀开源项目：
- [openai-agents](https://github.com/openai/openai-agents-python)
- [mkdocs-material](https://github.com/squidfunk/mkdocs-material)
- [model-context-protocol](https://github.com/modelcontextprotocol/python-sdk)
## 📚 引用
如果您觉得这项工作有帮助，请考虑引用：
```bibtex
@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
 
