### Install Project Dependencies

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/docs/quickstart_beginner.md

Installs all project dependencies, including development tools, using the UV package manager. This ensures all necessary libraries are available for the project.

```shell
# Install all dependencies, including development tools
uv sync --group dev
```

--------------------------------

### Install and Setup YouTu Agent Project

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/docs/quickstart.md

This snippet demonstrates the commands to clone the project repository, set up a Python virtual environment using `uv`, install dependencies, and copy the example environment configuration file. It's essential for initial project setup.

```sh
# Clone the project repository
git clone https://github.com/TencentCloudADP/youtu-agent.git
cd youtu-agent

# We use `uv` to manage the virtual environment and dependencies
# Create the virtual environment
uv venv

# Activate the environment
source .venv/bin/activate

# Install all dependencies, including development tools
uv sync --group dev

# Create your environment configuration file from the example
cp .env.example .env
```

--------------------------------

### Configure Environment Variables

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/docs/quickstart_beginner.md

Copies the example environment file and instructs the user to edit it to add necessary API keys for LLM and optional tools like Serper and Jina.

```shell
# Copy environment variable template file
cp .env.example .env

# Use a text editor to open the configuration file
# You can use nano, vim, or any editor you prefer
nano .env
```

--------------------------------

### Example .env File Configuration

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/docs/quickstart_beginner.md

Shows an example of the `.env` file content, illustrating where to input API keys for DeepSeek (LLM) and optional keys for Serper and Jina. It also shows alternative configurations for DeepSeek on Tencent Cloud.

```ini
# LLM Configuration - **Required**
# We use DeepSeek as an example LLM provider.
UTU_LLM_TYPE=chat.completions
UTU_LLM_MODEL=deepseek-chat
UTU_LLM_BASE_URL=https://api.deepseek.com/v1
UTU_LLM_API_KEY=[DeepSeek_API_key]
# Or use the DeepSeek equivalent on Tencent Cloud
# 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=[DeepSeek_API_key]

# Tools Configuration - Optional
SERPER_API_KEY=[Serper_API_key]
JINA_API_KEY=[Jina_API_key]
```

--------------------------------

### Clone Youtu-agent Project and Navigate

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/docs/quickstart_beginner.md

Clones the Youtu-agent project repository from GitHub and navigates into the project directory. This is the initial step to get the project code locally.

```shell
# Clone the project locally
git clone https://github.com/TencentCloudADP/youtu-agent.git

# Enter the project directory
cd youtu-agent
```

--------------------------------

### Verify UV Installation

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/docs/quickstart_beginner.md

Checks if the UV package manager has been installed successfully by displaying its version. A successful output indicates that UV is ready to be used.

```bash
uv --version
```

--------------------------------

### Install UV Package Manager

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/docs/quickstart_beginner.md

Installs the UV package manager using different methods suitable for various operating systems and environments. It includes installation via a script for Linux/macOS, PowerShell for Windows, and pip/pipx.

```shell
# Install UV on Linux/macOS
curl -LsSf https://astral.sh/uv/install.sh | sh
```

```powershell
# On Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```

```shell
pip install uv
```

```shell
# Or pipx
pipx install uv
```

--------------------------------

### Running WebUI Example Script (Bash)

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/docs/frontend.md

Shows how to execute an example script (`main_web.py`) to start the WebUI. This command assumes you are in the project's root directory and have the necessary example files.

```bash
python examples/data_analysis/main_web.py
```

--------------------------------

### Copy Example .env File

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/docs/docker.md

Copies the example environment configuration file for Docker. This file should be renamed to `.env` and customized with your API keys and settings.

```bash
cp .env.docker.example .env
```

--------------------------------

### Create and Activate Virtual Environment with UV

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/docs/quickstart_beginner.md

Creates a virtual environment named '.venv' using UV and then activates it. Activating the environment isolates project dependencies.

```shell
# Create virtual environment
uv venv

# Activate virtual environment
# Linux/macOS:
source .venv/bin/activate

# Windows:
# .venv\Scripts\activate
```

--------------------------------

### Configure Environment and Install Dependencies (Bash)

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/frontend/exp_analysis/README.md

This snippet details the initial setup for the exp_analysis frontend. It includes copying an environment file, sourcing it, and installing necessary npm packages using 'npm install --legacy-peer-deps' to handle potential peer dependency conflicts, particularly with react-json-view.

```bash
cd frontend/exp_analysis
cp .env.example .env  # config necessary keys...
source .env
npm install next
npm install --legacy-peer-deps
```

--------------------------------

### Run Full Evaluation Experiment

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/docs/quickstart_beginner.md

Initiates a comprehensive evaluation experiment for agent performance, encompassing agent rollout and judgment phases. Requires specifying configuration, experiment ID, dataset, and concurrency level.

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

--------------------------------

### Launch Youtu-agent with Interactive Shell via Docker

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/docs/docker.md

Starts the Youtu-agent Docker container and provides interactive bash shell access. This allows for running custom configurations or examples, and requires mounting a local .env file.

```bash
docker run -it \
    -p 8848:8848 \
    -v "/path/to/your/.env:/youtu-agent/.env" \
    youtu-agent \
    bash
```

--------------------------------

### Run SVG Generator Orchestra Example

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/docs/quickstart_beginner.md

Launches an orchestra agent designed to generate SVG graphics code directly in the terminal. This demonstrates a multi-agent (Plan-and-Execute) setup. An alternative command is provided to run a web UI for the same agent.

```bash
python examples/svg_generator/main.py
python examples/svg_generator/main_web.py
```

--------------------------------

### Setup Development Environment for uTu-agent

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/CONTRIBUTING.md

Installs project dependencies and sets up pre-commit hooks for code quality checks. It's recommended to run these commands to prepare your local environment for development.

```Shell
# Install all dependencies
make sync

# Install pre-commit hooks to automatically check your code before committing
pre-commit install

# You can test the hooks at any time by running:
pre-commit run
```

--------------------------------

### Run CLI Chat Agent

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/docs/quickstart_beginner.md

Executes the command-line chat interface for the YouTu agent, requiring a configuration file. This tool allows interactive conversation with the agent. Ensure your UV environment is activated and API keys are configured.

```bash
python scripts/cli_chat.py --config_name simple/search_agent.yaml
```

--------------------------------

### Run Web Application

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/examples/file_manager/README.md

Command to start the Gradio web server, making the file manager agent accessible via a web browser.

```Bash
python -m examples.file_manager.main_web
```

--------------------------------

### Create Custom Agent Configuration Directory

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/docs/quickstart_beginner.md

Creates a directory structure for custom agent configuration files using the mkdir command. This is the first step in creating your own agent.

```bash
mkdir -p configs/agents/my_agents
```

--------------------------------

### Start Development Server

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/utu/ui/frontend/README.md

Starts the development server for the utu-agent UI. This command is typically run after installing npm packages and allows for live reloading and development of the frontend.

```bash
npm run dev
```

--------------------------------

### YAML Agent Configuration

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/docs/quickstart_beginner.md

This YAML file defines the default settings for an agent, including loading base LLM model settings, the 'search' toolkit, and allowing for local configuration overrides. It specifies the agent's name and its initial instructions.

```yaml
# @package _global_
defaults:
  - /model/base@model.   # Loads base LLM model settings
  - /tools/search@toolkits.search.  # Loads the builtin 'search' toolkit
  - _self_   # Loads the current configuration file, allowing overrides

agent:
    name: MyFirstAgent
    instructions: "You are a helpful assistant that can search the web."
```

--------------------------------

### Configure LLM Provider Environment Variables

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/docs/quickstart_beginner.md

Switches the LLM provider by modifying environment variables in the .env file. Examples are provided for OpenAI GPT models and Anthropic Claude (via OpenAI-compatible API).

```bash
# For OpenAI GPT models
UTU_LLM_TYPE=chat.completions
UTU_LLM_MODEL=gpt-4
UTU_LLM_BASE_URL=https://api.openai.com/v1
UTU_LLM_API_KEY=[Openai_API_key]

# For Anthropic Claude (via OpenAI-compatible API)
UTU_LLM_TYPE=chat.completions
UTU_LLM_MODEL=claude-3-sonnet-20240229
UTU_LLM_BASE_URL=[Anthropic_compatible_endpoint]
UTU_LLM_API_KEY=[Anthropic_API_key]
```

--------------------------------

### Configure Phoenix Tracing Environment Variables

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/docs/quickstart_beginner.md

Enables tracing for observing agent behavior by setting Phoenix tracing-related environment variables in the .env file. Compatible with other services supporting openai-agents.

```bash
# Phoenix Tracing Configuration
PHOENIX_ENDPOINT=[Phoenix_endpoint]
PHOENIX_BASE_URL=[Phoenix_base_url]
PHOENIX_PROJECT_NAME=[Phoenix_project_name]
```

--------------------------------

### Run Youtu-Agent Python Script

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/docs/quickstart_beginner.md

This Python script uses the `SimpleAgent` class from the `utu.agents` library to run a custom agent. It loads a specified agent configuration file and allows interaction by sending chat messages to the agent. The script requires the `asyncio` library.

```python
import asyncio
from utu.agents import SimpleAgent

async def main():
    # Use your custom agent configuration
    async with SimpleAgent(config="my_agents/my_first_agent.yaml") as agent:
        # Ask a question
        await agent.chat("What's the weather in Beijing today?")

asyncio.run(main())
```

--------------------------------

### Running Development Commands with uv

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/AGENTS.md

These commands utilize 'uv' to manage the virtual environment and install dependencies, ensuring a consistent development setup. They cover tasks like syncing the environment, formatting code, running tests, building documentation, and executing the CLI chat application.

```bash
make sync

```

```bash
make format

```

```bash
make lint

```

```bash
make format-check

```

```bash
uv run pytest -q

```

```bash
pytest tests/tools/test_search_toolkit.py

```

```bash
make build-docs

```

```bash
make serve-docs

```

```bash
make deploy-docs

```

```bash
uv run python scripts/cli_chat.py --config simple/base.yaml

```

```bash
make build-ui

```

```bash
uv run pytest tests/test_config.py -q

```

--------------------------------

### Build and Start Project (Bash)

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/frontend/exp_analysis/README.md

Commands to build the Next.js project for production and start the server. The server can be accessed on port 3000 by default, which can be configured in package.json.

```bash
npm run build
npm run start
```

--------------------------------

### Configure Database URL Environment Variable

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/docs/quickstart_beginner.md

Sets the DB_URL environment variable to configure the database connection for the evaluation framework. Supports PostgreSQL, MySQL, and the default SQLite. Modify the .env file to apply changes.

```bash
# For PostgreSQL
DB_URL="postgresql://user:password@host:port/database"

# For MySQL
DB_URL="mysql://user:password@host:port/database"

# Default SQLite (recommended for beginners)
DB_URL="sqlite:///test.db"
```

--------------------------------

### Run Data Analysis Example with Web UI (Python)

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/examples/data_analysis/README.md

Launches the data analysis example through a web interface using the Python module. This allows for interactive execution and visualization of the analysis results.

```Bash
python -m examples.data_analysis.main_web
```

--------------------------------

### Run File Preparation Script

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/examples/file_manager/README.md

Command to execute the Python script that sets up the necessary files and directories for the file manager example.

```Bash
python -m examples.file_manager.prepare_messy_files
```

--------------------------------

### Run Data Analysis Example (Python)

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/examples/data_analysis/README.md

Executes the data analysis example using the Python module. This command initiates the OrchestraAgent with custom configurations for data inspection and reporting.

```Bash
python -m examples.data_analysis.main
```

--------------------------------

### Build Youtu-agent Docker Image

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/docs/docker.md

Builds the Youtu-agent Docker image. Ensure you are in the project's root directory before running this command.

```bash
docker build -t youtu-agent .
```

--------------------------------

### Dump Experiment Data from Database

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/docs/quickstart_beginner.md

Extracts trajectories and results from the experiment database for a specific experiment ID. This allows for offline analysis and debugging of agent behavior and outcomes.

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

--------------------------------

### Install Youtu-Agent Frontend Package (Bash & Uvicorn)

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/README.md

Downloads and installs the Youtu-Agent frontend package, enabling visualization of the agent's runtime status via a web UI. It uses `curl` for downloading and `uv pip` for installation.

```bash
# 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
```

--------------------------------

### Paper Collector Example: Standard OrchestraAgent

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/docs/examples.md

A standard, out-of-the-box application of OrchestraAgent for multi-step document analysis. It is configuration-driven and uses few-shot examples from `planner_examples_data.json` to guide the Planner. It utilizes DocumentToolkit and SearchToolkit.

```Python
from utu.agents.orchestra_agent import OrchestraAgent
from utu.tools.document_toolkit import DocumentToolkit
from utu.tools.search_toolkit import SearchToolkit

# Configuration for the OrchestraAgent
config = {
    "planner_examples_path": "planner_examples_data.json",
    "tools": [DocumentToolkit(), SearchToolkit()]
}

# Initialize and run the OrchestraAgent
agent = OrchestraAgent(config)
result = agent.run("collect and analyze papers on topic X")
...
```

--------------------------------

### Configure Youtu-agent Environment Variables

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/docker/README.md

This snippet shows how to copy an example environment configuration file and lists the required variables for LLM, Serper API, and Frontend configuration. The IP address must be '0.0.0.0' for Docker port forwarding. Sensitive information like API keys should be kept secure.

```bash
cp .env.docker.example .env
```

```plaintext
# LLM Configuration (required)
UTU_LLM_TYPE=chat.completions
UTU_LLM_MODEL=deepseek-chat
UTU_LLM_BASE_URL=https://api.deepseek.com/v1
UTU_LLM_API_KEY=<your-api-key> # Required

# Serper API Configuration
# Get your key from https://serper.dev/playground
SERPER_API_KEY=<your-serper-key>

# Frontend Configuration
# Note: IP must be 0.0.0.0 for Docker container port forwarding
UTU_WEBUI_PORT=8848
UTU_WEBUI_IP=0.0.0.0
```

--------------------------------

### Enabling Pre-commit Hooks

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/AGENTS.md

This command installs the pre-commit framework, which automatically runs linters and formatters (like ruff) before each commit. This ensures consistent code style and quality across the project.

```bash
pre-commit install

```

--------------------------------

### Start MCP Server and Inspector

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/docs/tools.md

This sequence starts a local MCP server exposing specified toolkits (e.g., search, image, github) via HTTP and then launches an MCP Inspector to interactively test these tools. It requires Node.js and npm for the inspector, and a Python environment for the server.

```sh
# start the MCP server
python scripts/utils/start_tools_mcp.py --toolkits search image github

# start the MCP inspector
npx @modelcontextprotocol/inspector
# ... connect to the MCP server with Streamable HTTP transport URL http://localhost:3005/mcp
```

--------------------------------

### Compiling WebUI Frontend from Source (Bash)

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/docs/frontend.md

Outlines the steps to compile the WebUI frontend from source. This involves navigating to the frontend directory, installing npm dependencies, installing the build package, and executing the build script.

```bash
cd utu/ui/frontend
npm install
uv pip install build
bash ./build.sh
```

--------------------------------

### Clone Repository and Sync Dependencies (Bash)

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/README.md

This snippet demonstrates how to clone the Youtu-Agent project repository and synchronize its dependencies using uv. It also covers activating the virtual environment and setting up the environment variables by copying the example configuration file. Ensure Python 3.12+ and uv are installed beforehand.

```bash
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
```

--------------------------------

### Clone Youtu-agent Repository using Git

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/docker/README.md

This command clones the Youtu-agent project repository from GitHub. It requires Git to be installed on the system. The output is the project files downloaded to the local machine.

```bash
git clone https://github.com/Tencent/youtu-agent.git
```

--------------------------------

### File Manager Example: SimpleAgent with UI

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/docs/examples.md

A configuration-driven SimpleAgent wrapped in an interactive Gradio web UI. This example focuses on an agent interacting with the local file system, emphasizing UI integration and safety. It utilizes the BashToolkit.

```Python
import gradio as gr
from utu.agents.simple_agent import SimpleAgent
from utu.tools.bash_toolkit import BashToolkit

# Initialize the agent with BashToolkit
agent = SimpleAgent(tools=[BashToolkit()])

# Define the Gradio interface
def agent_interface(command):
    return agent.run(command)

iface = gr.Interface(fn=agent_interface, inputs="text", outputs="text")
iface.launch()
...
```

--------------------------------

### Installing WebUI Package using pip (Bash)

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/docs/frontend.md

Provides the command to install the `utu_agent_ui` package using a prebuilt wheel file. This method is suitable if you have downloaded the `.whl` file from the project's releases.

```bash
uv pip install utu_agent_ui-0.2.0-py3-none-any.whl
```

--------------------------------

### Generate SVG Introduction Image

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/README_ZH.md

This command executes a Python script from the examples directory to generate an SVG introduction image based on information about 'DeepSeek V3.1 new features'. This example requires the agent to have internet search capabilities configured.

```bash
python examples/svg_generator/main_web.py
```

--------------------------------

### Run Default Web Search Agent Demo with Docker

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/docs/docker.md

Launches the Youtu-agent service using Docker, exposing the web UI on port 8848. It mounts a local .env file into the container for configuration.

```bash
docker run -it \
    -p 8848:8848 \
    -v "/path/to/your/.env:/youtu-agent/.env" \
    youtu-agent
```

--------------------------------

### Prepare Messy Files

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/examples/file_manager/README.md

This Python script prepares a workspace by creating sample files for the file manager example. It's a prerequisite for testing the agent's file organization capabilities.

```Python
import os
import shutil

def prepare_messy_files():
    base_dir = "/tmp/file_manager_test"
    if os.path.exists(base_dir):
        shutil.rmtree(base_dir)
    os.makedirs(base_dir)

    # Create some sample files and directories
    os.makedirs(os.path.join(base_dir, "documents"))
    with open(os.path.join(base_dir, "documents", "report.txt"), "w") as f:
        f.write("This is a report.")
    with open(os.path.join(base_dir, "image.jpg"), "w") as f:
        f.write("fake image data")
    with open(os.path.join(base_dir, "notes.md"), "w") as f:
        f.write("# Meeting Notes\n- Discussed project.")

    print(f"Prepared messy files in {base_dir}")

if __name__ == "__main__":
    prepare_messy_files()
```

--------------------------------

### Install Python Wheel

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/utu/ui/frontend/README.md

Installs the built Python wheel file for the utu-agent UI. This command assumes the user is in the parent directory of the wheel file and activates the virtual environment before installation.

```bash
# install `utu_agent_ui` in the parent directory
cd ../../..
source .venv/bin/activate
uv pip install ./utu/ui/frontend/build/utu_agent_ui-0.1.5-py3-none-any.whl
```

--------------------------------

### Run MCP Stdio Example

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/docs/tools.md

This command executes a Python script to demonstrate the Model Context Protocol (MCP) using stdio transport. It requires a Python environment and the necessary MCP libraries.

```sh
python examples/mcp/stdio_example/main.py
```

--------------------------------

### Instantiate SimpleAgent with Custom Instructions

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/docs/agents.md

This example shows how to directly instantiate `SimpleAgent` and override its default configuration, specifically setting custom instructions for the agent's behavior during initialization. It utilizes an asynchronous context manager.

```python
from utu.agents import SimpleAgent

async with SimpleAgent(instructions="Always answer with prefix `Aloha!`") as agent:
    await agent.chat("What's the weather in Beijing today?")
```

--------------------------------

### Install npm Packages

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/utu/ui/frontend/README.md

Installs the necessary Node.js packages for the utu-agent UI frontend. This is a prerequisite for running the development server or building the project.

```bash
npm install
```

--------------------------------

### Copy Example .env File

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/docs/environment_variables.md

This command copies the example environment file to a new file named .env, which should then be edited with specific configurations.

```sh
cp .env.example .env
```

--------------------------------

### Run SVG Generator Example (Python)

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/README.md

Executes the SVG generator example, which allows the agent to automatically search the web for information on a given topic and generate an SVG visualization. This command assumes API keys are set in the environment.

```python
python examples/svg_generator/main.py
```

--------------------------------

### Research Example: Manual Multi-Agent Orchestration

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/docs/examples.md

Demonstrates building a complex workflow from scratch using basic SimpleAgent blocks by orchestrating three independent SimpleAgents to create a 'Plan-and-Execute' workflow. It utilizes the SearchToolkit.

```Python
from utu.agents.simple_agent import SimpleAgent
from utu.tools.search_toolkit import SearchToolkit

# Example setup for research
agent1 = SimpleAgent(...)
agent2 = SimpleAgent(...)
agent3 = SimpleAgent(...)

# Orchestration logic here
...
```

--------------------------------

### Clone Repository and Sync Dependencies

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/README_ZH.md

These bash commands clone the Youtu-Agent repository from GitHub, navigate into the project directory, synchronize project dependencies using 'uv', and activate the virtual environment. It also includes copying an example environment file and notes the need to configure environment variables.

```bash
git clone https://github.com/TencentCloudADP/youtu-agent.git
cd youtu-agent
uv sync
source ./.venv/bin/activate
cp .env.example .env  # NOTE: 你需要配置相关环境变量!
```

--------------------------------

### Launch File Manager Web UI

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/examples/file_manager/README.md

This Python script launches the Gradio web interface for the file manager agent. Users can interact with the agent through this UI to perform file organization tasks.

```Python
import gradio as gr
from agent import SimpleAgent
import os

# Assume SimpleAgent and its methods are defined elsewhere
# For demonstration, we'll use a placeholder agent
class PlaceholderAgent:
    def __init__(self):
        self.working_directory = "/tmp/file_manager_test"
        os.makedirs(self.working_directory, exist_ok=True)

    def process_task(self, task):
        return f"Agent processed task: '{task}' in {self.working_directory}"

agent = PlaceholderAgent()

def agent_interface(user_input):
    return agent.process_task(user_input)

iface = gr.Interface(
    fn=agent_interface,
    inputs=gr.Textbox(label="Enter your file management task"),
    outputs=gr.Textbox(label="Agent Response"),
    title="File Manager Agent",
    description="Organize your files using the SimpleAgent."
)

if __name__ == "__main__":
    if not os.path.exists(agent.working_directory):
        print(f"Creating working directory: {agent.working_directory}")
        os.makedirs(agent.working_directory)
    if not os.listdir(agent.working_directory):
        print("Warning: Working directory is empty. Consider running prepare_messy_files.py first.")
    iface.launch()
```

--------------------------------

### Customize Agent: Python Script Example

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/docs/quickstart.md

This Python script shows how to instantiate and run a `SimpleAgent` using a specified configuration file. The agent is then used to send a chat message. This code snippet complements the YAML configuration example for agent customization.

```python
import asyncio
from utu.agents import SimpleAgent

async def main():
    async with SimpleAgent(config="sample_tool.yaml") as agent:
        await agent.chat("What's the weather in Beijing today?")

asyncio.run(main())
```

--------------------------------

### Download Youtu-Agent UI Frontend Package

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/README_ZH.md

This command uses `curl` to download the Youtu-Agent UI frontend package from GitHub releases. The downloaded file is a Python wheel package that can be installed locally to visualize agent runtime.

```bash
# fetch and 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
```

--------------------------------

### System Prompt for Tool Disclosure

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/docs/examples_output/deep_research.md

This example demonstrates how to structure a system prompt to inform an AI model about available tools, their descriptions, and expected output formats. It emphasizes using tools only when necessary and provides a clear JSON example for tool invocation.

```text
System Prompt:
You are an assistant equipped with the following tools. Use a tool **only** when the user request cannot be answered from the conversation history.

TOOLS:
- `search_web(query: string, top_k: integer = 3) -> list[dict]` – fetches up‑to‑date web results.
- `calc(expression: string) -> number` – safe arithmetic evaluator.
- `pdf_extract(file_id: string, fields: list[string]) -> dict` – extracts structured data from a PDF stored in the vector store.

When you decide to call a tool, output **exactly** the JSON snippet shown in the example below.

Example:
{ "tool": "search_web", "arguments": { "query": "latest S&P 500 price" } }
```

--------------------------------

### Wide Research Example: Agent-as-Tool Pattern

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/docs/examples.md

Illustrates the 'Agent-as-Tool' pattern where a single SimpleAgent makes decisions and calls a custom tool that encapsulates parallel sub-agents. This simplifies the main agent's logic by abstracting parallelism and complex operations into a tool. It uses the SearchToolkit.

```Python
from utu.agents.simple_agent import SimpleAgent
from utu.tools.search_toolkit import SearchToolkit

# Define a custom tool that encapsulates parallel sub-agents
class ParallelSubAgentTool:
    def __init__(self):
        # Initialize sub-agents and orchestration logic
        pass

    def run(self, query):
        # Logic to run sub-agents in parallel and aggregate results
        return "results from parallel agents"

# Main agent using the custom tool
main_agent = SimpleAgent(tools=[ParallelSubAgentTool()])

# Agent interaction
response = main_agent.run("perform wide research")
...
```

--------------------------------

### Run Simple and Orchestra Agents via CLI

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/docs/quickstart.md

These commands show how to run different types of agents from the command line. The first command runs a simple agent with search capabilities using a specified configuration file. The second command runs a multi-agent orchestra agent, and the third command starts a web UI for the agent.

```sh
# Run a simple agent with search capabilities
python scripts/cli_chat.py --config_name simple/search_agent.yaml
```

```sh
# Run a multi-agent (Plan-and-Execute) orchestra agent
python examples/svg_generator/main.py
```

```sh
# Run a web UI for the agent
python examples/svg_generator/main_web.py
```

--------------------------------

### Basic WebUI Chatbot with SimpleAgent (Python)

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/docs/frontend.md

Demonstrates how to launch a WebUI chatbot using the `WebUIChatbot` class with a `SimpleAgent`. This requires the `utu_agent_ui` package to be installed. The chatbot can be launched on a specified IP and port.

```python
from utu.ui.webui_chatbot import WebUIChatbot
from utu.agents import SimpleAgent

simple_agent = SimpleAgent(name="demo")

chatbot = WebUIChatbot(
    simple_agent,
    example_query="Hello, how are you?",
)
chatbot.launch(port=8848, ip="127.0.0.1")
```

--------------------------------

### Use SimpleAgent with MCP-based Tools

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/docs/agents.md

This example illustrates using `SimpleAgent` with tools configured via the Multi-Component Protocol (MCP), indicated by setting the toolkit's `mode` to `mcp`. It uses an asynchronous context manager for the agent.

```python
from utu.agents import SimpleAgent

async with SimpleAgent(config="sample_mcp.yaml") as agent:
    await agent.chat("What's the time now")
```

--------------------------------

### Project Scripts in package.json (JSON)

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/frontend/exp_analysis/README.md

Defines the available scripts for the Next.js project, including development, building, starting, linting, database migration, and database connection testing.

```json
{
  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start -p 3000",
    "lint": "next lint",
    "db:migrate": "tsx src/lib/db/migrate.ts",
    "test:db": "tsx scripts/test-db-connection.ts"
  }
}
```

--------------------------------

### Customize Agent: Configuration and Python Script

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/docs/quickstart.md

This example demonstrates how to customize an agent by creating a YAML configuration file that defines agent properties and loads toolkits. It's followed by a Python script that utilizes the `SimpleAgent` class to run a chat interaction with the customized agent.

```yaml
# configs/agents/sample_tool.yaml
defaults:
  - /model/base
  - /tools/search@toolkits.search # Loads the 'search' toolkit
  - _self_

agent:
    name: simple-tool-agent
    instructions: "You are a helpful assistant that can search the web."
```

--------------------------------

### Planner Few-Shot Examples (JSON)

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/examples/paper_collector/README.md

This JSON file provides few-shot examples for the Planner agent, guiding it on how to generate effective plans for paper analysis tasks. Modifying these examples can influence the Planner's output and overall workflow performance.

```json
[
  {
    "input": "Analyze the paper: The Impact of AI on Society",
    "output": {
      "plan": [
        {
          "task": "Summarize the paper",
          "input": "Summarize the key findings of the paper 'The Impact of AI on Society'."
        },
        {
          "task": "Find related articles",
          "input": "Find articles related to the societal impact of AI."
        },
        {
          "task": "Generate report",
          "input": "Combine the summary and related articles into a comprehensive report."
        }
      ]
    }
  },
  {
    "input": "Analyze the paper: Quantum Computing Fundamentals",
    "output": {
      "plan": [
        {
          "task": "Summarize the paper",
          "input": "Provide a concise summary of 'Quantum Computing Fundamentals'."
        },
        {
          "task": "Find related articles",
          "input": "Search for recent advancements in quantum computing."
        },
        {
          "task": "Generate report",
          "input": "Create a report detailing the paper's summary and recent quantum computing news."
        }
      ]
    }
  }
]
```

--------------------------------

### Build Youtu-agent Docker Image

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/docker/README.md

This command builds the Docker image for the Youtu-agent service. It requires Docker to be installed and assumes the Dockerfile is located in the 'docker/' directory relative to the project root. The image is tagged as 'youtu-agent'.

```bash
cd youtu-agent/docker
docker build -t youtu-agent .
```

--------------------------------

### Re-judge Existing Evaluation Results

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/docs/quickstart_beginner.md

Re-executes the judgment phase of an evaluation experiment without re-running the agent rollout. This is useful for re-evaluating results with updated judging criteria or parameters. Requires configuration, experiment ID, and dataset.

```bash
python scripts/run_eval_judge.py --config_name <your_eval_config> --exp_id <your_exp_id> --dataset WebWalkerQA
```

--------------------------------

### Configure and Launch Simple Search Agent (YAML & Python)

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/README.md

Defines a simple agent with a search tool using a YAML configuration file and demonstrates how to launch an interactive CLI chatbot with it. Requires API keys for web search.

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

```python
# 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 --config simple/base_search
# To avoid using the search toolkit, you can run:
python scripts/cli_chat.py --config simple/base
```

--------------------------------

### Generate and Run Simple Agent Configuration (Bash)

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/README.md

Demonstrates how to interactively generate a YAML configuration for an agent and then run it using the command-line interface. This showcases the automatic agent generation feature of Youtu-Agent.

```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 --config generated/xxx
```

--------------------------------

### LangChain ZeroShotAgent Implementation

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/docs/examples_output/deep_research.md

Illustrates the implementation of the ReAct pattern using LangChain's ZeroShotAgent. This snippet shows how to initialize an agent with a language model and a set of tools, providing a uniform API for explainable reasoning.

```Python
agent = ZeroShotAgent.from_llm_and_tools(llm, tools)
```

--------------------------------

### Install python-docx using pip

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/examples/gui_agent_datamaker/ref_output/trajectory.txt

Installs the 'python-docx' library, which is necessary for manipulating Microsoft Word documents (.docx) using Python. This command ensures the required package is available in the environment.

```bash
pip install python-docx
```

```bash
pip3 install python-docx
```

--------------------------------

### Configure Tool API Keys in .env

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/README_ZH.md

This snippet details the configuration of API keys for external tools like Serper and Jina within the `.env` file. These keys are necessary for agents that require internet search capabilities. It provides links to access API key information.

```bash
# 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>
```

--------------------------------

### Paper Collector Configuration (YAML)

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/examples/paper_collector/README.md

This YAML file defines the configuration for the paper collector example, specifying the agents and their roles in the Plan-and-Execute workflow. It outlines the Planner, Worker agents (PaperSummarizeAgent, SearchAgent), and Reporter agent.

```yaml
name: "PaperCollector"

# Define the agents used in the workflow
agents:
  - name: "Planner"
    class: "OrchestraAgent"
    config:
      prompt_template_path: "prompts/planner.prompt"
      examples_path: "configs/examples/planner_examples_data.json"

  - name: "PaperSummarizeAgent"
    class: "PaperSummarizeAgent"
    config:
      prompt_template_path: "prompts/summarize.prompt"

  - name: "SearchAgent"
    class: "SearchAgent"
    config:
      search_engine: "google"

  - name: "Reporter"
    class: "ReporterAgent"
    config:
      report_template_path: "templates/report.md"

# Define the workflow steps
workflow:
  - step: "Plan paper analysis"
    agent: "Planner"
    input: "Analyze the paper: {paper_title}"
    output_key: "plan"

  - step: "Summarize the paper"
    agent: "PaperSummarizeAgent"
    input: "{plan.summarize_task.input}"
    output_key: "summary"

  - step: "Find related articles"
    agent: "SearchAgent"
    input: "Related articles for {paper_title}"
    output_key: "related_articles"

  - step: "Generate report"
    agent: "Reporter"
    input: "Summary: {summary}\nRelated Articles: {related_articles}"
    output_key: "final_report"
```

--------------------------------

### Run Basic CLI Chat Agent

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/README_ZH.md

These commands demonstrate how to run the Youtu-Agent CLI chat. The first command runs a base search agent, requiring SERPER_API_KEY and JINA_API_KEY to be set in `.env`. The second command runs a simpler base agent without search tools.

```bash
# NOTE: 你需要在 .env 中配置 `SERPER_API_KEY` 和 `JINA_API_KEY` (我们计划在未来替换为免费工具)
python scripts/cli_chat.py --config simple/base_search
# 如果你不想使用搜索工具，可以运行
python scripts/cli_chat.py --config simple/base
```

--------------------------------

### Configure LiteLLM Package for LLM Models

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/docs/faq.md

This bash snippet demonstrates configuring the `litellm` package directly by setting environment variables. It includes setting the LLM type to `litellm` and specifying the model name. Additional LiteLLM configurations can be added as needed.

```bash
UTU_LLM_TYPE=litellm  # set the llm type as litellm
# set the litellm model name. e.g. azure/gpt-5
UTU_LLM_MODEL=
# add other necessary litellm configs bellow, see https://docs.litellm.ai/docs/providers/
```

--------------------------------

### Runtime DSL Enforcement Example

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/docs/examples_output/deep_research.md

Demonstrates the enforcement of runtime Domain Specific Language (DSL) rules for tool usage. This example shows how to define policies that can abort or reject tool calls based on specific conditions related to the tool name and its arguments.

```DSL
when tool=search_web and arguments.query contains "password" => abort
when tool=calc and arguments.expression length > 200 => reject
```

--------------------------------

### Data Analysis Example: Customized OrchestraAgent

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/docs/examples.md

An advanced use case of OrchestraAgent demonstrating deep customization for a complex, domain-specific problem. It features a DAPlannerAgent that proactively inspects data schema before planning and a custom Reporter that generates a rich HTML report using a specific template. It utilizes the TabularDataToolkit.

```Python
from utu.agents.orchestra_agent import OrchestraAgent
from utu.tools.tabular_data_toolkit import TabularDataToolkit

# Custom Planner Agent
class DAPlannerAgent(OrchestraAgent):
    def plan(self, prompt):
        # Inspect data schema proactively
        schema_info = self.inspect_data_schema()
        # Generate plan based on schema and prompt
        return super().plan(f"Schema: {schema_info}\nPrompt: {prompt}")

# Custom Reporter
class CustomReporter:
    def generate_report(self, analysis_results):
        # Use custom template to generate HTML report
        return f"<html><body><h1>Report</h1><p>{analysis_results}</p></body></html>"

# Configuration for the customized OrchestraAgent
config = {
    "planner_agent_class": DAPlannerAgent,
    "reporter_class": CustomReporter,
    "tools": [TabularDataToolkit()]
}

# Initialize and run the customized agent
agent = OrchestraAgent(config)
report = agent.run("analyze sales data")
...
```

--------------------------------

### Format and Lint Code with pre-commit

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/CONTRIBUTING.md

Applies code formatting and runs linters using the pre-commit framework. This command ensures code consistency across the project.

```Shell
# Format code and run linters
make format
```

--------------------------------

### Agent Environment Configuration

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/docs/env.md

Example of how to specify the environment for an agent in its configuration file. This allows selection between different environment types like 'shell_local', 'browser_docker', or 'base'.

```yaml
env:
  name: shell_local  # Or: browser_docker, base
```

--------------------------------

### Use SimpleAgent with YAML Configuration

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/docs/agents.md

This snippet demonstrates using `SimpleAgent` with a YAML configuration file that defines the agent's properties and loads toolkits, such as a search toolkit. It also uses an asynchronous context manager.

```python
from utu.agents import SimpleAgent

async with SimpleAgent(config="sample_tool.yaml") as agent:
    await agent.chat("What's the weather in Beijing today?")
```

--------------------------------

### Run All Tests for uTu-agent

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/CONTRIBUTING.md

Executes the entire test suite for the uTu-agent project. This is a comprehensive check to ensure all functionalities are working as expected.

```Shell
pytest
```

--------------------------------

### Generate Youtu-Agent Simple Agent Configuration

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/docs/auto_generation.md

This command starts an interactive script to generate a configuration file for a SimpleAgent. The script will prompt the user for agent details like name, instructions, and tools.

```bash
python scripts/gen_simple_agent.py
```

--------------------------------

### Load Agent and Evaluation Configurations using ConfigLoader

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/docs/config.md

Demonstrates how to use the ConfigLoader class to load agent and evaluation configurations from YAML files. This class abstracts the file loading logic, making it easier to access configuration data.

```python
from utu.config import ConfigLoader

# Load an agent configuration from /configs/agents/my_agent.yaml
agent_config = ConfigLoader.load_agent_config("my_agent")

# Load an evaluation configuration from /configs/eval/my_eval.yaml
eval_config = ConfigLoader.load_eval_config("my_eval")
```

--------------------------------

### Generate and Test Youtu-Agent Tool

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/docs/auto_generation.md

This script initiates the process of generating a new tool for the Youtu-Agent framework. It creates a tool directory and configuration file, sets up a virtual environment, and installs dependencies from a requirements.txt file.

```shell
python scripts/gen_tool.py
```

```shell
cd {output_directory}
uv venv
source .venv/bin/activate
uv pip install -r requirements.txt
```

--------------------------------

### Build Python Wheel

Source: https://github.com/tencentcloudadp/youtu-agent/blob/main/utu/ui/frontend/README.md

Builds a Python wheel file for the utu-agent UI. This involves synchronizing dependencies with uv, activating a virtual environment, and executing a build script. The resulting wheel is typically found in the 'build' directory.

```bash
uv sync
source .venv/bin/activate
bash ./build.sh
```