### Install Project Dependencies (Bash)

Source: https://tencentcloudadp.github.io/youtu-agent/quickstart_beginner

Installs all project dependencies, including development tools, using UV.

```bash
uv sync --group dev
```

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

### Environment Variable Configuration Example (Properties)

Source: https://tencentcloudadp.github.io/youtu-agent/quickstart_beginner

Example configuration for environment variables, including LLM and tool API keys. Replace placeholders with actual keys.

```properties
# 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]
```

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

### Install UV Package Manager (Pipx)

Source: https://tencentcloudadp.github.io/youtu-agent/quickstart_beginner

Installs the UV package manager using pipx. This is a fast Python package manager.

```python
pipx install uv
```

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

### Run Web UI for Agent

Source: https://tencentcloudadp.github.io/youtu-agent/quickstart

Starts a web-based user interface for interacting with the agent.

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

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

### Copy Environment Configuration Example

Source: https://tencentcloudadp.github.io/youtu-agent/docker

Copies the example environment file to be used for Docker configurations. This file will contain necessary settings for the agent.

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

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

### Verify UV Installation (Bash)

Source: https://tencentcloudadp.github.io/youtu-agent/quickstart_beginner

Verifies the installation of the UV package manager by checking its version.

```bash
uv --version
```

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

### Install UV Package Manager (Pip)

Source: https://tencentcloudadp.github.io/youtu-agent/quickstart_beginner

Installs the UV package manager using pip. This is a fast Python package manager.

```python
pip install uv
```

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

### Run WebUI Examples with Python

Source: https://tencentcloudadp.github.io/youtu-agent/examples

This snippet illustrates how to initiate the WebUI versions of the examples. It requires the `utu_agent_ui` package to be installed, providing an interactive graphical interface for the agent's functionality.

```bash
python main_web.py
```

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

### Install UV Package Manager (PowerShell)

Source: https://tencentcloudadp.github.io/youtu-agent/quickstart_beginner

Installs the UV package manager on Windows using PowerShell. This is a fast Python package manager.

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

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

### Clone Youtu-agent Project (Bash)

Source: https://tencentcloudadp.github.io/youtu-agent/quickstart_beginner

Clones the Youtu-agent project repository from GitHub to your local machine using Git.

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

cd youtu-agent
```

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

### Clone Repository and Setup Python Environment

Source: https://tencentcloudadp.github.io/youtu-agent/quickstart

Clones the youtu-agent GitHub repository and sets up the Python virtual environment and dependencies using uv.

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

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

### Build Youtu-agent Docker Image

Source: https://tencentcloudadp.github.io/youtu-agent/docker

Builds the Docker image for the Youtu-agent. Ensure Docker is installed and you are in the project directory.

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

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

### Install UV Package Manager (Shell Script)

Source: https://tencentcloudadp.github.io/youtu-agent/quickstart_beginner

Installs the UV package manager using a shell script. This is a fast Python package manager.

```shell
curl -LsSf https://astral.sh/uv/install.sh | sh
```

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

### Create and Activate Virtual Environment (Bash)

Source: https://tencentcloudadp.github.io/youtu-agent/quickstart_beginner

Creates a new virtual environment named '.venv' using UV and then activates it for Linux/macOS.

```bash
uv venv

source .venv/bin/activate
```

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

### Run WebUI Example Script (Shell)

Source: https://tencentcloudadp.github.io/youtu-agent/frontend

Provides instructions on how to run an example script to start the WebUI from the command line. This is a convenient way to test the WebUI functionality.

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

```

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

### Configure Environment Variables (Bash)

Source: https://tencentcloudadp.github.io/youtu-agent/quickstart_beginner

Copies the environment variable template file to '.env' and opens it for editing with nano.

```bash
cp .env.example .env

nano .env
```

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

### Create Agent Configuration Directory (Shell)

Source: https://tencentcloudadp.github.io/youtu-agent/quickstart_beginner

Creates a directory structure for custom agent configuration files using the mkdir command.

```shell
# Create a new agent configuration file
mkdir -p configs/agents/my_agents
```

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

### Run Simple Agent with Search Capability

Source: https://tencentcloudadp.github.io/youtu-agent/quickstart

Executes a simple agent using a configuration file, demonstrating search capabilities via the command line interface.

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

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

### Run Full Evaluation Experiment

Source: https://tencentcloudadp.github.io/youtu-agent/quickstart

Initiates a comprehensive evaluation process, covering agent rollout and judgment, with specified dataset and concurrency.

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

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

### Run Custom Simple Agent (Python)

Source: https://tencentcloudadp.github.io/youtu-agent/quickstart_beginner

Implements a Python script to run a custom agent using the SimpleAgent class. It loads a specified agent configuration and allows interaction via chat.

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

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

### Activate Virtual Environment (Windows Batch)

Source: https://tencentcloudadp.github.io/youtu-agent/quickstart_beginner

Activates the virtual environment named '.venv' for Windows command prompt.

```batch
.venv\Scripts\activate
```

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

### Create Agent Config File

Source: https://tencentcloudadp.github.io/youtu-agent/quickstart

Defines a sample agent configuration file, including base models and the search toolkit.

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

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

### Define Custom Agent Configuration (YAML)

Source: https://tencentcloudadp.github.io/youtu-agent/quickstart_beginner

Defines the configuration for a custom agent, including LLM model settings and toolkits. This YAML file specifies the agent's name, instructions, and default configurations.

```yaml
# @package _global_
defaults:
  - /model/base@model.
  - /tools/search@toolkits.search.
  - _self_

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

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

### Configure Phoenix Tracing in .env File (Shell)

Source: https://tencentcloudadp.github.io/youtu-agent/quickstart_beginner

Enables tracing for observing agent behavior by setting Phoenix tracing environment variables in the .env file. Requires Phoenix endpoint and project details.

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

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

### Configure LLM Provider in .env File (Shell)

Source: https://tencentcloudadp.github.io/youtu-agent/quickstart_beginner

Switches the LLM provider by setting relevant environment variables in the .env file. Supports configuration for OpenAI GPT models and Anthropic Claude via compatible APIs.

```shell
# 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]
```

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

### Run Examples with Python

Source: https://tencentcloudadp.github.io/youtu-agent/examples

This snippet shows the general command to run Python example scripts from their respective directories. It's the primary method for executing the demonstrations provided by the YouTu Agent.

```bash
python main.py
```

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

### Configure Database URL in .env File (Shell)

Source: https://tencentcloudadp.github.io/youtu-agent/quickstart_beginner

Sets the database connection URL in the .env file for the evaluation framework. Supports various database systems like PostgreSQL, MySQL, and SQLite.

```shell
# 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"
```

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

### Write and Run Custom Agent Script

Source: https://tencentcloudadp.github.io/youtu-agent/quickstart

Demonstrates writing and running a custom agent in Python using the `SimpleAgent` class and a provided configuration file.

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

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

### Run Orchestra Agent (Plan-and-Execute)

Source: https://tencentcloudadp.github.io/youtu-agent/quickstart

Launches a multi-agent orchestration system, specifically a Plan-and-Execute agent, using its configuration file.

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

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

### Launch Youtu-agent with Interactive Shell Access

Source: https://tencentcloudadp.github.io/youtu-agent/docker

Launches the Youtu-agent Docker container with interactive shell access, allowing for custom configurations or running other examples. It maps the host port 8848 to the container's port and mounts a local .env file.

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

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

### Enable Phoenix Tracing

Source: https://tencentcloudadp.github.io/youtu-agent/quickstart

Sets environment variables required to enable Phoenix for agent behavior tracing.

```bash
# PHOENIX_ENDPOINT
# PHOENIX_BASE_URL
# PHOENIX_PROJECT_NAME
```

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

### Build WebUI from Source (Shell)

Source: https://tencentcloudadp.github.io/youtu-agent/frontend

Outlines the steps to build the WebUI from source, which includes installing npm dependencies, installing a build package, and running a build script.

```bash
npm install
uv pip install build
bash ./build.sh

```

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

### Install WebUI Package (Shell)

Source: https://tencentcloudadp.github.io/youtu-agent/frontend

Details the command for installing the WebUI package using pip. This assumes a prebuilt wheel file is available for installation.

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

```

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

### Dump Experiment Data from Database

Source: https://tencentcloudadp.github.io/youtu-agent/quickstart

Retrieves trajectories and results from the database for a specific experiment ID.

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

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

### Configure PostgreSQL Database

Source: https://tencentcloudadp.github.io/youtu-agent/quickstart

Sets the DB_URL environment variable to configure the evaluation framework to use PostgreSQL instead of the default SQLite.

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

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

### Orchestra Planner Configuration (Python)

Source: https://tencentcloudadp.github.io/youtu-agent/ref/config/agent_config

This Python snippet defines the 'planner_config' attribute as a dictionary for orchestra agents. It includes a description mentioning 'examples_path' for providing planner examples, likely in a JSON format, to guide the planning process.

```Python
planner_config: dict = Field(default_factory=dict)

"""Planner config (dict)\n    - `examples_path`: path to planner examples json file"""
```

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

### Copy and Edit .env Example for Youtu-Agent Configuration

Source: https://tencentcloudadp.github.io/youtu-agent/environment_variables

This snippet shows the command to copy the example environment file to be edited. It's a prerequisite for configuring Youtu-Agent with necessary API keys and settings.

```shell
cp .env.example .env
```

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

### System Prompt with Tool Disclosure (Agentic Playbook)

Source: https://tencentcloudadp.github.io/youtu-agent/examples_output/deep_research

This example demonstrates how to configure a system prompt for an AI agent, detailing the available tools, their arguments, and return types. It emphasizes tool usage guidelines and provides an example of the expected JSON output for tool calls. This helps the model understand its capabilities and how to interact with them.

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

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

### Re-judge Existing Evaluation Results

Source: https://tencentcloudadp.github.io/youtu-agent/quickstart

Re-runs the judgment phase of an evaluation experiment for already processed rollouts.

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

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

### BrowserEnv Class Initialization and Setup - Python

Source: https://tencentcloudadp.github.io/youtu-agent/ref/env/browser_env

Initializes the BrowserEnv with a trace ID, Docker manager, and sets the initial browser state to None. It prepares the environment for browser interactions.

```Python
class BrowserEnv(BaseEnv):
    """Browser environment for agents."""

    def __init__(self, trace_id: str):
        self.trace_id = trace_id
        self.docker_manager = DockerManager()
        self.browser_state: str = None
```

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

### Run Default Web Search Agent Demo

Source: https://tencentcloudadp.github.io/youtu-agent/docker

Launches the Youtu-agent Docker container to run the default web search agent demo. It maps the host port 8848 to the container's port and mounts a local .env file for configuration. The agent will be accessible at http://127.0.0.1:8848.

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

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

### SimpleAgent Usage with YAML Configuration and Built-in Tools

Source: https://tencentcloudadp.github.io/youtu-agent/agents

Illustrates using `SimpleAgent` with a YAML configuration file to define the agent and its toolkits, enabling more complex behavior. The example loads a configuration file named `sample_tool.yaml`.

```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?")
```

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

### Get Tools in Agents Format (Python)

Source: https://tencentcloudadp.github.io/youtu-agent/ref/tool/audio_toolkit

Fetches tools formatted specifically for the openai-agents library. It utilizes the tool map and converts each tool into the required FunctionTool structure.

```Python
async def get_tools_in_agents(self) -> list[FunctionTool]:
    """Get tools in openai-agents format."""
    tools_map = await self.get_tools_map_func()
    tools = []
    for _, tool in tools_map.items():
        tools.append(
            function_tool(
                tool,
                strict_mode=False,  # turn off strict mode
            )
        )
    return tools
```

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

### Build Browser Environment using Docker - Python

Source: https://tencentcloudadp.github.io/youtu-agent/ref/env/browser_env

Asynchronously builds the browser environment by starting a Docker container and retrieving the MCP URL. This is a crucial step for establishing communication with the browser.

```Python
async def build(self):
    """Build the environment. We use docker to run a browser container."""
    self.container_info = await self.docker_manager.start_container(self.trace_id)
    self.mcp_url = self.container_info["mcp_url"]
```

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

### Get Available Browser Tools - Python

Source: https://tencentcloudadp.github.io/youtu-agent/ref/env/browser_env

Asynchronously retrieves a list of available browser tools. It filters tools based on a predefined set of activated tools and configures them with invocation logic using MCPClient.

```Python
async def get_tools(self) -> list[Tool]:
    """Get the tools available in the environment."""
    activated_tools = (
        "search_google",
        "go_to_url",
        "go_back",
        # "wait",
        "click_element",
        "input_text",
        "switch_tab",
        "open_tab",
        "scroll_down",
        "scroll_up",
        "download_file",
        # "search_google_api"
    )
    tools: list[Tool] = []

    def create_on_invoke_tool(tool_name: str):
        async def on_invoke_tool(ctx: RunContextWrapper[TContext], input_json: str) -> str:
            try:
                async with MCPClient.get_mcp_client(self.mcp_url) as client:
                    res = await client.call_tool(tool_name, json.loads(input_json))
                    if res.isError:
                        return f"Error: {res.content[0].text}"
                    self.browser_state = res.content[1].text  # DISCUSS: record the web actions?
                    return res.content[0].text
            except Exception as e:  # pylint: disable=broad-except
                logger.error(f"except: {e}", exc_info=True)
                return f"Error: {e}"

        return on_invoke_tool

    async with MCPClient.get_mcp_client(self.mcp_url) as client:
        # NOTE: check `MCPUtil` in @agents
        res = await client.list_tools()
        assert res.nextCursor is None
        for tool in res.tools:
            if tool.name not in activated_tools:
                continue
            tools.append(
                FunctionTool(
                    name=tool.name,
                    description=tool.description,
                    params_json_schema=tool.inputSchema,
                    on_invoke_tool=create_on_invoke_tool(tool.name),
                )
            )
        return tools
```

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

### Load Agent Configuration using ConfigLoader in Python

Source: https://tencentcloudadp.github.io/youtu-agent/ref/config/loader

This method loads the configuration for the agent. It prepends 'agents/' to the name if it doesn't already start with it and loads the configuration from the general configs directory.

```python
@classmethod
def load_agent_config(cls, name: str = "default") -> AgentConfig:
    """Load agent config"""
    if not name.startswith("agents/"):
        name = "agents/" + name
    cfg = cls._load_config_to_dict(name, config_path="../../configs")
    return AgentConfig(**cfg)

```

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

### BaseBenchmark Class for AI Agent Evaluation

Source: https://tencentcloudadp.github.io/youtu-agent/ref/eval/benchmarks

Defines the core structure for AI agent benchmarks, including data loading, preprocessing, rollout, judging, and statistical analysis. It utilizes configuration files for setup and manages evaluation samples through a database manager.

```python
import asyncio
import json
import time

from tqdm.asyncio import tqdm

from common.db_manager import DBDataManager
from common.evaluation_sample import EvaluationSample
from common.processer import BaseProcesser
from common.utils import AgentsUtils
from config import EvalConfig, ConfigLoader
from youtu_agent.agent import BaseAgent, get_agent

logger = logging.getLogger(__name__)


class BaseBenchmark:
    """Base class for benchmarks.

    Evaluation phases:
      - preprocess: load and preprocess the data
      - rollout: rollout the predictions
      - judge: judge the correctness of a batch of predictions
      - stat: get metrics.
    """

    dataset: DBDataManager
    _source_to_processer: dict[str, BaseProcesser] = {}
    _source_to_agent: dict[str, BaseAgent] = {}

    def __init__(self, config: EvalConfig | str) -> None:
        # config
        if isinstance(config, str):
            config = ConfigLoader.load_eval_config(name=config)
        self.config = config

        # dataset
        self.dataset = DBDataManager(config)
        _samples = self.dataset.load()
        if len(_samples) == 0:
            raise ValueError(f"No samples found for data config '{self.config.data}'! Please check the data config.")

    async def main(self):
        logger.info(f"> Running with config: \n{json.dumps(self.config.model_dump(), indent=2, ensure_ascii=False)}")
        self.preprocess()
        await self.rollout()
        await self.judge()
        logger.info("> Running stat...")
        await self.stat()
        logger.info("> Cleaning up...")
        await self.cleanup()

    def preprocess(self) -> None:
        """Preprocess the dataset before rollout."""
        samples = self.dataset.get_samples(stage="init")
        logger.info(f"Preprocessing {len(samples)} samples...")
        results = []
        for sample in tqdm(samples, desc="Preprocessing"):
            processed_sample = self.preprocess_one(sample)
            if processed_sample is not None:
                results.append(processed_sample)
        logger.info(f"Successfully preprocessed {len(results)} samples. Updated to db.")
        return results

    def preprocess_one(self, sample: EvaluationSample) -> EvaluationSample:
        processer = self._get_processer(sample.source)
        processed_sample = processer.preprocess_one(sample)
        if processed_sample is None:
            return None
        self.dataset.save(sample)
        return sample

    async def rollout(self) -> None:
        """Rollout the datapoints."""
        samples = self.dataset.get_samples(stage="init")
        logger.info(f"Rollout {len(samples)} samples...")

        semaphore = asyncio.Semaphore(self.config.concurrency)

        async def rollout_with_semaphore(item: EvaluationSample):
            async with semaphore:
                try:
                    return await self.rollout_one(item)
                except Exception as e:  # pylint: disable=broad-except
                    logger.error(
                        f">>>>>>>>>>>>>\nError running rollout on sample '{item.raw_question}': {e}\n<<<<<<<<<<<<<",
                        exc_info=True,
                    )

        tasks = [rollout_with_semaphore(item) for item in samples]
        results = []
        for task in tqdm(asyncio.as_completed(tasks), total=len(tasks), desc="Rolling out"):
            result = await task
            if result is not None:
                results.append(result)
        logger.info(f"Successfully rollout {len(results)} samples. Updated to db.")
        return results

    async def rollout_one(self, sample: EvaluationSample) -> EvaluationSample:
        agent = get_agent(self.config.agent)
        await agent.build()
        trace_id = AgentsUtils.gen_trace_id()
        start_time = time.time()
        result = await agent.run(sample.augmented_question, trace_id=trace_id)
        end_time = time.time()

        # Update the sample with the predicted answer and trajectory
        sample.update(
            trace_id=trace_id,
            response=result.final_output,
            time_cost=end_time - start_time,
            trajectories=json.dumps(result.trajectories, ensure_ascii=False),
            stage="rollout",  # update stage to rollout!
        )
        self.dataset.save(sample)
        return sample

```

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

### SimpleAgent Build Process (Python)

Source: https://tencentcloudadp.github.io/youtu-agent/ref/agents/simple_agent

Builds the agent by initializing the environment, creating the core agent instance with specified tools and configurations, and setting up the context manager. Skips if already initialized.

```python
    async def build(self, trace_id: str = None):
        """Build the agent"""
        if self._initialized:
            logger.info("Agent already initialized! Skipping build.")
            return
        self.env = await get_env(self.config, trace_id or AgentsUtils.gen_trace_id())  # Pass trace_id
        await self.env.build()
        self.current_agent = Agent(
            name=self.config.agent.name,
            instructions=self.config.agent.instructions,
            model=self.model,
            model_settings=self.model_settings,
            tools=await self.get_tools(),
            output_type=self.output_type,
            tool_use_behavior=self.tool_use_behavior,
            mcp_servers=self._mcp_servers,
        )
        self.context_manager = build_context_manager(self.config)
        self._initialized = True
```

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

### Get Tools in OpenAI Format

Source: https://tencentcloudadp.github.io/youtu-agent/ref/tool/bash_toolkit

Retrieves tools formatted for OpenAI. It calls `get_tools_in_agents` to get tools in the agent format and then converts them to the specific OpenAI format using `ChatCompletionConverter.tool_to_openai`.

```python
from typing import Callable, Dict, List, Any

# Mock classes for demonstration
class FunctionTool:
    def __init__(self, func: Callable, strict_mode: bool):
        self.func = func
        self.strict_mode = strict_mode

class ChatCompletionConverter:
    @staticmethod
    def tool_to_openai(tool: FunctionTool) -> Dict[str, Any]:
        # Mock conversion logic
        return {"name": tool.func.__name__, "description": "A mock description"}

class BaseTools:
    def __init__(self, config: Any, tools_map: Dict[str, Callable]):
        self.config = config
        self.tools_map = tools_map

    async def get_tools_map_func(self) -> Dict[str, Callable]:
        # Mock implementation
        return self.tools_map

    async def get_tools_in_agents(self) -> List[FunctionTool]:
        # Mock implementation
        return [FunctionTool(func, False) for func in self.tools_map.values()]

    async def get_tools_in_openai(self) -> List[Dict]:
        """Get tools in OpenAI format."""
        tools = await self.get_tools_in_agents()
        return [ChatCompletionConverter.tool_to_openai(tool) for tool in tools]

```

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

### Build Agent

Source: https://tencentcloudadp.github.io/youtu-agent/ref/agents/simple_agent

Initializes the agent by setting up the environment and creating the core agent object with specified configurations, including name, instructions, model, and tools.

```python
async def build(self, trace_id: str = None):
    """Build the agent"""
    if self._initialized:
        logger.info("Agent already initialized! Skipping build.")
        return
    self.env = await get_env(self.config, trace_id or AgentsUtils.gen_trace_id())  # Pass trace_id
    await self.env.build()
    self.current_agent = Agent(
        name=self.config.agent.name,
        instructions=self.config.agent.instructions,
        model=self.model,
        model_settings=self.model_settings,
        tools=await self.get_tools(),
        output_type=self.output_type,
        tool_use_behavior=self.tool_use_behavior,
        mcp_servers=self._mcp_servers,
    )
    self.context_manager = build_context_manager(self.config)
    self._initialized = True
```

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

### Get Tools in OpenAI Format

Source: https://tencentcloudadp.github.io/youtu-agent/ref/tool/document_toolkit

The `get_tools_in_openai` function retrieves a list of tools formatted specifically for OpenAI's API. It leverages `get_tools_in_agents` to get the tools in the agent format and then uses `ChatCompletionConverter.tool_to_openai` to convert them into the required OpenAI format.

```python
get_tools_in_openai() -> list[dict]

Get tools in OpenAI format.

async def get_tools_in_openai(self) -> list[dict]:
    """Get tools in OpenAI format."""
    tools = await self.get_tools_in_agents()
    return [ChatCompletionConverter.tool_to_openai(tool) for tool in tools]
```

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

### Start Persistent Bash Shell

Source: https://tencentcloudadp.github.io/youtu-agent/ref/tool/bash_toolkit

Starts a persistent bash shell session using pexpect. It handles platform differences (Windows vs. Linux) and sets a custom prompt for reliable output capturing. Includes logic for setting terminal modes and unsetting prompt commands on Linux.

```python
    @staticmethod
    def start_persistent_shell(timeout: int):
        import sys

        import pexpect
        # https://github.com/pexpect/pexpect/issues/321

        # Start a new Bash shell
        if sys.platform == "win32":
            child = pexpect.spawn("cmd.exe", encoding="utf-8", echo=False, timeout=timeout)
            custom_prompt = "PROMPT_>"
            child.sendline(f"prompt {custom_prompt}")
            child.expect(custom_prompt)
        else:
            child = pexpect.spawn("/bin/bash", encoding="utf-8", echo=False, timeout=timeout)
            # Set a known, unique prompt
            # We use a random string that is unlikely to appear otherwise
            # so we can detect the prompt reliably.
            custom_prompt = "PEXPECT_PROMPT>> "
            child.sendline("stty -onlcr")
            child.sendline("unset PROMPT_COMMAND")
            child.sendline(f"PS1='{custom_prompt}'")
            # Force an initial read until the newly set prompt shows up
            child.expect(custom_prompt)
            return child, custom_prompt
```

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

### Get Tools Map

Source: https://tencentcloudadp.github.io/youtu-agent/ref/tool/search_toolkit

Retrieves the map of available tools, optionally filtered by activated tools.

```APIDOC
## GET /tools/map

### Description
Retrieves the available tools. If `activated_tools` is configured, only the specified tools will be returned.

### Method
GET

### Endpoint
/tools/map

### Parameters
#### Query Parameters
- **activated_tools** (list[str]) - Optional - A list of tool names to filter the results. If not provided, all available tools are returned.

### Request Example
```json
{
  "activated_tools": ["search", "web_qa"]
}
```

### Response
#### Success Response (200)
- **tools** (dict[str, Callable]) - A dictionary where keys are tool names and values are their corresponding callable functions.

#### Response Example
```json
{
  "tools": {
    "search": "<function search at 0x... >",
    "web_qa": "<function web_qa at 0x...>"
  }
}
```
```

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

### SimpleAgent Initialization (Python)

Source: https://tencentcloudadp.github.io/youtu-agent/ref/agents/simple_agent

Initializes the SimpleAgent with various configurations including agent name, instructions, model, tools, and output types. It sets up internal states and prepares for asynchronous operations.

```python
class SimpleAgent(BaseAgent):
    """A simple agent with env, tools, mcps, and context manager, wrapped on openai-agents."""

    def __init__(
        self,
        *, 
        config: AgentConfig | str | None = None,  # use config to pass agent configs
        name: str | None = None,
        instructions: str | Callable | None = None,
        model: str | Model | None = None,
        model_settings: ModelSettings | None = None,
        tools: list[Tool] = None,
        output_type: type[Any] | AgentOutputSchemaBase | None = None,
        tool_use_behavior: Literal["run_llm_again", "stop_on_first_tool"] | StopAtTools = "run_llm_again",
    ):
        self.config = self._get_config(config)
        if name:
            self.config.agent.name = name
        if instructions:
            self.config.agent.instructions = instructions
        self.model = self._get_model(self.config, model)
        self.model_settings = self._get_model_settings(self.config, model_settings)
        self.tools: list[Tool] = tools or []
        self.output_type: type[Any] | AgentOutputSchemaBase | None = output_type
        self.tool_use_behavior: Literal["run_llm_again", "stop_on_first_tool"] | StopAtTools = tool_use_behavior
        self.context_manager: BaseContextManager = None
        self.env: BaseEnv = None
        self.current_agent: Agent[TContext] = None  # move to task recorder?
        self.input_items: list[TResponseInputItem] = []

        self._run_hooks: RunHooks = None
        self._mcp_servers: list[MCPServer] = []
        self._toolkits: list[AsyncBaseToolkit] = []
        self._mcps_exit_stack = AsyncExitStack()
        self._tools_exit_stack = AsyncExitStack()
        self._initialized = False
```

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

### Python Agent Run Configuration and Context Preparation

Source: https://tencentcloudadp.github.io/youtu-agent/ref/agents/simple_agent

Prepares configuration and context for agent runs, including model settings, workflow names, and input data. This code defines helper methods for generating run configurations and context dictionaries.

```python
    def _get_run_config(self) -> RunConfig:
        run_config = RunConfig(
            model=self.current_agent.model,
            model_settings=self.config.model.model_settings,
            workflow_name=self.config.agent.name,
        )
        return run_config

    def _get_context(self) -> dict:
        return {
            "context_manager": self.context_manager,
            "env": self.env,
        }

    def _prepare_run_kwargs(self, input: str | list[TResponseInputItem]) -> dict:
        return {
            "starting_agent": self.current_agent,
            "input": input,
            "context": self._get_context(),
            "max_turns": self.config.max_turns,
            "hooks": self._run_hooks,
            "run_config": self._get_run_config(),
        }

    # wrap `Runner` apis in @openai-agents
    async def run(
        self, input: str | list[TResponseInputItem], trace_id: str = None, save: bool = False
    ) -> TaskRecorder:
        """Entrypoint for running the agent

        Args:
            trace_id: str to identify the run
            save: whether to use history (use `input_items`)
        """

```

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

### Get Response Output (Python)

Source: https://tencentcloudadp.github.io/youtu-agent/ref/utils/openai_utils

Extracts the 'output' field from an OpenAI response. It expects a Response object and returns a list of dictionaries representing the output.

```python
@staticmethod
def get_response_output(response: Response) -> list[dict]:
    """Get response output from response"""
    return response.model_dump()["output"]
```

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

### Basic SimpleAgent Usage with Custom Instructions

Source: https://tencentcloudadp.github.io/youtu-agent/agents

Shows how to instantiate `SimpleAgent` directly and override its configuration, such as providing custom instructions, in the constructor. It utilizes the `SimpleAgent` class from the `utu.agents` module and supports asynchronous context management.

```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?")
```

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

### Launch WebUI with SimpleAgent (Python)

Source: https://tencentcloudadp.github.io/youtu-agent/frontend

Demonstrates how to launch the WebUI using the WebUIChatbot class with a SimpleAgent. It requires importing necessary classes and setting up the agent and chatbot instance.

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

```

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

### Get Tool Map (Python)

Source: https://tencentcloudadp.github.io/youtu-agent/ref/tool/tabular_data_toolkit

Retrieves a dictionary mapping tool names to their corresponding callable methods. This function is part of the tabular data toolkit.

```python
async def get_tools_map(self) -> dict[str, Callable]:
    """Return a mapping of tool names to their corresponding methods."""
    return {
        # "get_tabular_columns": self.get_tabular_columns,
        # "get_column_info": self.get_column_info,
    }
```

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

### Get Column Info

Source: https://tencentcloudadp.github.io/youtu-agent/ref/tool/tabular_data_toolkit

Intelligently analyzes and interprets column information, building on get_tabular_columns to provide file structure analysis and column meaning interpretation.

```APIDOC
## GET get_column_info

### Description
Intelligently analyze and interpret column information. Builds on get_tabular_columns() to provide simple file structure analysis and column meaning interpretation.

### Method
GET

### Endpoint
/get_column_info

### Parameters
#### Query Parameters
- **file_path** (str) - Required - Path to the tabular data file.

### Request Example
```json
{
  "file_path": "/path/to/your/data.csv"
}
```

### Response
#### Success Response (200)
- **str** (str) - Analysis with file structure and column explanations.

#### Response Example
```json
{
  "response": "This file contains columns X, Y, Z. Column X appears to be an identifier... Column Y represents... Column Z is likely..."
}
```
```

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

### SearchToolkit Initialization and Configuration

Source: https://tencentcloudadp.github.io/youtu-agent/ref/tool/search_toolkit

Initializes the SearchToolkit by configuring the search engine, crawl engine, and language model based on provided configurations. It supports multiple search and crawl engine implementations.

```python
class SearchToolkit(AsyncBaseToolkit):
    """Search Toolkit

    NOTE:
        - Please configure the required env variables! See `configs/agents/tools/search.yaml`

    Methods:
        - search(query: str, num_results: int = 5)
        - web_qa(url: str, query: str)
    """

    def __init__(self, config: ToolkitConfig = None):
        super().__init__(config)
        search_engine = self.config.config.get("search_engine", "google")
        match search_engine:
            case "google":
                from .search.google_search import GoogleSearch

                self.search_engine = GoogleSearch(self.config.config)
            case "jina":
                from .search.jina_search import JinaSearch

                self.search_engine = JinaSearch(self.config.config)
            case "baidu":
                from .search.baidu_search import BaiduSearch

                self.search_engine = BaiduSearch(self.config.config)
            case "duckduckgo":
                from .search.duckduckgo_search import DuckDuckGoSearch

                self.search_engine = DuckDuckGoSearch(self.config.config)
            case _:
                raise ValueError(f"Unsupported search engine: {search_engine}")
        crawl_engine = self.config.config.get("crawl_engine", "jina")
        match crawl_engine:
            case "jina":
                from .search.jina_crawl import JinaCrawl

                self.crawl_engine = JinaCrawl(self.config.config)
            case "crawl4ai":
                from .search.crawl4ai_crawl import Crawl4aiCrawl

                self.crawl_engine = Crawl4aiCrawl(self.config.config)
            case _:
                raise ValueError(f"Unsupported crawl engine: {crawl_engine}")
        # llm for web_qa
        self.llm = SimplifiedAsyncOpenAI(
            **self.config.config_llm.model_provider.model_dump() if self.config.config_llm else {}
        )
        self.summary_token_limit = self.config.config.get("summary_token_limit", 1_000)
```

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

### Get Tabular Columns

Source: https://tencentcloudadp.github.io/youtu-agent/ref/tool/tabular_data_toolkit

Extracts raw column metadata, including names, data types, and sample values, directly from tabular data files.

```APIDOC
## GET get_tabular_columns

### Description
Extract raw column metadata from tabular data files. Directly reads file and returns basic column information: column names, data types, and sample values.

### Method
GET

### Endpoint
/get_tabular_columns

### Parameters
#### Query Parameters
- **file_path** (str) - Required - Path to the tabular data file.
- **return_feat** (list[str]) - Optional - A list of features to return.

### Request Example
```json
{
  "file_path": "/path/to/your/data.csv",
  "return_feat": ["column1", "column2"]
}
```

### Response
#### Success Response (200)
- **str** (str) - Formatted string with raw column information.

#### Response Example
```json
{
  "response": "[Column Name: col1, Type: int64, Sample: 10]\n[Column Name: col2, Type: object, Sample: sample_text]"
}
```
```

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

### Get Current Browser State - Python

Source: https://tencentcloudadp.github.io/youtu-agent/ref/env/browser_env

Retrieves the current state of the browser environment, which is stored in the 'browser_state' attribute. This method returns the state as a string.

```Python
def get_state(self) -> str:
    """Get the current state of the environment."""
    return self.browser_state
```

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

### LangChain ZeroShotAgent Implementation

Source: https://tencentcloudadp.github.io/youtu-agent/examples_output/deep_research

Demonstrates the implementation of the ZeroShotAgent in LangChain, a pattern that leverages LLMs for tool use through a chain-of-thought process. This snippet shows how to initialize the agent with an LLM and a set of tools.

```python
from langchain.agents import ZeroShotAgent

# Assuming 'llm' is an initialized LLM object and 'tools' is a list of tools
agent = ZeroShotAgent.from_llm_and_tools(llm, tools)
```

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

### Get Tools Map (Python)

Source: https://tencentcloudadp.github.io/youtu-agent/ref/tool/tabular_data_toolkit

This asynchronous function returns a dictionary mapping tool names to their corresponding methods. It is intended for lazy loading of tool functionalities.

```python
async def get_tools_map(self) -> dict[str, Callable]:
        """Return a mapping of tool names to their corresponding methods."""
        return {
            # "get_tabular_columns": self.get_tabular_columns,
            # "get_column_info": self.get_column_info,
        }
```

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

### Initialize VideoToolkit

Source: https://tencentcloudadp.github.io/youtu-agent/ref/tool/video_toolkit

Initializes the VideoToolkit with configuration, setting up a client for the Gemini API. It requires a ToolkitConfig object and specifies the API version.

```python
class VideoToolkit(AsyncBaseToolkit):
    def __init__(self, config: ToolkitConfig = None) -> None:
        super().__init__(config)
        self.client = genai.Client(
            api_key=self.config.config.get("google_api_key"), http_options=HttpOptions(api_version="v1alpha")
        )
        self.model = self.config.config.get("google_model")
```

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

### Initialize TabularDataToolkit

Source: https://tencentcloudadp.github.io/youtu-agent/ref/tool/tabular_data_toolkit

Initializes the TabularDataToolkit with an optional configuration. It sets up an asynchronous LLM client for processing.

```python
class TabularDataToolkit(AsyncBaseToolkit):
    def __init__(self, config: ToolkitConfig = None):
        super().__init__(config)
        self.llm = SimplifiedAsyncOpenAI(
            **self.config.config_llm.model_provider.model_dump() if self.config.config_llm else {}
        )
```

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

### Get Tools in MCP Format

Source: https://tencentcloudadp.github.io/youtu-agent/ref/tool/bash_toolkit

Fetches tools formatted for MCP (Machine Conversation Platform). It utilizes `get_tools_in_agents` to obtain tools in the agent format and then converts them using `MCPConverter.function_tool_to_mcp`.

```python
from typing import Callable, Dict, List, Any

# Mock classes for demonstration
class FunctionTool:
    def __init__(self, func: Callable, strict_mode: bool):
        self.func = func
        self.strict_mode = strict_mode

class MCPConverter:
    @staticmethod
    def function_tool_to_mcp(tool: FunctionTool) -> Any: # Using Any as the return type for Tool is not defined
        # Mock conversion logic
        return {"name": tool.func.__name__, "description": "MCP description"}

class BaseTools:
    def __init__(self, config: Any, tools_map: Dict[str, Callable]):
        self.config = config
        self.tools_map = tools_map

    async def get_tools_map_func(self) -> Dict[str, Callable]:
        # Mock implementation
        return self.tools_map

    async def get_tools_in_agents(self) -> List[FunctionTool]:
        # Mock implementation
        return [FunctionTool(func, False) for func in self.tools_map.values()]

    async def get_tools_in_mcp(self) -> List[Any]: # Using Any as the return type for Tool is not defined
        """Get tools in MCP format."""
        tools = await self.get_tools_in_agents()
        return [MCPConverter.function_tool_to_mcp(tool) for tool in tools]

```

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

### SimpleAgent Configuration Loading (Python)

Source: https://tencentcloudadp.github.io/youtu-agent/ref/agents/simple_agent

Helper method to load agent configuration. It accepts either an AgentConfig object or a string path to a configuration file.

```python
    def _get_config(self, config: AgentConfig | str | None) -> AgentConfig:
        if isinstance(config, AgentConfig):
            return config
        return ConfigLoader.load_agent_config(config or "base")
```

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

### Get Tools in Agents Format

Source: https://tencentcloudadp.github.io/youtu-agent/ref/tool/bash_toolkit

Formats available tools into the 'openai-agents' format. It first retrieves the tool map and then converts each tool into a FunctionTool object, disabling strict mode.

```python
from typing import Callable, Dict, List, Any

# Mock classes for demonstration
class FunctionTool:
    def __init__(self, func: Callable, strict_mode: bool):
        self.func = func
        self.strict_mode = strict_mode

def function_tool(func: Callable, strict_mode: bool) -> FunctionTool:
    return FunctionTool(func, strict_mode)

class BaseTools:
    def __init__(self, config: Any, tools_map: Dict[str, Callable]):
        self.config = config
        self.tools_map = tools_map

    async def get_tools_map_func(self) -> Dict[str, Callable]:
        # Mock implementation
        return self.tools_map

    async def get_tools_in_agents(self) -> List[FunctionTool]:
        """Get tools in openai-agents format."""
        tools_map = await self.get_tools_map_func()
        tools = []
        for _, tool in tools_map.items():
            tools.append(
                function_tool(
                    tool,
                    strict_mode=False,  # turn off strict mode
                )
            )
        return tools

```

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

### SimpleAgent Asynchronous Entry (Python)

Source: https://tencentcloudadp.github.io/youtu-agent/ref/agents/simple_agent

Enters the asynchronous context for the agent, ensuring it is properly built before use.

```python
    async def __aenter__(self):
        await self.build()
        return self
```

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

### Load Evaluation Configuration using ConfigLoader in Python

Source: https://tencentcloudadp.github.io/youtu-agent/ref/config/loader

This method loads the configuration for evaluation tasks. It ensures the name starts with 'eval/' and retrieves the configuration from the main configs directory.

```python
@classmethod
def load_eval_config(cls, name: str = "default") -> EvalConfig:
    """Load eval config"""
    if not name.startswith("eval/"):
        name = "eval/" + name
    cfg = cls._load_config_to_dict(name, config_path="../../configs")
    return EvalConfig(**cfg)

```