# Getting Started with Deep Agents: build AI pipelines that cost 80% less **Teams are overpaying for LLM APIs.** Most organizations run every task through one expensive model—Claude Opus, GPT-4o, whatever—because orchestrating multiple models feels like a headache. We thought the same thing until we found ourselves staring at a $0.18 bill for a single repo analysis that should've cost pennies. That's the problem this repo solves. Deep Agents is a multi-agent pipeline that dynamically routes each sub-task to the cheapest capable model on Regolo — using a semantic router called `brick-complexity-pro` that evaluates complexity and picks the right tool for the job. The result, in our testing: roughly **73–84% cost savings** versus running one frontier model for everything. --- https://www.youtube.com/watch?v=1wDiRqGT294&t=4s --- ## What this code actually does Deep Agents takes a any goal, really—and breaks it into a dependency DAG (directed acyclic graph). Then it pushes each step through a specialized sub-agent. The clever part? It doesn't just blindly throw Opus at everything. Here's the pipeline, start to finish: 1. **Planner** — Asks `brick-complexity-pro` to decompose the goal into a structured execution plan. It decides how many steps, which sub-agents to use, and how to allocate the token budget. 2. **Researcher** — Does AST extraction on the target codebase. It catalogs every module, every function signature, every contract. 3. **Tool Agent** — Probes the discovered endpoints. Validates schemas, tests latency, pokes at error boundaries. 4. **Code Executor** — Synthesizes typed Pydantic V2 schemas and MCP tools. Then it runs sandboxed pytest to verify everything actually works. 5. **Reviewer** — Audits the synthesized artifacts for compliance, schema strictness, and the kind of subtle bugs that only show up when you're looking for them. 6. \*\* Report Writer\*\* — Compiles the whole mess into a `HARNESS_SPEC.md` file with telemetry comparing Regolo's multi-model cost against a single-model frontier baseline. The output lands at `data/synthesized_harness/HARNESS_SPEC.md`. It's not some generic template—the structure changes based on whether the user is assessing existing code or synthesizing new tools. --- ## Setup in under 5 minutes Fair warning: the first time we tried this, we messed up the `.env` file twice. ``` git clone cd pip install -e . cp .env.example .envCode language: CSS (css) ``` Now edit `.env`: ``` REGOLO_API_KEY=sk-your-real-key-here OPENAI_BASE_URL=https://api.regolo.ai/v1 REGOLO_MODEL=gpt-oss-20bCode language: JavaScript (javascript) ``` **Pro tip** — and we mean this—if you don't have a Regolo key yet, just leave the API key blank. The system falls back to high-fidelity offline simulation mode automatically. It's surprisingly good for demos and CI pipelines. One more thing: you'll need Python 3.11+. If you're on 3.10, stuff will break in ways that aren't obvious. --- ## Two modes, pick your poison Deep Agents supports two execution modes. ### Assessment mode Use when you want to **analyze code without changing it**. ``` python3 main.py \ --goal "Analyze all modules in this repo and give me an architectural assessment" \ --autoCode language: JavaScript (javascript) ``` This produces a `HARNESS_SPEC.md` with: - A module catalog table (auto-extracted from AST, not hand-written) - Per-layer architectural assessment (API, Contract, Sandbox, Vector, Crawler) - A quality audit matrix with scored dimensions—Modularity, Isolation, Cost Efficiency, Resiliency - Telemetry comparing Regolo's multi-model cost against the frontier baseline We ran this on a repo with 18 modules and 50 functional contracts. Took about 3.5 seconds. Cost: $0.05. The frontier equivalent would've run around $0.19. --- ## How the routing actually works This is where the magic happens: every sub-agent task gets evaluated by `brick-complexity-pro`, a semantic routing meta-model running on Regolo.ai. Think of it as a smart dispatcher. Here's the flow: 1. **Complexity Evaluation** — the router analyzes the task description, the sub-agent's role, and which tools are needed. It spits out a score from 1 to 10. 2. **Dynamic Model Assignment** — based on that score and whatever budget is left, Brick routes to the cheapest model that can actually handle the job: Complexity Tier Model When It Gets Used < 5.5 FAST `gpt-oss-20b` Classification, simple extraction, basic probing 5.5–7.0 BALANCED `gpt-oss-20b` Schema validation, interface probing 7.0–8.5 ESCALATED `qwen3.5-122b` Code synthesis, DAG planning, tool generation > 8.5 REASONING `qwen3.5-122b` Full spec review, hallucination detection 3. **Budget Pressure Detection** — here's our favorite part. If the pipeline budget drops below 25%, Brick automatically downscales remaining steps to `gpt-oss-20b`. No manual intervention. No surprise overages. The thing is, most of the heavy lifting in a multi-agent pipeline is actually cheap. Research? Cheap. Probing? Cheap. It's only the synthesis and review stages that need the expensive stuff. Brick figures this out on the fly. --- ## Customization without the pain ### Adjust the budget In `.env`: ``` TOTAL_PIPELINE_TOKEN_BUDGET=50000 BUDGET_WARNING_THRESHOLD=0.70 ``` The default is 25,000 tokens with a 75% warning threshold. ### Software architecture ``` ┌────────────────────────────────┐ │ DEEP AGENT ORCHESTRATOR │ └────────────────┬───────────────┘ │ [Brick Semantic Router] (brick-complexity-pro) │ ┌──────────────────┬───────────────────┼───────────────────┬──────────────────┐ ▼ ▼ ▼ ▼ ▼ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ PLANNER │ │ RESEARCHER │ │ TOOL AGENT │ │ CODE EXECUTOR│ │ REVIEWER │ │ qwen3.5-122b │ │ gpt-oss-20b │ │ GLM-5.2 │ │ Llama-3.3-70B│ │ qwen3.5-122b │ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ │ │ │ │ │ └──────────────────┴───────────────────┼───────────────────┴──────────────────┘ ▼ ┌───────────────────────┐ │ REPORT WRITER │ │ GLM-5.2 │ └───────────────────────┘ ▲ ┌───────────────────────┐ │ BUDGET CONTROLLER │ │ gpt-oss-20b │ └───────────────────────┘Code language: CSS (css) ``` ### Add Your Own Sub-Agent In `config.py`, under `SUBAGENT_PROFILES`: ``` "security_auditor": { "role_name": "Security Code Auditor", "description": "Scans for injection vulnerabilities, auth flaws, and misconfigurations", "preferred_model": "gpt-oss-20b", "fallback_model": "gpt-oss-20b", "escalation_model": "qwen3.5-122b", "token_limit": 3000, "timeout_sec": 45, "allowed_tools": ["grep_code", "audit_dependencies", "check_auth_flows"], "escalation_threshold": 6.5, "criticality": "HIGH", },Code language: JavaScript (javascript) ``` ### Override models via environment Any model in `config.py` can be overridden without touching code: ``` export MODEL_PLANNER_PREFERRED=gpt-oss-20b export MODEL_REPORT_WRITER_PREFERRED=Llama-3.3-70B-InstructCode language: JavaScript (javascript) ``` --- ## Real numbers from a live run We're "show me the receipts" people, so here's the telemetry from an actual pipeline run against a repo with 18 modules and 50 functional contracts: ``` Frontier Baseline (single model): $0.1852 Regolo Brick Routed (multi-model): $0.0504 Savings: 72.8% (8.5x cheaper)Code language: Bash (bash) ``` And the per-sub-agent breakdown: | Sub-Agent | Model Used | Regolo Cost | Frontier Cost | Savings | |---|---|---|---|---| | Planner | qwen3.5-122b | $0.0026 | $0.0095 | -71.8% | | Researcher | gpt-oss-20b | $0.0063 | $0.0263 | -81.3% | | Tool Prober | gpt-oss-20b | $0.0072 | $0.0276 | -81.5% | | Code Executor | qwen3.5-122b | $0.0156 | $0.0417 | -62.7% | | Reviewer | qwen3.5-122b | $0.0119 | $0.0553 | -61.3% | | Report Writer | gpt-oss-20b | $0.0069 | $0.0247 | -95.7% | Total pipeline tokens: 51,650. Total duration: 3.56 seconds. The cheap stages (Researcher, Tool Prober, Report Writer) see massive savings because `gpt-oss-20b` handles them just fine: the expensive stages (Code Executor, Reviewer) still use `qwen3.5-122b` but they're a smaller share of the total work. --- ## Troubleshooting the annoying stuff ### "Invalid model name" errors If you see `model=GLM-5.2` rejected by the API, you're running older code. The current version normalizes model names automatically—`GLM-5.2` maps to `gpt-oss-20b` internally. Pull the latest and check that `config.normalize_model_name()` is applied in `brick_router.py`. ### Pipeline runs in simulation mode This happens when `REGOLO_API_KEY` is empty or set to the placeholder value. The system silently falls back to offline simulation. It's a feature, not a bug—but make sure you actually want simulation before trusting the outputs. ### Sandbox tests fail The Code Executor drops generated files into `data/sandboxes/sandbox_/`. If old artifacts pile up, things get weird: ``` rm -rf data/sandboxes/ ``` ### The TUI feels sluggish `tui.py` works fine, but it's a basic terminal interface. For serious work, just use the `--auto` flag with `--goal`. You'll save time and avoid the occasional rendering glitch. ### How do we integrate this into CI/CD? Set `REGOLO_API_KEY` as a secret in your CI environment, then run: ``` python3 main.py --goal "Security audit of this repository" --autoCode language: Bash (bash) ``` The exit code reflects pipeline success (0) or failure (non-zero). Perfect for GitHub Actions, GitLab CI, or whatever you're running. The generated `HARNESS_SPEC.md` becomes a build artifact you can archive or push to a docs repo. --- ## Github Code You can download the codes on our Github repo, just download and follow the README steps. If need help you can always reach out our team on [Discord](https://discord.gg/gVcxQz7Y) 🤙 [Download the codes](https://github.com/regolo-ai/tutorials/tree/main/deepagents-multi-agent-brick) --- ## FAQ ### Does this work without a Regolo.ai API key? Yes. Leave `REGOLO_API_KEY` blank and the system runs in high-fidelity offline simulation mode. It's accurate enough for demos, CI pipelines, and development—though obviously not for production workloads. ### Can we use our own LLM provider? Currently, the API client targets Regolo.ai's OpenAI-compatible endpoint. You could swap `OPENAI_BASE_URL` to another provider, but the model names and pricing catalog would need updating. ### What's the maximum repo size it can handle? We've tested up to ~50 modules without issues. Beyond that, you'll want to increase `TOTAL_PIPELINE_TOKEN_BUDGET` in `.env`. The AST extraction is the bottleneck—it's O(n) in the number of files. ### Is the generated HARNESS\_SPEC.md actually usable? Honestly? It depends on your goal. For assessments, it's production-ready—we've used it to brief architects. For tool synthesis, the generated MCP schemas are solid but you'll want to review the SSRF guards and error recovery paths before deploying. ### How do we contribute a new sub-agent? Add your profile to `SUBAGENT_PROFILES` in `config.py`, create a class in `core/subagents/`, and reference it in your planner DAG. The existing sub-agents are good templates—`researcher.py` is probably the cleanest starting point. --- ## Ship Private AI. Not Infrastructure. You have the private AI App architecture, bow give it an inference layer built for production. **Regolo** gives European teams fast, OpenAI-compatible access to Mistral, Llama, Qwen, DeepSeek, GLM, and more — with zero data retention, EU data residency, and no new SDK to learn. Change your `base_url`. Keep your LangChain code. Start shipping. ### 🚀 [Start your 30-day free trial →](https://regolo.ai/?utm_source=blog&utm_medium=cta&utm_campaign=private-rag) Build, test, and deploy with no infrastructure to maintain. **No credit card. No migration project. No compromise on data control.** ### 💬 [Join the Regolo Discord →](https://discord.gg/bqGrVJHeF) Meet builders working on private RAG, local LLMs, LangChain, Ollama, and production AI systems. Share your setup, get feedback from the community, and speak directly with the Regolo team. ### 🤝 [Talk to an AI Infrastructure Engineer →](https://regolo.ai/contact?utm_source=blog&utm_medium=cta&utm_campaign=private-rag) Running a sensitive workload, scaling beyond a proof of concept, or assessing a managed EU inference provider? Get a tailored architecture and commercial proposal for your team. ### 📂 [Clone the GitHub repository →](https://github.com/regolo-ai/tutorials/) Get the full implementation from this guide: ingestion scripts, ChromaDB setup, hybrid retrieval, the **30-Question RAG Floor**, evaluation examples, and deployment configuration. > **Private AI should not require a private data center.** > Regolo gives your team an EU-native path from local experimentation to production-grade inference. --- ### Build with Regolo - **Discord:** [Join the community →](https://discord.gg/bqGrVJHeF) - **GitHub:** [Explore open-source workflows →](https://github.com/regolo-ai/tutorials/) - **X / Twitter:** [Follow @regolo\_ai →](https://x.com/regolo_ai) - **Reddit:** [Join the community →](https://www.reddit.com/r/regolo_ai/) - **Documentation:** [Read the API docs →](https://docs.regolo.ai) - **Contact:** [Talk to the team →](https://regolo.ai/contact) --- *Built with ❤️ by the Regolo team. Questions? [regolo.ai/contact](https://regolo.ai/contact)* or chat with us on [Discord](https://discord.gg/bqGrVJHeF)