Getting Started

This guide walks you through everything you need to get started with the framework — from environment setup to running your first agent.

Docker Setup

For the full experience (including the web UI and isolated environments), we recommend using Docker.

Download it from the official Docker website.

Python Virtual Environment

Before installing dependencies, it’s best to create a Python virtual environment.

Create one:

python -m venv venv

Activate it:

On Windows (Git Bash or CMD):

.\venv\Scripts\activate

On macOS/Linux:

source venv/bin/activate

Installation

Install Laddr (CLI, core, and API):

pip install laddr

Or develop against the local repository (editable mode):

pip install -e lib/laddr

Create a New Project

Initialize a new project and move into it:

laddr init my_agent_system
cd my_agent_system

The project includes:

agents/ — Agent modules
workers/ — Worker scripts
Dockerfile — Build configuration
docker-compose.yml — Multi-service orchestration
main.py — Application runner

Set API Keys

To enable integrations, add your API keys to a .env file in your project root:

# .env
GEMINI_API_KEY=your_gemini_api_key
SERPER_API_KEY=your_serper_api_key

Note:

The web_search tool requires a Serper API key.

Gemini is used for LLM integrations.

Set both keys before running the stack.

Run the Stack (Docker)

Start the stack using either of these commands:

laddr run dev -d

docker compose up -d

Once running, open:

Dashboard → http://localhost:5173
API → http://localhost:8000

To run agents without Docker, see Local Setup.

Add an Agent and Tool

Create a new agent and attach a tool to it:

laddr add agent researcher --role "Researcher" --goal "Find facts" --llm-model gemini-2.5-flash
laddr add tool web_search --agent researcher --description "Search the web"

Quick Run

Run your agent with a quick test command:

laddr run researcher '{"topic": "Latest AI agent trends"}'

This executes a local run of your researcher agent using the default configuration.

You’re all set!
You’ve installed Laddr, initialized a project, configured API keys, and run your first agent.