快速开始

本指南将引导你完成项目设置、运行第一个智能体和执行评估。

安装与设置

首先，克隆仓库并设置 Python 环境。

# 克隆项目仓库
git clone https://github.com/TencentCloudADP/youtu-agent.git
cd youtu-agent

# 我们使用 `uv` 来管理虚拟环境和依赖
# 创建虚拟环境
uv venv

# 激活环境
source .venv/bin/activate

# 安装所有依赖，包括开发工具
uv sync --group dev

# 从示例创建你的环境配置文件
cp .env.example .env

创建 .env 文件后，你必须编辑它以添加必要的 API 密钥（例如，UTU_LLM_API_KEY、SERPER_API_KEY 等）。

运行智能体

你可以直接从命令行使用 cli_chat.py 脚本与智能体交互。

简单智能体

运行由配置文件定义的简单智能体。例如，运行一个具有搜索功能的智能体：

# python scripts/cli_chat.py --help
python scripts/cli_chat.py --config_name simple/search_agent.yaml

管弦乐队智能体

通过指定其配置文件运行多智能体（计划 - 执行）管弦乐队智能体：

python examples/svg_generator/main.py

你也可以为智能体运行一个 Web UI：

python examples/svg_generator/main_web.py

更多详情请参见前端。

运行评估

该框架包含一个强大的评估工具来对智能体性能进行基准测试。

运行完整实验

此命令运行从智能体部署到判断的完整评估。

python scripts/run_eval.py --config_name <your_eval_config> --exp_id <your_exp_id> --dataset WebWalkerQA --concurrency 5

重新判断现有结果

如果你已经运行了部署阶段，只想重新运行判断阶段，请使用此脚本：

python scripts/run_eval.py --config_name <your_eval_config> --exp_id <your_exp_id> --dataset WebWalkerQA --step judge

导出实验数据

你也可以从数据库中导出特定实验的轨迹和结果：

python scripts/db/dump_db.py --exp_id "<your_exp_id>"

高级设置

数据库配置

评估框架使用 SQL 数据库（默认为 SQLite）来存储数据集和实验结果。要使用不同的数据库（例如 PostgreSQL），请设置 UTU_DB_URL 环境变量：

UTU_DB_URL="postgresql://user:password@host:port/database"

跟踪

我们使用 Phoenix 作为默认的跟踪服务来观察智能体行为。要启用它，请设置以下环境变量： - PHOENIX_ENDPOINT - PHOENIX_BASE_URL - PHOENIX_PROJECT_NAME

该框架还支持与 openai-agents 库兼容的任何跟踪服务。更多选项请参见官方跟踪处理器列表。

自定义智能体

创建配置文件

# configs/agents/sample_tool.yaml
defaults:
  - /model/base
  - /tools/search@toolkits.search # 加载 'search' 工具包
  - _self_

agent:
    name: simple-tool-agent
    instructions: "你是一个可以搜索网络的有用助手。"

编写和运行 Python 脚本

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

下一步

探索示例：查看 /examples 目录以获取更多详细用例和高级脚本。
深入了解评估：通过阅读评估框架文档了解更多关于评估框架的工作原理。