| # 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. |
| |
