Multi-agent orchestration made simple. Drop in agents, watch the magic happen.
pip install agentrylab
# Comedy gold
agentrylab run standup_club.yaml --objective "remote work" --max-iters 4
# Real debates with evidence
agentrylab run debates.yaml --objective "Should we colonize Mars?" --max-iters 4
# Facebook Marketplace deals finder
agentrylab run marketplace_deals.yaml --objective "MacBook Pro deals"A zero-player game: drop android personas onto a stage, watch them talk, and jump in whenever you like.
pip install 'agentrylab[web]'
agentrylab serve # → http://127.0.0.1:8000- No API key? No problem. Without
OPENAI_API_KEYthe personas run on an offline demo brain so the stage is alive immediately. Set a key (orAGENTRYLAB_ROOM_PROVIDER=ollama) for real conversations. - 12 ready-made personalities (comedian, philosopher, skeptic, noir detective, grandma, benevolent overlord…) or build your own: name, personality prompt, face, body, colour.
- Micro-animations: blinking, idle bob, a "thinking" pulse while the model runs, equaliser mouths and gesturing arms while talking.
- Join the loop: type a message; mention an android by name and it answers you next.
- Play / pause / step / speed, change the topic mid-show, remove anyone with one click.
- Bring your own brain. Sign in (email + password) and add your OpenAI, Anthropic, DeepSeek or xAI key to a vault that lives in server memory only; create private rooms that run on it. Opt in to "remember" and the key is stored encrypted under your password, so even the operator can't read it. Details and threat model in ROOM.md.
| Variable | Meaning | Default |
|---|---|---|
AGENTRYLAB_ROOM_PROVIDER |
public-stage brain: auto · openai · ollama · mock |
auto (OpenAI if a key is set, else mock) |
AGENTRYLAB_ROOM_MODEL |
model name for the public-stage brain | gpt-4o-mini / llama3 |
AGENTRYLAB_ROOM_DB |
accounts, sessions and encrypted keys (SQLite) | outputs/room.db |
AGENTRYLAB_ROOM_TRANSCRIPTS |
where room transcripts (JSONL) go | outputs/transcripts |
AGENTRYLAB_ALLOW_SIGNUP / AGENTRYLAB_COOKIE_SECURE |
close registration / mark cookies Secure behind HTTPS |
1 / auto |
All variables, with comments, are in .env.example. The complete guide (architecture, how a turn works, accounts and the key threat model, REST + WebSocket API, operating notes, roadmap) is ROOM.md.
The UI lives in web/ (Vite + React + TypeScript + Tailwind + Motion); agentrylab serve serves the built bundle. See web/README.md for development.
5 killer presets that actually work:
| Preset | What It Does | Cool Factor |
|---|---|---|
| 🎤 Stand-Up Club | Two comedians + MC | Comedy gold, pure entertainment |
| 🏛️ Debates | Pro/con + evidence search | Real web research, actual citations |
| 🔬 Research | Scientists collaborate | Academic rigor meets AI |
| 🤖 Research Assistant | Interactive research chat | Human-in-the-loop web research |
| 🛒 Marketplace Deals | Facebook Marketplace finder | Real listings, real URLs, real deals |
- Agents: Roles that speak (comedian, scientist, debater — no limits!)
- Tools: Real integrations (DuckDuckGo search, Facebook Marketplace, Wolfram Alpha)
- Providers: LLM backends (OpenAI, Anthropic, Ollama, and OpenAI-compatible APIs such as DeepSeek and xAI)
- Schedulers: Who talks when (round-robin, every-N)
# Install
pip install agentrylab
# Optional: Local models with Ollama
curl -fsSL https://ollama.ai/install.sh | sh
ollama pull llama3
# Optional: API keys in .env
echo "OPENAI_API_KEY=sk-..." >> .env
echo "APIFY_API_TOKEN=apify_..." >> .envagentrylab run standup_club.yaml --objective "AI taking over the world" --max-iters 6agentrylab run research.yaml --objective "quantum biology breakthroughs"# Start conversation
agentrylab run research_assistant.yaml --objective "latest AI developments"
# Jump in anytime
agentrylab say research_assistant.yaml demo "What about quantum computing?"
agentrylab run research_assistant.yaml --thread-id demo --resume --max-iters 1agentrylab run marketplace_deals.yaml --objective "iPhone 15 Pro deals in NYC"
# With structured inputs (user_inputs) non-interactively
agentrylab run marketplace_deals.yaml \
--params '{"query":"MacBook Pro 14 M3","location":"Tel Aviv","min_price":5000,"max_price":12000}'- Presets may declare a
user_inputssection. If required inputs are missing when starting a conversation via the Telegram adapter, the conversation entersCOLLECTINGstatus until inputs are provided. - Adapter helpers:
provide_user_param(conversation_id, key, value): supply a single input; returns remaining keysfinalize_params_and_start(conversation_id): substitute values, initialize the lab, transition toACTIVE
This enables progressive, chat-like forms for complex scenarios (e.g., location, radius, min/max price) while still supporting one-shot runs with --params.
from agentrylab import init
# Start a comedy show
lab = init("standup_club.yaml", experiment_id="comedy-night")
lab.run(rounds=6)
# Check out the show
for msg in lab.state.history:
print(f"[{msg['role']}]: {msg['content']}")- Real-time streaming: Watch agents work live
- Resume anywhere: Pick up where you left off
- Tool budgets: Prevent runaway API costs
- Human-in-the-loop: Jump into conversations anytime
- Persistence: Everything saved to SQLite + JSONL
- The Room / Web API - Web UI, REST + WebSocket API
- CLI Reference - All commands
- Configuration - YAML preset format
- Architecture - How it works
- Persistence - Data storage format
- Web UI development - Frontend stack and layout
- Security - How user API keys are protected, operator checklist
We welcome contributions! See CONTRIBUTING.md for details.
Quick wins:
- New presets (comedy, debates, research, etc.)
- New tools (APIs, databases, etc.)
- New personas and avatar parts for the Room
- New providers (Gemini, Mistral, etc.)
MIT - Go build something amazing!
Made with ❤️ for the AI community. Because single agents are boring. 🤖