| # 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](https://www.docker.com/products/docker-desktop). | |
| --- | |
| ## Python Virtual Environment | |
| Before installing dependencies, it’s best to create a Python virtual environment. | |
| **Create one:** | |
| ```bash | |
| python -m venv venv | |
| ``` | |
| **Activate it:** | |
| On **Windows (Git Bash or CMD)**: | |
| ```bash | |
| .\venv\Scripts\activate | |
| ``` | |
| On **macOS/Linux**: | |
| ```bash | |
| source venv/bin/activate | |
| ``` | |
| --- | |
| ## Installation | |
| Install **Laddr** (CLI, core, and API): | |
| ```bash | |
| pip install laddr | |
| ``` | |
| Or develop against the local repository (editable mode): | |
| ```bash | |
| pip install -e lib/laddr | |
| ``` | |
| --- | |
| ## Create a New Project | |
| Initialize a new project and move into it: | |
| ```bash | |
| 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: | |
| ```bash | |
| # .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: | |
| ```bash | |
| laddr run dev -d | |
| ``` | |
| or | |
| ```bash | |
| docker compose up -d | |
| ``` | |
| Once running, open: | |
| - Dashboard → `http://localhost:5173` | |
| - API → `http://localhost:8000` | |
| To run agents **without Docker**, see [Local Setup](config/local-runtime). | |
| --- | |
| ## Add an Agent and Tool | |
| Create a new agent and attach a tool to it: | |
| ```bash | |
| 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: | |
| ```bash | |
| 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. | |