Getting Started

What is RabbitHole?

RabbitHole is a developer-friendly Python framework designed to simplify the creation and orchestration of AI agents. It wraps Google’s core A2A (Agent-to-Agent) communication protocol, providing the structure to build, host, and interact with agents from various providers like Google (ADK) and OpenAI.

The primary goal of RabbitHole is to let you focus on your agent’s unique logic, not the boilerplate of communication protocols and server setup.

Key Features

Minimal Code: Spin up a new A2A-compliant agent with very little code.
Extensible: Designed as a plug-in architecture, allowing for the easy addition of new agent SDKs.
Interoperable: Enables agents built on different platforms to communicate using a single, standardized protocol.
CLI Included: Comes with a built-in command-line client for easy testing and interaction.
Dockerized: Includes a Dockerfile for reproducible, containerized deployments.

Installation

Getting up and running with RabbitHole is simple. The recommended approach is to use uv for fast package management.

Clone the repository:

git clone https://github.com/VinsmokeSomya/RabbitHole.git
cd RabbitHole

Create a virtual environment and install dependencies:

# Create the virtual environment
uv venv

# Activate it
# On Windows: .venv\Scripts\activate
# On macOS/Linux: source .venv/bin/activate
source .venv/bin/activate

# Install the project in editable mode with dev dependencies
uv pip install -e ".[dev]"

Quick Start: Running the ADK Agent

Navigate to the ADK agent directory:
Terminal window
```
cd rabbithole/agent/adk
```
Set up your API Key: Copy the .env.template file to a new file named .env and add your Google API Key.
Terminal window
```
cp .env.template .env
# Now edit .env with your key
```
Launch the Agent Server: From the rabbithole/agent/adk directory, run:
Terminal window
```
uv run .
```
The server will start, typically on http://localhost:10000.
Talk to your Agent: Open a new terminal, activate the virtual environment again, and navigate to the CLI directory:
Terminal window
```
cd rabbithole/cli
uv run . --agent http://localhost:10000
```
You can now send messages to your agent!