{
  "nbformat": 4,
  "nbformat_minor": 0,
  "metadata": {
    "colab": {
      "provenance": []
    },
    "kernelspec": {
      "name": "python3",
      "display_name": "Python 3"
    },
    "language_info": {
      "name": "python"
    }
  },
  "cells": [
    {
      "cell_type": "markdown",
      "source": [
        "# 🤖 AgentPro Custom Tool Integration\n",
        "\n",
        "This notebook will walk you through how to set up and use [**AgentPro**](https://github.com/traversaal-ai/AgentPro) — a production-ready open-source agent framework built by [Traversaal.ai](https://traversaal.ai) for building powerful, modular, and multi-functional AI agents.\n",
        "\n",
        "### What is AgentPro?\n",
        "AgentPro lets you build intelligent agents that can:\n",
        "- Use language models (like OpenAI’s GPT) as reasoning engines\n",
        "- Combine multiple tools (code execution, web search, YouTube summarization, etc.)\n",
        "- Solve real-world tasks such as research, automation, and knowledge retrieval\n",
        "- Scale up with custom tools, memory, and orchestration features\n",
        "\n",
        "Whether you're a developer, researcher, or AI enthusiast — this guide will help you:\n",
        "- Build and integrate your own tools with AgentPro\n"
      ],
      "metadata": {
        "id": "CyxnkWVzhqOi"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "## Step 1: Clone AgentPro and Install Dependencies\n",
        "\n",
        "To get started with **AgentPro**, begin by cloning the official GitHub repository and installing its dependencies."
      ],
      "metadata": {
        "id": "Fi5Eth4ge70O"
      }
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "tCGHQVf-Q2Zj",
        "outputId": "744cf4b6-8106-4ad5-93ab-ebde24551b65"
      },
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "Cloning into 'AgentPro'...\n",
            "remote: Enumerating objects: 260, done.\u001b[K\n",
            "remote: Counting objects: 100% (81/81), done.\u001b[K\n",
            "remote: Compressing objects: 100% (78/78), done.\u001b[K\n",
            "remote: Total 260 (delta 37), reused 6 (delta 3), pack-reused 179 (from 1)\u001b[K\n",
            "Receiving objects: 100% (260/260), 102.23 KiB | 4.26 MiB/s, done.\n",
            "Resolving deltas: 100% (138/138), done.\n",
            "/content/AgentPro\n",
            "Requirement already satisfied: openai in /usr/local/lib/python3.11/dist-packages (from -r requirements.txt (line 1)) (1.70.0)\n",
            "Collecting youtube_transcript_api (from -r requirements.txt (line 2))\n",
            "  Downloading youtube_transcript_api-1.0.3-py3-none-any.whl.metadata (23 kB)\n",
            "Collecting duckduckgo-search (from -r requirements.txt (line 3))\n",
            "  Downloading duckduckgo_search-8.0.0-py3-none-any.whl.metadata (16 kB)\n",
            "Requirement already satisfied: requests in /usr/local/lib/python3.11/dist-packages (from -r requirements.txt (line 4)) (2.32.3)\n",
            "Collecting python-pptx (from -r requirements.txt (line 5))\n",
            "  Downloading python_pptx-1.0.2-py3-none-any.whl.metadata (2.5 kB)\n",
            "Requirement already satisfied: pydantic in /usr/local/lib/python3.11/dist-packages (from -r requirements.txt (line 6)) (2.11.2)\n",
            "Collecting python-dotenv (from -r requirements.txt (line 7))\n",
            "  Downloading python_dotenv-1.1.0-py3-none-any.whl.metadata (24 kB)\n",
            "Requirement already satisfied: pandas in /usr/local/lib/python3.11/dist-packages (from -r requirements.txt (line 8)) (2.2.2)\n",
            "Requirement already satisfied: numpy in /usr/local/lib/python3.11/dist-packages (from -r requirements.txt (line 9)) (2.0.2)\n",
            "Requirement already satisfied: matplotlib in /usr/local/lib/python3.11/dist-packages (from -r requirements.txt (line 10)) (3.10.0)\n",
            "Requirement already satisfied: seaborn in /usr/local/lib/python3.11/dist-packages (from -r requirements.txt (line 11)) (0.13.2)\n",
            "Requirement already satisfied: openpyxl in /usr/local/lib/python3.11/dist-packages (from -r requirements.txt (line 12)) (3.1.5)\n",
            "Requirement already satisfied: pyarrow in /usr/local/lib/python3.11/dist-packages (from -r requirements.txt (line 13)) (18.1.0)\n",
            "Requirement already satisfied: scikit-learn in /usr/local/lib/python3.11/dist-packages (from -r requirements.txt (line 15)) (1.6.1)\n",
            "Requirement already satisfied: anyio<5,>=3.5.0 in /usr/local/lib/python3.11/dist-packages (from openai->-r requirements.txt (line 1)) (4.9.0)\n",
            "Requirement already satisfied: distro<2,>=1.7.0 in /usr/local/lib/python3.11/dist-packages (from openai->-r requirements.txt (line 1)) (1.9.0)\n",
            "Requirement already satisfied: httpx<1,>=0.23.0 in /usr/local/lib/python3.11/dist-packages (from openai->-r requirements.txt (line 1)) (0.28.1)\n",
            "Requirement already satisfied: jiter<1,>=0.4.0 in /usr/local/lib/python3.11/dist-packages (from openai->-r requirements.txt (line 1)) (0.9.0)\n",
            "Requirement already satisfied: sniffio in /usr/local/lib/python3.11/dist-packages (from openai->-r requirements.txt (line 1)) (1.3.1)\n",
            "Requirement already satisfied: tqdm>4 in /usr/local/lib/python3.11/dist-packages (from openai->-r requirements.txt (line 1)) (4.67.1)\n",
            "Requirement already satisfied: typing-extensions<5,>=4.11 in /usr/local/lib/python3.11/dist-packages (from openai->-r requirements.txt (line 1)) (4.13.1)\n",
            "Requirement already satisfied: defusedxml<0.8.0,>=0.7.1 in /usr/local/lib/python3.11/dist-packages (from youtube_transcript_api->-r requirements.txt (line 2)) (0.7.1)\n",
            "Requirement already satisfied: click>=8.1.8 in /usr/local/lib/python3.11/dist-packages (from duckduckgo-search->-r requirements.txt (line 3)) (8.1.8)\n",
            "Collecting primp>=0.14.0 (from duckduckgo-search->-r requirements.txt (line 3))\n",
            "  Downloading primp-0.14.0-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.metadata (13 kB)\n",
            "Requirement already satisfied: lxml>=5.3.0 in /usr/local/lib/python3.11/dist-packages (from duckduckgo-search->-r requirements.txt (line 3)) (5.3.1)\n",
            "Requirement already satisfied: charset-normalizer<4,>=2 in /usr/local/lib/python3.11/dist-packages (from requests->-r requirements.txt (line 4)) (3.4.1)\n",
            "Requirement already satisfied: idna<4,>=2.5 in /usr/local/lib/python3.11/dist-packages (from requests->-r requirements.txt (line 4)) (3.10)\n",
            "Requirement already satisfied: urllib3<3,>=1.21.1 in /usr/local/lib/python3.11/dist-packages (from requests->-r requirements.txt (line 4)) (2.3.0)\n",
            "Requirement already satisfied: certifi>=2017.4.17 in /usr/local/lib/python3.11/dist-packages (from requests->-r requirements.txt (line 4)) (2025.1.31)\n",
            "Requirement already satisfied: Pillow>=3.3.2 in /usr/local/lib/python3.11/dist-packages (from python-pptx->-r requirements.txt (line 5)) (11.1.0)\n",
            "Collecting XlsxWriter>=0.5.7 (from python-pptx->-r requirements.txt (line 5))\n",
            "  Downloading XlsxWriter-3.2.2-py3-none-any.whl.metadata (2.8 kB)\n",
            "Requirement already satisfied: annotated-types>=0.6.0 in /usr/local/lib/python3.11/dist-packages (from pydantic->-r requirements.txt (line 6)) (0.7.0)\n",
            "Requirement already satisfied: pydantic-core==2.33.1 in /usr/local/lib/python3.11/dist-packages (from pydantic->-r requirements.txt (line 6)) (2.33.1)\n",
            "Requirement already satisfied: typing-inspection>=0.4.0 in /usr/local/lib/python3.11/dist-packages (from pydantic->-r requirements.txt (line 6)) (0.4.0)\n",
            "Requirement already satisfied: python-dateutil>=2.8.2 in /usr/local/lib/python3.11/dist-packages (from pandas->-r requirements.txt (line 8)) (2.8.2)\n",
            "Requirement already satisfied: pytz>=2020.1 in /usr/local/lib/python3.11/dist-packages (from pandas->-r requirements.txt (line 8)) (2025.2)\n",
            "Requirement already satisfied: tzdata>=2022.7 in /usr/local/lib/python3.11/dist-packages (from pandas->-r requirements.txt (line 8)) (2025.2)\n",
            "Requirement already satisfied: contourpy>=1.0.1 in /usr/local/lib/python3.11/dist-packages (from matplotlib->-r requirements.txt (line 10)) (1.3.1)\n",
            "Requirement already satisfied: cycler>=0.10 in /usr/local/lib/python3.11/dist-packages (from matplotlib->-r requirements.txt (line 10)) (0.12.1)\n",
            "Requirement already satisfied: fonttools>=4.22.0 in /usr/local/lib/python3.11/dist-packages (from matplotlib->-r requirements.txt (line 10)) (4.57.0)\n",
            "Requirement already satisfied: kiwisolver>=1.3.1 in /usr/local/lib/python3.11/dist-packages (from matplotlib->-r requirements.txt (line 10)) (1.4.8)\n",
            "Requirement already satisfied: packaging>=20.0 in /usr/local/lib/python3.11/dist-packages (from matplotlib->-r requirements.txt (line 10)) (24.2)\n",
            "Requirement already satisfied: pyparsing>=2.3.1 in /usr/local/lib/python3.11/dist-packages (from matplotlib->-r requirements.txt (line 10)) (3.2.3)\n",
            "Requirement already satisfied: et-xmlfile in /usr/local/lib/python3.11/dist-packages (from openpyxl->-r requirements.txt (line 12)) (2.0.0)\n",
            "Requirement already satisfied: scipy>=1.6.0 in /usr/local/lib/python3.11/dist-packages (from scikit-learn->-r requirements.txt (line 15)) (1.14.1)\n",
            "Requirement already satisfied: joblib>=1.2.0 in /usr/local/lib/python3.11/dist-packages (from scikit-learn->-r requirements.txt (line 15)) (1.4.2)\n",
            "Requirement already satisfied: threadpoolctl>=3.1.0 in /usr/local/lib/python3.11/dist-packages (from scikit-learn->-r requirements.txt (line 15)) (3.6.0)\n",
            "Requirement already satisfied: httpcore==1.* in /usr/local/lib/python3.11/dist-packages (from httpx<1,>=0.23.0->openai->-r requirements.txt (line 1)) (1.0.7)\n",
            "Requirement already satisfied: h11<0.15,>=0.13 in /usr/local/lib/python3.11/dist-packages (from httpcore==1.*->httpx<1,>=0.23.0->openai->-r requirements.txt (line 1)) (0.14.0)\n",
            "Requirement already satisfied: six>=1.5 in /usr/local/lib/python3.11/dist-packages (from python-dateutil>=2.8.2->pandas->-r requirements.txt (line 8)) (1.17.0)\n",
            "Downloading youtube_transcript_api-1.0.3-py3-none-any.whl (2.2 MB)\n",
            "\u001b[2K   \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m2.2/2.2 MB\u001b[0m \u001b[31m42.3 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
            "\u001b[?25hDownloading duckduckgo_search-8.0.0-py3-none-any.whl (18 kB)\n",
            "Downloading python_pptx-1.0.2-py3-none-any.whl (472 kB)\n",
            "\u001b[2K   \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m472.8/472.8 kB\u001b[0m \u001b[31m25.3 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
            "\u001b[?25hDownloading python_dotenv-1.1.0-py3-none-any.whl (20 kB)\n",
            "Downloading primp-0.14.0-cp38-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (3.3 MB)\n",
            "\u001b[2K   \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m3.3/3.3 MB\u001b[0m \u001b[31m67.1 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
            "\u001b[?25hDownloading XlsxWriter-3.2.2-py3-none-any.whl (165 kB)\n",
            "\u001b[2K   \u001b[90m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\u001b[0m \u001b[32m165.1/165.1 kB\u001b[0m \u001b[31m11.1 MB/s\u001b[0m eta \u001b[36m0:00:00\u001b[0m\n",
            "\u001b[?25hInstalling collected packages: XlsxWriter, python-dotenv, primp, youtube_transcript_api, python-pptx, duckduckgo-search\n",
            "Successfully installed XlsxWriter-3.2.2 duckduckgo-search-8.0.0 primp-0.14.0 python-dotenv-1.1.0 python-pptx-1.0.2 youtube_transcript_api-1.0.3\n"
          ]
        }
      ],
      "source": [
        "!git clone https://github.com/traversaal-ai/AgentPro.git\n",
        "%cd AgentPro\n",
        "!pip install -r requirements.txt"
      ]
    },
    {
      "cell_type": "code",
      "source": [
        "!pwd"
      ],
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "V6kVToyfSHHb",
        "outputId": "daa87e74-33cc-43a8-efce-1c58e8e378e2"
      },
      "execution_count": null,
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "/content/AgentPro\n"
          ]
        }
      ]
    },
    {
      "cell_type": "markdown",
      "source": [
        "## Step 2: Set Your API Keys\n",
        "\n",
        "AgentPro requires API keys to access language models and external tools.\n"
      ],
      "metadata": {
        "id": "SLfWC5m9fUpT"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "To use OpenAI models with AgentPro, you’ll need an API key from OpenAI. Follow these steps:\n",
        "\n",
        "1. Go to the [OpenAI API platform](https://platform.openai.com/)\n",
        "2. Log in or create an account\n",
        "3. Click **\"Create new secret key\"**\n",
        "4. Copy the generated key and paste it into the notebook like this:"
      ],
      "metadata": {
        "id": "2vlEmkaNgjwm"
      }
    },
    {
      "cell_type": "markdown",
      "source": [
        "Ares internet tool: Searches the internet for real-time information using the Traversaal Ares API. To use Ares internet tool with AgentPro, you’ll need an API key from traversaal.ai. Follow these steps:\n",
        "\n",
        "1. Go to the [Traversaal API platform](https://api.traversaal.ai/)\n",
        "2. Log in or create an account\n",
        "3. Click **\"Create new secret key\"**\n",
        "4. Copy the generated key and paste it into the notebook like this:"
      ],
      "metadata": {
        "id": "UuYqCgosgcVF"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "import os\n",
        "os.environ[\"OPENAI_API_KEY\"] = \"<openai-api-key>\"\n",
        "os.environ[\"TRAVERSAAL_ARES_API_KEY\"] = \"<traversaal-ares-api-key>\""
      ],
      "metadata": {
        "id": "4tV4Qe1RUGcI"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": [
        "## Step 1: Create a Custom Tool\n",
        "AgentPro is designed to be extensible — you can easily define your own tools for domain-specific tasks.\n",
        "\n",
        "Below is an example of a **custom tool** that queries the Hugging Face Hub and returns the **most downloaded model** for a given task:"
      ],
      "metadata": {
        "id": "LMFP4v5zZmlW"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "from agentpro import AgentPro, ares_tool, code_tool, youtube_tool\n",
        "from huggingface_hub import list_models\n",
        "\n",
        "# Define the task you're interested in\n",
        "task_name = \"text-classification\"\n",
        "\n",
        "# Get the most downloaded model for the specified task\n",
        "models = list_models(filter=task_name, sort=\"downloads\", direction=-1)\n",
        "top_model = next(iter(models))\n",
        "\n",
        "# Print the model ID\n",
        "print(top_model.id)\n"
      ],
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "b_wgIOdcWEYP",
        "outputId": "abb22a66-be0e-406b-fc0e-57576253e1de"
      },
      "execution_count": null,
      "outputs": [
        {
          "output_type": "stream",
          "name": "stderr",
          "text": [
            "/usr/local/lib/python3.11/dist-packages/huggingface_hub/utils/_auth.py:94: UserWarning: \n",
            "The secret `HF_TOKEN` does not exist in your Colab secrets.\n",
            "To authenticate with the Hugging Face Hub, create a token in your settings tab (https://huggingface.co/settings/tokens), set it as secret in your Google Colab and restart your session.\n",
            "You will be able to reuse this secret in all of your notebooks.\n",
            "Please note that authentication is recommended but still optional to access public models or datasets.\n",
            "  warnings.warn(\n"
          ]
        },
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "distilbert/distilbert-base-uncased-finetuned-sst-2-english\n"
          ]
        }
      ]
    },
    {
      "cell_type": "markdown",
      "source": [
        "## Step 2: Define your tool using AgentPro Tool class"
      ],
      "metadata": {
        "id": "Zbn0sZDqZwyX"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "from agentpro.tools.base import Tool\n",
        "\n",
        "class MostModelTool(Tool):\n",
        "    name: str = \"model_download_tool\"\n",
        "    description: str = (\n",
        "        \"Returns the most downloaded model checkpoint on the Hugging Face Hub \"\n",
        "        \"for a given task (e.g., 'text-classification', 'translation').\"\n",
        "    )\n",
        "    arg: str = \"The task name for which you want the top model.\"\n",
        "\n",
        "    def run(self, prompt: str) -> str:\n",
        "        task_name = prompt.strip()\n",
        "        models = list_models(filter=task_name, sort=\"downloads\", direction=-1)\n",
        "        top_model = next(iter(models))\n",
        "        return top_model.id\n",
        "\n"
      ],
      "metadata": {
        "id": "zFrDw_enVAcq"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": [
        "## Step 3: Pass tool to AgentPro"
      ],
      "metadata": {
        "id": "3YHUz6e8ZzPl"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "most_model_download_tool = MostModelTool()\n",
        "agent2 = AgentPro(tools=[most_model_download_tool, ares_tool, code_tool])\n",
        "\n",
        "\n",
        "# Define a task (e.g., 'text-generation', 'image-classification', 'text-to-video', 'text-classification')\n",
        "\n",
        "# Run a query\n",
        "response = agent2(\"Can you give me the name of the model that has the most downloads in the 'text-classification' task on the Hugging Face Hub?\")\n",
        "print(response)"
      ],
      "metadata": {
        "colab": {
          "base_uri": "https://localhost:8080/"
        },
        "id": "47wUizrrVPTr",
        "outputId": "fc70a5db-d660-4b0c-e8c3-88bf04526500"
      },
      "execution_count": null,
      "outputs": [
        {
          "output_type": "stream",
          "name": "stdout",
          "text": [
            "OpenRouter API key not found, using default OpenAI client with gpt-4o-mini\n",
            "================================================================================\n",
            "Thought: I need to use the model download tool to get the most downloaded model for the 'text-classification' task on the Hugging Face Hub. \n",
            "Action: model_download_tool \n",
            "Action Input: 'text-classification' \n",
            "Observation: The most downloaded model for the 'text-classification' task is 'distilbert-base-uncased-finetuned-sst-2-english'. \n",
            "Thought: I now know the final answer.\n",
            "Final Answer: The most downloaded model for the 'text-classification' task on the Hugging Face Hub is 'distilbert-base-uncased-finetuned-sst-2-english'.\n",
            "================================================================================\n",
            "The most downloaded model for the 'text-classification' task on the Hugging Face Hub is 'distilbert-base-uncased-finetuned-sst-2-english'.\n"
          ]
        }
      ]
    },
    {
      "cell_type": "code",
      "source": [],
      "metadata": {
        "id": "pf8Y3xCcWhyl"
      },
      "execution_count": null,
      "outputs": []
    }
  ]
}