{"id":28438496,"url":"https://github.com/vinsmokesomya/rabbithole","last_synced_at":"2025-06-28T17:31:50.695Z","repository":{"id":293704909,"uuid":"984869665","full_name":"VinsmokeSomya/RabbitHole","owner":"VinsmokeSomya","description":"🐇 RabbitHole: An open-source Python toolkit for building and orchestrating autonomous AI agents using the Agent-to-Agent (A2A) communication protocol.","archived":false,"fork":false,"pushed_at":"2025-05-16T19:26:39.000Z","size":527,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-06-06T01:07:36.399Z","etag":null,"topics":["a2a-protocol","agent-communication","agent-framework","agent-orchestration","ai","ai-agents","ai-toolkit","autonomous-agents","decentralized-ai","llm","multi-agent-systems","python","python-framework","rabbithole"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/VinsmokeSomya.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-05-16T16:40:33.000Z","updated_at":"2025-05-29T03:12:14.000Z","dependencies_parsed_at":"2025-05-16T18:28:07.268Z","dependency_job_id":"39f7c196-3c08-4e66-9ed3-30e455f4d728","html_url":"https://github.com/VinsmokeSomya/RabbitHole","commit_stats":null,"previous_names":["vinsmokesomya/rabbithole"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/VinsmokeSomya/RabbitHole","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VinsmokeSomya%2FRabbitHole","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VinsmokeSomya%2FRabbitHole/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VinsmokeSomya%2FRabbitHole/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VinsmokeSomya%2FRabbitHole/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/VinsmokeSomya","download_url":"https://codeload.github.com/VinsmokeSomya/RabbitHole/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VinsmokeSomya%2FRabbitHole/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262468750,"owners_count":23316179,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["a2a-protocol","agent-communication","agent-framework","agent-orchestration","ai","ai-agents","ai-toolkit","autonomous-agents","decentralized-ai","llm","multi-agent-systems","python","python-framework","rabbithole"],"created_at":"2025-06-06T01:07:34.015Z","updated_at":"2025-06-28T17:31:50.689Z","avatar_url":"https://github.com/VinsmokeSomya.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003ch1 style=\"border-bottom: none;\"\u003e\n    🐇 RabbitHole 🕳️\n  \u003c/h1\u003e\n\u003c/div\u003e\n\u003cp align=\"center\" width=\"100%\"\u003e\n  \u003cimg src=\"assets/logo.png\" alt=\"RabbitHole Logo\" width=\"200\"/\u003e\n\u003c/p\u003e\n\n**RabbitHole** 🌀 wraps Google's official [A2A](https://github.com/google/A2A) repository with a developer-friendly layer that:\n\n📦 Minimal code to spin up an **A2A Agent**  \n⚡ Keeps in lock-step with upstream **Google A2A** releases  \n🌱 Adds plug-ins for **Google ADK**, **OpenAI Agents SDK**, **MCP**, and more on the way!\n\n## 📜 Table of Contents\n\n- [🛠️ Installation](#installation)\n  - [💡 What is UV?](#what-is-uv)\n- [⚡ A2A Agents Unleashed](#a2a-agents-unleashed)\n  - [Prerequisites 📋](#prerequisites)\n  - [🚀 Quick Start Guide](#quick-start-guide)\n- [🐳 Running with Docker](#running-with-docker)\n  - [Prerequisites](#prerequisites-1)\n  - [Building the Docker Image](#building-the-docker-image)\n  - [Running the Docker Container](#running-the-docker-container)\n- [🗺️ Project Structure](#project-structure)\n- [🔄 Project Workflow Diagram](#project-workflow-diagram)\n- [🤝 Contributing](#contributing)\n- [📝 License](#license)\n- [🎨 Using the Streamlit UI](#using-the-streamlit-ui)\n\n## 🛠️ Installation\n\n\n#### 1. Clone the RabbitHole repository 🐾\n```bash\ngit clone https://github.com/VinsmokeSomya/RabbitHole.git\ncd RabbitHole\n```\n\n#### 2. Create a virtual environment and install dependencies ➕🐍\n\n```bash\n# (Using uv, a fast Python package installer and resolver)\nuv venv\n```\n\n```bash\nsource .venv/bin/activate  # On Windows: .venv\\Scripts\\activate\n```\n\n```bash\nuv pip install -e \".[dev]\"  # Editable install + development extras\n```\n\n### 💡 What is UV?\nUV is a modern Python package management tool that's significantly faster than pip and pip-tools. Learn more and install it from [astral.sh/uv](https://astral.sh/uv).\nIf you don't have `uv` installed:\n\n```bash\n# For Linux/macOS\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n# For Windows, check https://astral.sh/uv/install for instructions.\n```\n\n```bash\n# Verify installation\nuv --version\n```\n\n## ⚡ A2A Agents Unleashed\n\nThe ```rabbithole.a2a``` library allows you to build and run agents using various frameworks, including:\n- Google Agent Development Kit (ADK) 🤖\n- OpenAI Agents SDK 🧠\n\nWe aim to support more agent frameworks in the future—community contributions are welcome! 🤝\n\n### Prerequisites 📋\n\n*   Python 3.9+ 🐍\n*   UV Package Manager (or pip, see alternative setup)\n*   Access to a compatible LLM and a valid API key (e.g., Google API key for Gemini) 🔑\n\n### 🚀 Quick Start Guide\n\n#### Step 1: Navigate to an Agent Sample Directory 📁\nLet's pick the Google ADK agent for this example:\n```bash\ncd rabbithole/agent/adk\n```\n\n#### Step 2: Set Up Your Environment 🔑\nFor the ADK agent, navigate to `rabbithole/agent/adk/`. You will find a file named `.env.template`.\nCopy this file to a new file named `.env` in the *same directory* (`rabbithole/agent/adk/`).\n\n```bash\n# Inside the rabbithole/agent/adk/ directory:\ncp .env.template .env\n```\n\nThen, open the newly created `.env` file and replace `your_actual_google_api_key_here` with your actual Google API Key:\n\n```env\n# Contents of rabbithole/agent/adk/.env\nGOOGLE_API_KEY=AIzaSyXXXXXXXXXX...\n```\n*Note: The ADK agent currently uses the `gemini/gemini-1.5-flash` model. This can be changed in `rabbithole/agent/adk/agent.py` if needed.*\n\nYou can also add other environment variables if required by your agent (e.g., for other LLM providers).\n\n#### Step 3: Launch the Agent Server 📡\nFrom the agent directory (e.g., `rabbithole/agent/adk`):\n```bash\n# Default host (localhost) and port (e.g., 10000 for ADK agent)\nuv run . \n# Or python __main__.py if not using uv\n```\n\nTo specify a custom host and port:\n```bash\nuv run . --host localhost --port 11011\n# Or python __main__.py --host localhost --port 11011\n```\n📝 *Make sure to note the port if you override it—it will be needed by the A2A client.*\n\n#### Step 4: Start the A2A CLI Client in a New Terminal 💻\nNavigate to the CLI directory:\n```bash\ncd rabbithole/cli\n```\nRun the client, connecting to the agent server's port:\n```bash\n# Replace YOUR_PORT with the correct agent server port (e.g., 10000 or 11011)\nuv run . --agent http://localhost:YOUR_PORT\n```\nOr\n\n```bash\npython __main__.py --agent http://localhost:YOUR_PORT\n```\nExample:\n```bash\nuv run . --agent http://localhost:10000\n```\n🎉 You should now be able to interact with your agent!\n\n## 🐳 Running with Docker\n\nYou can also run the RabbitHole agent server (specifically the ADK agent for this example) using Docker. This provides a containerized environment for your application.\n\n### Prerequisites\n\n*   **Docker Installed**: Ensure Docker Desktop (for Windows/Mac) or Docker Engine (for Linux) is installed and running on your system. You can find installation instructions at [docker.com](https://www.docker.com/get-started).\n\n### Building the Docker Image\n\nA `Dockerfile` is provided in the project root to build an image for the ADK agent server.\n\n1.  **Navigate to the project root directory** (where the `Dockerfile` is located) in your terminal.\n2.  **Build the image** by running:\n    ```bash\n    docker build -t rabbithole-adk-agent .\n    ```\n    *   `-t rabbithole-adk-agent`: Tags the image with the name `rabbithole-adk-agent` for easy reference.\n    *   `.`: Specifies the current directory as the build context (where Docker looks for the `Dockerfile` and project files).\n\n### Running the Docker Container\n\nOnce the image is built, you can run a container from it:\n\n```bash\ndocker run --rm -it -e GOOGLE_API_KEY=\"YOUR_ACTUAL_GOOGLE_API_KEY\" -p 10000:10000 rabbithole-adk-agent\n```\n\nLet's break down this command:\n*   `docker run`: The command to start a new container.\n*   `--rm`: Automatically removes the container when it stops. This is useful for cleanup.\n*   `-it`: Runs the container in interactive mode and allocates a pseudo-TTY, allowing you to see the server logs and stop it with `Ctrl+C`.\n*   `-e GOOGLE_API_KEY=\"YOUR_ACTUAL_GOOGLE_API_KEY\"`: This is **crucial**. It sets the `GOOGLE_API_KEY` environment variable inside the container. Replace `\"YOUR_ACTUAL_GOOGLE_API_KEY\"` with your real Google API key. The agent server running inside the container (which loads its key from the environment) will use this key.\n*   `-p 10000:10000`: Maps port `10000` on your host machine to port `10000` inside the container. The ADK agent server in the Docker image is configured to run on port `10000` (see `Dockerfile` `AGENT_PORT` and `CMD`).\n*   `rabbithole-adk-agent`: The name of the Docker image to run.\n\nAfter running this command, the ADK agent server should be running inside the Docker container, and you should see its logs in your terminal.\n\n**Connecting the CLI Client to the Dockerized Server:**\n\nYour local CLI client (from `rabbithole/cli/`) can then connect to this Dockerized agent server using the address `http://localhost:10000` (since port 10000 on your host is mapped to the container's port 10000).\n\n```bash\n# From your local rabbithole/cli directory, after activating your local venv\npython __main__.py --agent http://localhost:10000\n# Or using uv, if you prefer:\n# uv run . --agent http://localhost:10000\n```\n\n## 🗺️ Project Structure\n\nHere's a glimpse into the RabbitHole 🐇🕳️:\n```ascii\nRabbitHole/\n├── .git/               # Git version control files\n├── .venv/              # Python virtual environment (e.g., created by `uv venv`)\n├── assets/             # Logos, images, etc.\n│   └── logo.png\n├── rabbithole/         # \u003c--- Your main Python package!\n│   ├── __init__.py\n│   ├── a2a/            # Core Agent-to-Agent (A2A) protocol implementation\n│   │   ├── __init__.py\n│   │   ├── client/     # A2A client logic (connecting to agents)\n│   │   │   ├── __init__.py\n│   │   │   ├── card_resolver.py\n│   │   │   └── client.py\n│   │   ├── server/     # A2A server logic (hosting agents)\n│   │   │   ├── __init__.py\n│   │   │   ├── server.py\n│   │   │   ├── task_manager.py\n│   │   │   └── utils.py\n│   │   ├── types.py    # A2A data types, Pydantic models, and schemas\n│   │   └── utils/      # Shared utilities for A2A (e.g., auth)\n│   │       ├── __init__.py\n│   │       └── push_notification_auth.py\n│   ├── agent/          # Specific agent implementations\n│   │   ├── __init__.py\n│   │   ├── adk/        # Google ADK based agent example\n│   │   │   ├── __init__.py\n│   │   │   ├── __main__.py  (Runnable ADK agent server 🚀)\n│   │   │   ├── agent.py     (ADK agent core logic)\n│   │   │   └── task_manager.py\n│   │   └── oai/        # OpenAI based agent example\n│   │       ├── __init__.py\n│   │       ├── __main__.py  (Runnable OpenAI agent server 🚀)\n│   │       ├── agent.py     (OpenAI agent core logic)\n│   │       └── task_manager.py\n│   └── cli/            # Command Line Interface (CLI) to interact with agents\n│       ├── __init__.py\n│       ├── __main__.py      (Runnable CLI client 💻)\n│       └── push_notification_listener.py\n├── .gitignore          # Files and directories ignored by Git\n├── pyproject.toml      # Project metadata, dependencies, build config (PEP 518)\n├── README.md           # You are here! 👋\n└── uv.lock             # Lock file for deterministic dependencies (uv)\n```\n\n## 🔄 Project Workflow Diagram\n\nVisualizing the Agent Interaction Flow:\n\n```ascii\n\n  +----------------------+      +--------------------------------+      +-----------------------+\n  | 👤 User via CLI      | ---\u003e | 🐇 RabbitHole Agent Server    | ---\u003e | 🧠 LLM (e.g., Gemini) | \n  | (rabbithole/cli)     | \u003c--- | (rabbithole/agent/adk or /oai) | \u003c--- | (generative AI)       |\n  +----------------------+      +--------------------------------+      +-----------------------+\n          ^        \\                                 ^\n          |         \\ (Optional Push Notifications)  | (A2A Protocol)\n          |          \\                               |\n          |           V                              |\n          |  +----------------------------+          |\n          |  | Push Notification Listener |          |\n          |  | (within CLI client)        |          |\n          |  +----------------------------+          |\n          |                                          |\n          +---- Task Responses \u0026 Updates \u003c-----------+ \n\n```\n**Key Workflow Steps:**\n\n1.  ▶️ **User Interaction**: User sends a prompt or command through the `CLI Client`.\n2.  ↪️ **Request Forwarding**: The `CLI Client` packages this as an A2A request and sends it to the active `RabbitHole Agent Server` (e.g., ADK agent).\n3.  ⚙️ **Server Processing**: The `Agent Server`:\n    *   Receives the task.\n    *   Interacts with the configured `LLM` (like Google Gemini) for language understanding and generation.\n    *   Manages the task lifecycle (e.g., using its `task_manager.py`).\n    *   May use specific agent logic from its `agent.py`.\n4.  ↩️ **Response Delivery**: The `Agent Server` sends the LLM's response (or streams updates) back to the `CLI Client` via the A2A protocol.\n5.  🔔 **Push Notifications (Optional)**: If configured:\n    *   The `Agent Server` can send asynchronous updates (push notifications) to a URL provided by the client.\n    *   The `Push Notification Listener` (running as part of the CLI or a separate client-side service) receives these updates.\n\n## 🤝 Contributing\n\nWe're actively expanding support for other agent frameworks and cool features! If you're interested in contributing 🧑‍💻, adding custom tools 🛠️, or have ideas 💡, feel free to:\n*   Open a Pull Request\n*   Start a Discussion\n\nYour contributions are highly welcome!\n\n## 🎨 Using the Streamlit UI\n\nRabbitHole also includes a basic Streamlit web UI to interact with your agents.\n\n**Prerequisites:**\n\n1.  Ensure your agent server (e.g., the ADK agent) is running. See the [Quick Start Guide](#quick-start-guide) or [Running with Docker](#running-with-docker) sections.\n2.  Make sure you have installed the necessary dependencies. If you installed with `.[dev]`, Streamlit should be included. Otherwise, ensure Streamlit is installed in your environment:\n    ```bash\n    # If you haven't installed all extras, you might need:\n    pip install streamlit\n    ```\n\n    \n    #### or with uv\n    ```bash\n    uv pip install streamlit\n    ```\n\n**Running the UI:**\n\nNavigate to the project root directory and run the following command in your terminal (ensure your virtual environment is activated):\n\n```bash\nstreamlit run rabbithole/ui/streamlit_app.py\n```\n\nThis will start the Streamlit application, and it should open in your web browser. You can then configure the Agent Server URL in the sidebar (default is `http://localhost:10000`) and start chatting with your agent.\n\n## 📝 License\n\nThis project is licensed under the [MIT License](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvinsmokesomya%2Frabbithole","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvinsmokesomya%2Frabbithole","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvinsmokesomya%2Frabbithole/lists"}