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.

---

---

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 <repo-url>
cd <repo-name>

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_<id>/. 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 🤙

---

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.

---