youtu-agent 0.1.2__py3-none-any.whl

utils/sqlmodel_utils.py

@@ -0,0 +1,95 @@
+from sqlmodel import Session, create_engine, text
+
+from .env import EnvUtils
+from .log import get_logger
+
+logger = get_logger(__name__)
+
+
+class SQLModelUtils:
+    _engine = None  # singleton
+    _db_available = None  # cache for database availability check
+    _last_check_time = None  # timestamp of last check
+
+    @classmethod
+    def get_engine(cls):
+        if cls._engine is None:
+            cls._engine = create_engine(
+                EnvUtils.get_env("UTU_DB_URL"),  # assert UTU_DB_URL is provided here!
+                pool_size=300,
+                max_overflow=500,
+                pool_timeout=30,
+                pool_pre_ping=True,
+            )
+            # Ensure DB schema/tables exist on first engine init
+            try:
+                cls._init_db_schema(cls._engine)
+            except Exception as e:
+                logger.warning(f"Auto schema creation skipped due to error: {e}")
+        return cls._engine
+
+    @staticmethod
+    def create_session():
+        return Session(SQLModelUtils.get_engine())
+
+    @classmethod
+    def check_db_available(cls, force_check: bool = False, cache_ttl: int = 60) -> bool:
+        """Check if database is available with caching.
+
+        Args:
+            force_check: Force a fresh check, bypassing cache
+            cache_ttl: Cache time-to-live in seconds (default: 60s)
+
+        Returns:
+            bool: True if database is available, False otherwise
+        """
+        import time
+
+        # Return cached result if available and not expired
+        if not force_check and cls._db_available is not None and cls._last_check_time is not None:
+            if time.time() - cls._last_check_time < cache_ttl:
+                logger.debug(f"Using cached DB availability status: {cls._db_available}")
+                return cls._db_available
+
+        # Perform actual check
+        logger.debug("Performing fresh database availability check")
+
+        if not EnvUtils.get_env("UTU_DB_URL", ""):
+            cls._db_available = False
+            cls._last_check_time = time.time()
+            return False
+
+        try:
+            engine = cls.get_engine()
+            with engine.connect() as conn:
+                conn.execute(text("SELECT 1"))
+            cls._db_available = True
+            cls._last_check_time = time.time()
+            logger.debug("Database is available")
+            return True
+        except Exception as e:
+            cls._db_available = False
+            cls._last_check_time = time.time()
+            logger.error(f"Database connection failed: {e}")
+            return False
+
+    @staticmethod
+    def _init_db_schema(engine):
+        """
+        Import all SQLModel table definitions and create tables if they do not exist.
+        """
+        # Import models so SQLModel knows about all tables
+        try:
+            # Core models registered here
+            from utu.db import eval_datapoint, tool_cache_model, tracing_model, trajectory_model  # noqa: F401
+        except Exception as e:
+            logger.debug(f"Model import warning (non-fatal): {e}")
+
+        # Create tables if not exist
+        try:
+            from sqlmodel import SQLModel
+
+            SQLModel.metadata.create_all(engine)
+            logger.info("Database schema ensured (tables created if missing).")
+        except Exception as e:
+            logger.warning(f"SQLModel metadata create_all failed: {e}")

utils/token.py

@@ -0,0 +1,21 @@
+import tiktoken
+
+_tokenizer = tiktoken.get_encoding("cl100k_base")
+
+
+class TokenUtils:
+    @staticmethod
+    def truncate_text_by_token(text: str, limit: int = -1) -> str:
+        """Truncate text to a given token limit with tiktoken."""
+        if limit <= 0 or not text:
+            return text
+        tokens = _tokenizer.encode(text)
+        if len(tokens) <= limit:
+            return text
+        truncated_tokens = tokens[:limit]
+        truncated_text = _tokenizer.decode(truncated_tokens)
+        return truncated_text + "..."
+
+    @staticmethod
+    def count_tokens(text: str) -> int:
+        return len(_tokenizer.encode(text))

utils/tool_cache.py

@@ -0,0 +1,121 @@
+import functools
+import hashlib
+import json
+import pathlib
+import time
+from datetime import datetime
+from typing import Literal
+
+from sqlmodel import select
+
+from ..db import ToolCacheModel
+from ..utils import EnvUtils, SQLModelUtils, get_logger
+from .path import DIR_ROOT
+
+logger = get_logger(__name__)
+
+DIR_CACHE = DIR_ROOT / ".cache"
+DIR_CACHE.mkdir(exist_ok=True)
+
+USE_CACHE = EnvUtils.get_env("UTU_DISABLE_TOOL_CACHE", "").lower() not in ("true", "1")
+
+
+def create_cached_file(cache_path: pathlib.Path, expire_time: int | None = None):
+    def decorator_file(func):
+        @functools.wraps(func)
+        async def wrapper(*args, **kwargs):
+            func_name = func.__name__
+            cache_args = args[1:] if args and hasattr(args[0], func.__name__) else args  # remove `self`
+            args_str = str(cache_args) + str(sorted(kwargs.items()))
+            cache_key = hashlib.md5(args_str.encode()).hexdigest()
+            cache_file = cache_path / f"{func_name}" / f"{func_name}_{cache_key}.json"
+            cache_file.parent.mkdir(exist_ok=True, parents=True)
+
+            if USE_CACHE and cache_file.exists():
+                with open(cache_file) as f:
+                    cache_data = json.load(f)
+
+                if expire_time is None or (time.time() - cache_data["metadata"]["timestamp"]) < expire_time:
+                    logger.debug(f"🔄 Using cached result for {func_name} from {cache_file}")
+                    return cache_data["result"]
+
+            start_time = time.time()
+            result = await func(*args, **kwargs)
+            execution_time = time.time() - start_time
+            metadata = {
+                "function": func_name,
+                "timestamp": time.time(),
+                "datetime": datetime.now().isoformat(),
+                "args": str(cache_args),
+                "kwargs": str(kwargs),
+                "execution_time": execution_time,
+            }
+            cache_data = {"result": result, "metadata": metadata}
+
+            with open(cache_file, "w") as f:
+                json.dump(cache_data, f, ensure_ascii=False, indent=2)
+            logger.debug(f"💾 Cached result for {func_name} to {cache_file}")
+            return result
+
+        return wrapper
+
+    return decorator_file
+
+
+def create_cached_db(expire_time: int | None = None):
+    def decorator_db(func):
+        @functools.wraps(func)
+        async def wrapper(*args, **kwargs):
+            func_name = func.__name__
+            cache_args = args[1:] if args and hasattr(args[0], func.__name__) else args  # remove `self`
+            args_str = str(cache_args) + str(sorted(kwargs.items()))
+            cache_key = hashlib.md5(args_str.encode()).hexdigest()
+
+            with SQLModelUtils.create_session() as session:
+                if USE_CACHE:
+                    stmt = select(ToolCacheModel).where(
+                        ToolCacheModel.function == func_name, ToolCacheModel.cache_key == cache_key
+                    )
+                    if_exist = session.exec(stmt).first()  # one_or_none
+                    if if_exist and (expire_time is None or (time.time() - if_exist.timestamp) < expire_time):
+                        logger.debug(f"🔄 Using cached result for {func_name} from db")
+                        return if_exist.result
+
+                start_time = time.time()
+                result = await func(*args, **kwargs)
+                execution_time = time.time() - start_time
+                data = ToolCacheModel(
+                    function=func_name,
+                    args=args_str,
+                    kwargs=str(kwargs),
+                    result=result,
+                    cache_key=cache_key,
+                    execution_time=execution_time,
+                    timestamp=time.time(),
+                    datetime=datetime.now().isoformat(),
+                )
+                session.add(data)
+                session.commit()
+                logger.debug(f"💾 Cached result for {func_name} to db")
+                return result
+
+        return wrapper
+
+    return decorator_db
+
+
+def async_file_cache(
+    cache_dir: str | pathlib.Path = DIR_CACHE, expire_time: int | None = None, mode: Literal["db", "file"] = "db"
+):
+    """Decorator to cache async function results to local files.
+
+    Args:
+        cache_dir (str|pathlib.Path): Directory to store cache files
+        expire_time (Optional[int]): Cache expiration time in seconds, None means no expiration
+    """
+    cache_path = pathlib.Path(cache_dir)
+    cache_path.mkdir(exist_ok=True, parents=True)
+    if mode == "db" and SQLModelUtils.check_db_available():
+        return create_cached_db(expire_time)
+    else:
+        return create_cached_file(cache_path, expire_time)

youtu_agent-0.1.2.dist-info/METADATA

@@ -0,0 +1,439 @@
+Metadata-Version: 2.4
+Name: youtu-agent
+Version: 0.1.2
+Summary: Youtu-Agent is a simple but powerful framework for building, running, and evaluating agents.
+Project-URL: Homepage, https://github.com/TencentCloudADP/youtu-agent
+Project-URL: Documentation, https://tencentcloudadp.github.io/youtu-agent/
+Project-URL: Repository, https://github.com/TencentCloudADP/youtu-agent
+Author-email: easonsshi <easonsshi@tencent.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,ai,automation,llm
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.12
+Requires-Dist: aiofiles>=24.1.0
+Requires-Dist: aiohttp>=3.12.15
+Requires-Dist: art>=6.5
+Requires-Dist: arxiv>=2.2.0
+Requires-Dist: chunkr-ai>=0.1.0
+Requires-Dist: colorlog>=6.9.0
+Requires-Dist: docker>=7.1.0
+Requires-Dist: google-genai>=1.26.0
+Requires-Dist: hydra-core>=1.3.2
+Requires-Dist: ipython>=9.5.0
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: matplotlib>=3.10.3
+Requires-Dist: mcp>=1.12.3
+Requires-Dist: openai-agents==0.3.3
+Requires-Dist: openinference-instrumentation-openai-agents>=1.1.1
+Requires-Dist: openinference-instrumentation-openai>=0.1.30
+Requires-Dist: openpyxl>=3.1.5
+Requires-Dist: pandas>=2.3.0
+Requires-Dist: pexpect>=4.9.0
+Requires-Dist: prompt-toolkit>=3.0.52
+Requires-Dist: psycopg2-binary>=2.9.10
+Requires-Dist: python-pptx>=1.0.2
+Requires-Dist: requests>=2.32.4
+Requires-Dist: rich>=14.1.0
+Requires-Dist: sqlmodel>=0.0.24
+Requires-Dist: tiktoken>=0.9.0
+Requires-Dist: toml>=0.10.2
+Requires-Dist: wikipedia-api>=0.8.1
+Provides-Extra: litllm
+Requires-Dist: litellm>=1.77.0; extra == 'litllm'
+Description-Content-Type: text/markdown
+
+# <img src="docs/assets/logo.svg" alt="Youtu-agent Logo" height="24px"> Youtu-Agent: A simple yet powerful agent framework that delivers with open-source models
+
+<div align="center">
+<a href="https://tencentcloudadp.github.io/youtu-agent/"><img src=https://img.shields.io/badge/📖-Documentation-blue.svg></a>
+<!-- <a href=https://arxiv.org/abs/2502.14345><img src=https://img.shields.io/badge/arXiv-2502.14345-b31b1b.svg></a> -->
+<a href=https://github.com/TencentCloudADP/youtu-agent><img src=https://img.shields.io/badge/GitHub-Tencent-blue.svg></a>
+<a href=https://deepwiki.com/TencentCloudADP/youtu-agent><img src=https://img.shields.io/badge/DeepWiki-Tencent-blue.svg></a>
+<a href=https://arxiv.org/abs/2510.08191><img src=https://img.shields.io/badge/arXiv-2510.08191-b31b1b.svg></a>
+</div>
+
+<p align="center">
+| <a href="README_ZH.md"><b>中文</b></a>
+| <a href="README_JA.md"><b>日本語</b></a>
+| <a href="#-benchmark-performance"><b>🌟 Performance</b></a> 
+| <a href="#-examples"><b>💡 Examples</b> </a> 
+| <a href="#-features"><b>✨ Features</b> </a> 
+| <a href="#-getting-started"><b>🚀 Getting Started</b> </a> 
+| 📢 <a href="https://discord.gg/QjqhkHQVVM"><b>Join Discord</b></a> or <a href="https://github.com/user-attachments/assets/354cd8e7-e108-4348-9355-04440052f408"><b>WeChat</b></a> 
+|
+</p>
+
+
+`Youtu-Agent` is a flexible, high-performance framework for building, running, and evaluating autonomous agents. Beyond topping the benchmarks, this framework delivers powerful agent capabilities, e.g. data analysis, file processing, and deep research, all with open-source models.
+
+<img src="docs/assets/mascot.png" alt="Youtu-agent Logo" width="200" align="left" style="margin-right:20px;">
+
+Key highlights:
+- **Verified performance**: Achieved 71.47% on WebWalkerQA (pass@1) and 72.8% on GAIA (text-only subset, pass@1), using purely `DeepSeek-V3` series models (without Claude or GPT), establishing a strong open-source starting point.
+- **Open-source friendly & cost-aware**: Optimized for accessible, low-cost deployment without reliance on closed models.
+- **Practical use cases**: Out-of-the-box support for tasks like CSV analysis, literature review, personal file organization, and podcast and video generation (coming soon).
+- **Flexible architecture**: Built on [openai-agents](https://github.com/openai/openai-agents-python), with extensible support for diverse model APIs (form `DeepSeek` to `gpt-oss`), tool integrations, and framework implementations.
+- **Automation & simplicity**: YAML-based configs, auto agent generation, and streamlined setup reduce manual overhead.
+
+## 🗞️ News
+
+- 🚀 [2025-10-10] [**Training-Free Group Relative Policy Optimization**](https://arxiv.org/abs/2510.08191). RL for DeepSeek-V3.2 at $8? Yes, it’s possible! Training-free GRPO keeps DeepSeek-V3.2 frozen, learns a token prior from ~100 samples for ~$8 RL runs, delivers verified math and web search gains! [code in branch [training_free_GRPO](https://github.com/TencentCloudADP/youtu-agent/tree/training_free_GRPO)] [[x thread](https://x.com/cai_cecilia47/status/1976558824640393559)].
+- 🛠️ [2025-09-28] Agent auto-generation now ships with companion tooling: describe a capability once and let `Youtu-Agent` build the tool for you. [[details](https://tencentcloudadp.github.io/youtu-agent/auto_generation/)].
+- 📺 [2025-09-09] We hosted a live sharing the design philosophy and basic usage of `Youtu-Agent`. [[video](https://www.bilibili.com/video/BV1mypqz4EvS)] [[documentation](https://doc.weixin.qq.com/doc/w3_AcMATAZtAPICNLgt3CbnxRWaYWnW4)].
+- 🎁 [2025-09-02] [Tencent Cloud International](https://www.tencentcloud.com/) offers new users of the DeepSeek API **3 million free tokens** (**Sep 1 – Oct 31, 2025**). [Try it out](https://www.tencentcloud.com/document/product/1255/70381) for free if you want to use DeepSeek models in `Youtu-Agent`! For enterprise agent solutions, also check out [Agent Development Platform](https://adp.tencentcloud.com) (ADP).
+- 📺 [2025-08-28] We hosted a live sharing updates about DeepSeek-V3.1 and how to use it in the `Youtu-Agent` framework. [[video](https://www.bilibili.com/video/BV1XwayzrETi/)] [[documentation](https://doc.weixin.qq.com/doc/w3_AcMATAZtAPICNvcLaY5FvTOuo7MwF)].
+
+## 🌟 Benchmark Performance
+
+`Youtu-Agent` is built on open-source models and lightweight tools, demonstrating strong results on challenging deep search and tool use benchmarks.
+
+- **[WebWalkerQA](https://huggingface.co/datasets/callanwu/WebWalkerQA)**: Achieved 60.71% accuracy with `DeepSeek-V3-0324`， using new released `DeepSeek-V3.1` can further improve to 71.47%, setting a new SOTA performance.
+- **[GAIA](https://gaia-benchmark-leaderboard.hf.space/)**: Achieved 72.8% pass@1 on the [text-only validation subset](https://github.com/sunnynexus/WebThinker/blob/main/data/GAIA/dev.json) using `DeepSeek-V3-0324` (including models used within tools). We are actively extending evaluation to the full GAIA benchmark with multimodal tools, and will release the trajectories in the near future. Stay tuned! ✨
+
+![WebWalkerQA](docs/assets/images/benchmark_webwalkerqa.png)
+
+## 💡 Examples
+
+Click on the images to view detailed videos.
+
+<table>
+  <tr>
+    <td style="border: 1px solid black; padding: 10px; width: 50%; vertical-align: top;">
+      <strong>Data Analysis</strong><br>Analyzes a CSV file and generates an HTML report.
+    </td>
+    <td style="border: 1px solid black; padding: 10px; width: 50%; vertical-align: top;">
+      <strong>File Management</strong><br>Renames and categorizes local files for the user.
+    </td>
+  </tr>
+  <tr>
+    <td style="border: 1px solid black; padding: 10px; width: 50%; vertical-align: top;">
+      <video src="https://github.com/user-attachments/assets/60193435-b89d-47d3-8153-5799d6ff2920" 
+             poster="https://img.youtube.com/vi/r9we4m1cB6M/sddefault.jpg" 
+             controls muted preload="metadata" 
+             width="100%" height="300"
+             style="object-fit: cover; border-radius: 8px;"></video>
+    </td>
+    <td style="border: 1px solid black; padding: 10px; width: 50%; vertical-align: top;">
+      <video src="https://github.com/user-attachments/assets/dbb9cfc6-3963-4264-ba93-9ba21c5a579e" 
+             poster="https://img.youtube.com/vi/GdA4AapE2L4/sddefault.jpg" 
+             controls muted preload="metadata" 
+             width="100%" height="300"
+             style="object-fit: cover; border-radius: 8px;"></video>
+    </td>
+  </tr>
+  <tr >
+    <td style="border: 1px solid black; padding: 10px; width: 50%; vertical-align: top;">
+      <strong>Wide Research</strong><br>Gathers extensive information to generate a comprehensive report, replicating the functionality of Manus.
+    </td>
+    <td style="border: 1px solid black; padding: 10px; width: 50%; vertical-align: top;">
+      <strong>Paper Analysis</strong><br>Parses a given paper, performs analysis, and compiles related literature to produce a final result.
+    </td>
+  </tr>
+  <tr>
+    <td style="border: 1px solid black; padding: 10px; width: 50%; vertical-align: top;">
+      <video src="https://github.com/user-attachments/assets/6fc75814-e565-4f94-9ab5-33e3e7788e92" 
+             poster="https://img.youtube.com/vi/v3QQg0WAnPs/sddefault.jpg" 
+             controls muted preload="metadata" 
+             width="100%" height="300"
+             style="object-fit: cover; border-radius: 8px;"></video>
+    </td>
+    <td style="border: 1px solid black; padding: 10px; width: 50%; vertical-align: top;">
+      <video src="https://github.com/user-attachments/assets/09b24f94-30f0-4e88-9aaf-9f3bbf82e99d" 
+             poster="https://img.youtube.com/vi/vBddCjjRk00/sddefault.jpg" 
+             controls muted preload="metadata" 
+             width="100%" height="300"
+             style="object-fit: cover; border-radius: 8px;"></video>
+    </td>
+  </tr>
+</table>
+
+> [!NOTE]
+> See the [`examples`](./examples) directory and [documentation](https://tencentcloudadp.github.io/youtu-agent/examples/) for more details.
+
+### 🤖 Automatic Tool and Agent Generation
+
+A standout feature of `Youtu-Agent` is its ability to **automatically generate tools alongside agent configurations**. Other frameworks often make you hand-code functions or hand-craft prompts before an agent can even run. Here, you simply describe the task: the built-in meta-agent interviews you, assembles the necessary tools, produces YAML configs, and saves everything so you can execute it immediately.
+
+```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
+```
+
+<table>
+  <tr>
+    <td style="border: 1px solid black; padding: 10px; width: 50%; vertical-align: top;">
+      <strong>Automatic Agent Generation</strong><br>Interactively clarify your requirements, automatically generate the agent configuration, and run it right away.
+    </td>
+    <td style="border: 1px solid black; padding: 10px; width: 50%; vertical-align: top;">
+      <strong>Automatic Tool Generation</strong><br>Describe the behaviors you need, let the meta-agent draft tool code and schemas, then drop them straight into your workflow.
+    </td>
+  </tr>
+  <tr>
+    <td style="border: 1px solid black; padding:10px; vertical-align:top; width: 400px;">
+      <video src="https://github.com/user-attachments/assets/0c2ee833-507e-4141-8de4-148ff3d9f9ef" 
+             poster="https://img.youtube.com/vi/JVpHDJtKBo8/maxresdefault.jpg" 
+             controls muted preload="metadata" 
+             width="100%" height="auto" 
+             style="object-fit: cover; border-radius: 8px;"></video>
+    </td>
+    <td style="border: 1px solid black; padding:10px; vertical-align:top; width: 400px;">
+      <video src="https://github.com/user-attachments/assets/37878544-cfda-4a8a-9b42-a7361782c750" 
+             poster="https://img.youtube.com/vi/zjGooBuqdSE/maxresdefault.jpg" 
+             controls muted preload="metadata" 
+             width="100%" height="auto" 
+             style="object-fit: cover; border-radius: 8px;"></video>
+    </td>
+  </tr>
+</table>
+
+> [!NOTE]
+> See [documentation](https://tencentcloudadp.github.io/youtu-agent/auto_generation/) for more details.
+
+## ✨ Features
+
+![features](docs/assets/images/header.png)
+
+### Design Philosophy
+- **Minimal design**: We try to keep the framework simple and easy to use, avoiding unnecessary overhead.
+- **Modular & configurable**: Flexible customization and easy integration of new components.
+- **Open-source model support & low-cost**: Promotes accessibility and cost-effectiveness for various applications.
+
+### Core Features
+- **Built on openai-agents**: Leveraging the foundation of [openai-agents](https://github.com/openai/openai-agents-python) SDK, our framework inherits streaming, tracing, and agent-loop capabilities, ensuring compatibility with both `responses` and `chat.completions` APIs for seamless adaptation to diverse models like [gpt-oss](https://github.com/openai/gpt-oss).
+- **Fully asynchronous**: Enables high-performance and efficient execution, especially beneficial for evaluating benchmarks.
+- **Tracing & analysis system**: Beyond OTEL, our `DBTracingProcessor` system provides in-depth analysis of tool calls and agent trajectories. (will be released soon)
+
+### Automation
+- **YAML based configuration**: Structured and easily manageable agent configurations.
+- **Automatic agent generation**: Based on user requirements, agent configurations can be automatically generated.
+- **Tool generation & optimization**: Tool evaluation and automated optimization, and customized tool generation will be supported in the future.
+
+### Use Cases
+- **Deep / Wide research**: Covers common search-oriented tasks.
+- **Webpage generation**: Examples include generating web pages based on specific inputs.
+- **Trajectory collection**: Supports data collection for training and research purposes.
+
+
+## 🤔 Why Choose Youtu-Agent?
+
+`Youtu-Agent` is designed to provide significant value to different user groups:
+
+### For Agents Researchers & LLM Trainers
+- A **simple yet powerful baseline** that is stronger than basic ReAct, serving as an excellent starting point for model training and ablation studies.
+- **One-click evaluation scripts** to streamline the experimental process and ensure consistent benchmarking.
+
+### For Agent Application Developers
+- A **proven and portable scaffolding** for building real-world agent applications.
+- **Ease of Use**: Get started quickly with simple scripts and a rich set of built-in toolkits.
+- **Modular Design**: Key components like `Environment` and `ContextManager` are encapsulated yet highly customizable.
+
+### For AI & Agent Enthusiasts
+- **Practical Use Cases**: The `/examples` directory includes tasks like deep research report generation, data analysis, and personal file organization.
+- **Simplicity & Debuggability**: A rich toolset and visual tracing tools make development and debugging intuitive and straightforward.
+
+
+## 🧩 Core Concepts
+
+- **Agent**: An LLM configured with specific prompts, tools, and an environment.
+- **Toolkit**: An encapsulated set of tools that an agent can use.
+- **Environment**: The world in which the agent operates (e.g., a browser, a shell).
+- **ContextManager**: A configurable module for managing the agent's context window.
+- **Benchmark**: An encapsulated workflow for a specific dataset, including preprocessing, rollout, and judging logic.
+
+For more design and implementation details, please refer to our [technical documentation](https://tencentcloudadp.github.io/youtu-agent/).
+
+## 🚀 Getting Started
+
+Youtu-Agent provides complete code and examples to help you get started quickly. Follow the steps below to run your first agent, or refer to [`docker/README.md`](./docker/README.md) for a streamlined Docker-based setup with interactive frontend.
+
+### Setup
+
+#### Source Code Deployment
+
+> [!NOTE]
+> The project requires Python 3.12+. We recommend using [uv](https://github.com/astral-sh/uv) for dependency management.
+
+First, make sure Python and uv are installed.
+
+Then clone the repository and sync dependencies:
+
+```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  # NOTE: You should then config the necessary API keys.
+```
+
+After copying the `.env.example` file, you need to fill in the necessary keys in the `.env` file, e.g. LLM API keys. For example:
+
+```bash
+# llm requires OpenAI API format compatibility
+# setup your LLM config , ref https://api-docs.deepseek.com/
+UTU_LLM_TYPE=chat.completions
+UTU_LLM_MODEL=deepseek-chat
+UTU_LLM_BASE_URL=https://api.deepseek.com/v1
+UTU_LLM_API_KEY=replace-to-your-api-key
+```
+
+> [Tencent Cloud International](https://www.tencentcloud.com/) offers new users of the DeepSeek API **3 million free tokens** (**Sep 1 – Oct 31, 2025**). [Try it out](https://www.tencentcloud.com/document/product/1255/70381) for free. Once you’ve applied, replace the API key in the .env file below:
+
+```bash
+# llm
+# setup your LLM config , ref https://www.tencentcloud.com/document/product/1255/70381
+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=replace-with-your-api-key
+```
+
+#### Docker Deployment
+
+Please refer to [`docker/README.md`](./docker/README.md) for a streamlined Docker-based setup with interactive frontend.
+
+### Quick Start
+
+Youtu-agent ships with built-in configurations. For example, the config `configs/agents/simple/base_search.yaml` defines a simple agent equipped with a search tool:
+
+```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."
+```
+
+You can launch an interactive CLI chatbot with this agent by running:
+
+```bash
+# 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
+```
+
+📖 More details: [Quickstart Documentation](https://tencentcloudadp.github.io/youtu-agent/quickstart)
+
+### Explore More Examples
+
+The repository provides multiple ready-to-use examples. Some examples require the agent to have internet search capabilities, so you’ll need to configure the tool APIs in the `.env` file under the tools module:
+
+```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>
+```
+
+For example, to enable the agent to automatically search online for information and generate an SVG image on the topic of “DeepSeek V3.1 New Features,” run the following command:
+
+```bash
+python examples/svg_generator/main.py
+```
+
+If you want to visualize the agent’s runtime status using the web UI, download the frontend package from the Youtu-Agent releases and install it locally:
+
+```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
+```
+
+Next, run the web version of the SVG image generation command:
+
+```bash
+python examples/svg_generator/main_web.py
+```
+
+Once the terminal shows the following message, the deployment is successful. You can access the project by clicking the local link:
+
+```bash
+Server started at http://127.0.0.1:8848/
+```
+
+![svg_generator_ui](https://github.com/user-attachments/assets/337d327f-91ee-434e-bbcf-297dd4b26c28)
+
+Given a research topic, the agent will automatically search the web, collect relevant information, and output an SVG visualization.
+
+![svg_generator_result](https://github.com/user-attachments/assets/41aa7348-5f02-4daa-b5b2-225e35d21067)
+
+📖 Learn more: [Examples Documentation](https://tencentcloudadp.github.io/youtu-agent/examples)
+
+### Run Evaluations
+
+Youtu-Agent also supports benchmarking on standard datasets. For example, to evaluate on `WebWalkerQA`:
+
+```bash
+# Prepare dataset. This script will download and process WebWalkerQA dataset, and save it to DB.
+python scripts/data/process_web_walker_qa.py
+
+# Run evaluation with config `ww.yaml` with your custom `exp_id`. We choose the sampled small dataset `WebWalkerQA_15` for quick evaluation.
+# NOTE: `JUDGE_LLM_TYPE, JUDGE_LLM_MODEL, JUDGE_LLM_BASE_URL, JUDGE_LLM_API_KEY` should be set in `.env`. Ref `.env.full`.
+python scripts/run_eval.py --config_name ww --exp_id <your_exp_id> --dataset WebWalkerQA_15 --concurrency 5
+```
+
+Results are stored and can be further analyzed in the evaluation platform. See [Evaluation Analysis](./frontend/exp_analysis/README.md).
+
+![eval_analysis_overview](https://github.com/user-attachments/assets/4a285b9e-d096-437e-9b8e-e5bf6b1924b6)
+
+![eval_analysis_detail](https://github.com/user-attachments/assets/4ede525a-5e16-4d88-9ebb-01a7dca3aaec)
+
+📖 Learn more: [Evaluation Documentation](https://tencentcloudadp.github.io/youtu-agent/eval)
+
+## 📖 Dive Deeper
+
+After getting started, you can learn more about the framework and its capabilities through our full documentation:
+
+- 📖 **[Full Documentation](https://tencentcloudadp.github.io/youtu-agent/)**: Explore the core concepts, architecture, and advanced features.
+- 🚀 **[Quickstart Guide](https://tencentcloudadp.github.io/youtu-agent/quickstart/)**: A detailed guide to get you up and running.
+- ❓ **[FAQ](https://tencentcloudadp.github.io/youtu-agent/faq)**: Find answers to common questions and issues.
+
+## 🙏 Acknowledgements
+
+This project builds upon the excellent work of several open-source projects:
+- [openai-agents](https://github.com/openai/openai-agents-python)
+- [mkdocs-material](https://github.com/squidfunk/mkdocs-material)
+- [model-context-protocol](https://github.com/modelcontextprotocol/python-sdk)
+
+## 🙌 Contributing
+
+We welcome contributions from the community! If you'd like to help improve Youtu-Agent, please read our [**Contributing Guidelines**](./CONTRIBUTING.md) to get started.
+
+## 📚 Citation
+
+If you find this work useful, please consider citing:
+
+```bibtex
+@misc{training_free_grpo,
+      title={Training-Free Group Relative Policy Optimization}, 
+      author={Tencent Youtu Lab},
+      year={2025},
+      eprint={2510.08191},
+      archivePrefix={arXiv},
+      primaryClass={cs.CL},
+      url={https://arxiv.org/abs/2510.08191}, 
+}
+
+@misc{youtu-agent-2025,
+  title={Youtu-agent: A Simple yet Powerful Agent Framework},
+  author={Tencent Youtu Lab},
+  year={2025},
+  publisher = {GitHub},
+  journal = {GitHub repository},
+  howpublished = {\url{https://github.com/TencentCloudADP/youtu-agent}},
+}
+```