Youtu-agent：操作电脑自动完成任务的AI智能体框架

Youtu-agent是腾讯优图实验室开发的一款功能强大且设计简洁的AI智能体框架。 它专门为构建、运行和评估自主AI智能体而设计，其核心特色是全面拥抱开源模型，不依赖任何闭源大模型即可实现优异的性能。 该框架经过了严格的基准测试验证，在使用开源的DeepSeek-V3系列模型的情况下，于WebWalkerQA和GAIA等权威测评中取得了领先的成绩。 Youtu-agent具备很高的灵活性和可扩展性，架构基于openai-agents，并支持异步执行，能高效处理复杂任务。 为了降低使用门槛，框架采用YAML文件进行配置，并独创了“元智能体（meta-agent）”功能，可以通过与用户对话的方式自动生成智能体配置，极大地简化了开发流程。 目前，该框架已内置支持数据分析、文件管理、深度研究报告生成和论文分析等多种实用功能场景。

功能列表

• 优异的性能表现: 在主流的智能体基准测试（如WebWalkerQA和GAIA）中，仅使用开源模型（如DeepSeek-V3系列）就取得了业界领先的准确率。
• 全面的开源支持: 框架为开源模型进行了深度优化，旨在降低开发与部署成本，让用户无需依赖昂贵的闭源模型即可构建强大的智能体。
• 内置实用场景: 提供开箱即用的功能，可直接用于处理CSV数据分析、文献回顾、本地文件整理归类、以及深度主题研究等常见任务。
• 灵活的模块化架构: 基于openai-agents构建，核心组件（如环境、工具包、上下文管理器）都支持高度定制和扩展，可以轻松集成新的模型和工具。
• 自动化与简洁性:
  • 使用简单直观的YAML文件来定义和配置智能体，结构清晰且易于管理。
  • 独创的“元智能体”能够通过与用户进行交互式对话，自动捕捉需求并生成配置文件，显著降低了手动编写代码和配置的复杂度。
• 高效的异步执行: 框架完全支持异步操作，能够实现高性能和高效率的任务执行，特别适合于需要并发处理的评估和测试场景。
• 强大的追踪与分析: 内置了超越常规OTEL的DBTracingProcessor系统，可以深度分析智能体的工具调用轨迹，便于调试和优化（即将发布）。

使用帮助

Youtu-agent框架设计简洁，让用户可以快速上手并应用于实际场景中。以下是详细的安装和使用流程。

1. 环境准备与安装

首先，你需要从GitHub克隆项目的代码仓库到本地，并安装所需的依赖库。

第一步：克隆代码仓库
打开终端（命令行工具），执行以下git命令将项目代码下载到本地：

git clone https://github.com/Tencent/Youtu-agent.git

第二步：进入项目目录

cd Youtu-agent

第三步：安装依赖
项目使用pyproject.toml来管理依赖，你可以使用pip工具进行安装。建议在一个新的虚拟环境中安装，以避免与其他项目的依赖冲突。

# 创建并激活虚拟环境（推荐）
python -m venv venv
source venv/bin/activate  # 在Windows上使用 `venv\Scripts\activate`
# 安装项目依赖
pip install .

第四步：配置环境变量
为了让智能体能够调用外部API（例如大模型API或搜索工具API），你需要配置环境变量。项目提供了一个配置模板文件.env.example。你需要复制一份并重命名为.env，然后填入你的API密钥。

cp .env.example .env

之后，使用文本编辑器打开.env文件，填入类似DEEPSEEK_API_KEY等所需的值。

2. 快速上手：运行一个简单的搜索智能体

这个例子将带你运行一个具备网页搜索功能的基础智能体。

第一步：创建智能体配置文件
在configs/agents/目录下创建一个新的YAML文件，例如sample_tool.yaml。这个文件定义了智能体的名称、它的系统指令以及需要加载的工具。

# configs/agents/sample_tool.yaml
defaults:
- /model/base
- /tools/search@toolkits.search # 加载名为'search'的工具包
- _self_
agent:
name: simple-tool-agent
instructions: "你是一个乐于助人的助手，可以在网上搜索信息。"

第二步：编写并运行Python脚本
创建一个Python脚本文件，例如run_agent.py，并写入以下代码。这段代码会加载刚才创建的配置文件，并启动智能体与你进行对话。

import asyncio
from utu.agents import SimpleAgent
async def main():
# 通过指定配置文件名来初始化智能体
async with SimpleAgent(config="sample_tool.yaml") as agent:
# 与智能体进行对话
await agent.chat("今天北京的天气怎么样？")
# 运行主函数
asyncio.run(main())```
在终端中执行此脚本，智能体就会启动，调用搜索工具查询天气信息并给出回答。
```bash
python run_agent.py

3. 核心功能：自动化生成智能体

这是Youtu-agent最具特色的功能之一，它允许你通过与一个“元智能体”对话来自动创建智能体配置，无需手动编写YAML文件。

第一步：启动元智能体脚本
在终端中运行以下命令：

python scripts/gen_simple_agent.py

第二步：与元智能体对话
脚本启动后，它会像一个助手一样开始向你提问，以了解你想要创建的智能体的具体需求，例如：

• 你想让这个智能体做什么？
• 它需要哪些工具（如搜索、文件读写等）？
• 你希望它遵循什么样的行为指令？

第三步：自动生成配置文件
在你回答完问题后，元智能体将自动在generated/目录下生成一个对应的YAML配置文件。

第四步：运行新生成的智能体
你可以直接使用cli_chat.py脚本来运行这个刚刚生成的智能体，体验它的功能。

python scripts/cli_chat.py --stream --config generated/你生成的配置文件名.yaml

4. 进阶使用：运行内置示例

项目在examples/目录中提供了多个可以直接运行的复杂任务示例，例如深度研究。

要运行深度研究智能体，只需执行以下命令：

python -m examples.research.main

这个智能体将会围绕一个特定主题进行深入的在线研究，并最终生成一份综合报告。你可以参考这些示例代码，学习如何构建更复杂的应用。

应用场景

1. 自动化数据分析
   用户可以指令智能体分析一个CSV表格文件。智能体会自动读取数据内容，进行数据洞察和统计分析，并根据分析结果生成一份可视化的HTML格式报告。
2. 个人文件管理
   对于电脑中杂乱的文件，用户可以给智能体下达指令，例如“帮我把所有的项目文档按照年份和项目名称重新命名并分类放到不同的文件夹里”。智能体可以自动执行重命名和移动文件等操作，整理文件系统。
3. 深度课题研究
   当需要对某个陌生领域或具体课题进行深入研究时，可以指令智能体执行此项任务。它会自动上网搜集大量相关资料、阅读并提炼核心信息、筛选和整合内容，最终生成一份逻辑清晰、内容详实的综合性研究报告。
4. 学术论文辅助
   研究人员可以提供一篇或多篇学术论文，指令智能体进行分析。智能体能够解析论文的核心观点、实验方法和结论，并在此基础上自动查找和整理相关的参考文献，帮助研究者快速完成文献综述工作。

QA

1. Youtu-agent是什么？
   它是一个由腾讯优图实验室开发的AI智能体框架，设计目标是让开发者可以方便地使用开源大语言模型来构建、运行和评估能够自主完成任务的AI程序。
2. Youtu-agent和其他智能体框架有什么不同？
   它的主要区别在于对开源模型的专注和优化，致力于提供低成本、高性能的解决方案。 此外，其独特的“元智能体”功能，可以通过对话自动生成智能体配置，极大地简化了开发流程。
3. 它支持哪些大语言模型？
   该框架对以DeepSeek-V3系列为代表的开源模型有很好的支持和性能表现。 同时，其架构兼容openai-agents SDK，可以无缝适应和接入包括gpt-oss在内的多种模型API。
4. 使用Youtu-agent需要编写很多代码吗？
   不需要。对于大多数常见任务，你只需要通过简单的YAML文件进行配置即可。对于更个性化的需求，其“元智能体”功能甚至可以通过对话自动为你生成配置文件，进一步降低了使用门槛。