Tutorial 2: Delegating to subagents

In this tutorial malac splits one request into two subagents that work at the same time: one researches the code without changing anything, the other refactors it and runs the tests. You watch both in the terminal and in the web UI.

You need malac with a working provider, from tutorial 1.

Set up a project

1. Create a small shop package with tests.

   mkdir shop && cd shop && git init -q
   cat > pricing.py <<'EOF'
   def calc_total(prices, discount=0.0):
       subtotal = sum(prices)
       return round(subtotal * (1 - discount), 2)
   EOF
   cat > tax.py <<'EOF'
   from pricing import calc_total
   
   def with_vat(prices, rate=0.27):
       return round(calc_total(prices) * (1 + rate), 2)
   EOF
   cat > cart.py <<'EOF'
   from pricing import calc_total
   
   class Cart:
       def __init__(self):
           self.items = []
   
       def add(self, price):
           self.items.append(price)
   
       def total(self):
           return calc_total(self.items)
   EOF
   cat > test_shop.py <<'EOF'
   import unittest
   from cart import Cart
   from pricing import calc_total
   from tax import with_vat
   
   class ShopTest(unittest.TestCase):
       def test_total(self):
           self.assertEqual(calc_total([1.0, 2.5]), 3.5)
   
       def test_cart(self):
           cart = Cart()
           cart.add(2.0)
           self.assertEqual(cart.total(), 2.0)
   
       def test_vat(self):
           self.assertEqual(with_vat([100.0]), 127.0)
   
   if __name__ == "__main__":
       unittest.main()
   EOF
   git add . && git commit -qm "Add shop"

2. Check that the tests pass.

   python3 -m unittest -q

   ----------------------------------------------------------------------
   Ran 3 tests in 0.000s
   
   OK

Delegate two tasks

1. Start malac and open the web UI.

   malac --name shop

   The terminal UI opens in a new tab named shop for this folder. The daemon behind it always serves the web UI: the welcome screen lists its address next to web, with its token; click it (or the web segment in the status line) to copy it, and open it in your browser. Connection → Show the web UI address shows it too, and malac web --open in another terminal opens it directly.

2. Ask for parallel work. Be explicit about the split; it helps the agent write complete briefs:

   Use two subagents in parallel. First, a read-only subagent labelled
   "research" that lists every place where money is rounded and how,
   with file:line references. Second, a subagent labelled "refactor" that
   renames calc_total to total_price everywhere, tests included, and runs
   python3 -m unittest. Then summarize both reports.

3. Approve the refactor’s edits. In ask mode, the refactor subagent asks before editing and before running the tests. Its dialogs say refactor wants to run edit, so you can tell them from the main agent’s. The research subagent is read-only and never asks. Press a (Always) on the first edit to let the refactor proceed through all four files, and y (Allow) for the test run.

   You can answer in the terminal or in the web UI; the first answer wins.

Watch the agents

While they work, look at the same tree in three places.

In the terminal UI, each subagent has a live card in the transcript with its current step:

⠋ research  lora/default                                   8s ›
  └ grep round\(
⠋ refactor  lora/default                                   8s ›
  └ edit cart.py

Click a card (or press Tab, select it and press Enter) to open that subagent’s own transcript, with a breadcrumb above it; Esc takes you back. On a wide terminal the sidebar lists the tree with each agent’s step; Ctrl+G toggles it. F3 opens the agent list, and F3 again the agent map: the main agent as a box, with research and refactor to its right, each showing its model, state, current step, tokens and cost. Enter opens an agent, x stops it. The status line counts the running agents (⠋ 2 agents), and a click there opens the map. When a card finishes, it shows ◆ done and the first line of its report.

In the line mode, each subagent step is one indented line:

● agent_spawn research: List every place where money is rounded and how…
● agent_spawn refactor: Rename calc_total to total_price everywhere…
  ↳ research started (lora/default)
  ↳ refactor started (lora/default)
  ↳ research · grep round\(
  ↳ refactor · grep calc_total
  ↳ refactor · read pricing.py
  ↳ research · read tax.py
  ✓ research finished
  ↳ refactor · edit pricing.py
  ↳ refactor · edit tax.py
  ↳ refactor · edit cart.py
  ↳ refactor · edit test_shop.py
  ↳ refactor · bash python3 -m unittest
  ✓ refactor finished

The two agent_spawn calls came in one response, so the subagents ran at the same time: their lines interleave.

In the web UI, the tab shows the same transcript, with live subagent cards you can open. The Agents page (A) is a tree of every agent with its status, model and activity, and a live preview of the one you select. Pending approvals show with Allow, Always allow and Deny, and answering in either place closes the dialog in both.

Check the result

1. Read the summary. The main agent collects both reports and summarizes them: the rounding sites (pricing.py and tax.py, both with round(…, 2)) and the rename with a passing test run.

2. Verify the refactor yourself.

   git diff --stat

    cart.py      | 4 ++--
    pricing.py   | 2 +-
    tax.py       | 4 ++--
    test_shop.py | 4 ++--
    4 files changed, 7 insertions(+), 7 deletions(-)

   python3 -m unittest -q
   grep -rn calc_total --include='*.py' . || echo "no calc_total left"

   ----------------------------------------------------------------------
   Ran 3 tests in 0.000s
   
   OK
   no calc_total left

3. Look at the logs. Each subagent has its own transcript. Find the session and print it with all its subagents:

   malac sessions               # main sessions
   malac sessions list --all    # subagents too, labelled [research] and [refactor]
   malac sessions show <id>     # the session, then each subagent indented under it

Going further

• Subagents run up to agents.max_concurrent at a time (default 4) and can nest agents.max_depth levels deep (default 2).
• Give mechanical work a cheaper model: “use lora/fast for the refactor subagent”.
• Ctrl+C cancels the turn and every subagent it started.
• Make recurring roles reusable as agent types; tutorial 6 builds one.

Next: Automating a browser.