Skip to main content

Multi-Agent Architecture

Asking a single AI Agent to execute 50 consecutive tool calls and still remember what you originally wanted — that's not realistic.

Helix's answer: don't let one Agent do everything. Use three-layer role separation so each layer focuses on its own responsibility.

Two Fatal Problems with Single-Agent Systems​

In real-world engineering tasks, single-agent systems hit two nearly inevitable failure modes:

1. Objective Drift

The Agent needs to read files, search symbols, execute commands, analyze results… every step consumes context. After 30 steps, it's completely immersed in details and has lost the user's real intent. You asked it to "refactor the auth module," and it ends up modifying a completely unrelated config file.

2. Context Pollution

Every tool call's output — file contents, command results, search matches — piles up in conversation history. Important reasoning and decisions get drowned in a sea of intermediate data. The model's attention scatters, and output quality drops sharply.

Three Execution Layers​

Helix uses three execution roles to solve both problems:

Layer 1: Manager Agent (Governance Layer)​

The Manager Agent's sole responsibility is ensuring the final result matches the user's intent.

It doesn't do implementation work. Instead, it:

  • Preserves the user's exact original objective
  • Judges whether the Execution Agent's output is "done"
  • Enforces quality acceptance before final delivery

Think of it as the "project manager" — it doesn't write code, but it knows when the task is truly complete.

Layer 2: Execution Agent (Delivery Layer)​

This is the workhorse. The Execution Agent handles:

  • Driving the primary coding and tool workflow
  • Calling MCP tools: reading/writing files, executing commands, searching code, invoking LSP
  • Decomposing tasks into subtasks and delegating to SubAgents when needed
  • Iterating until the task is complete

It runs sequentially in the main session, with every step visible to the user.

Layer 3: SubAgent (Parallel Deep-Work Layer)​

SubAgent is Helix's most distinctive design. When a task has independently executable branches, the Execution Agent launches one or more SubAgents to work in parallel in fully isolated contexts.

Execution Agent
├─ SubAgent A: "Search all auth-related files"          ──→ summary returned
├─ SubAgent B: "Analyze database migration impact"      ──→ summary returned
└─ SubAgent C: "Check frontend routing change points"   ──→ summary returned
     ↑ Parallel execution, no interference, total time = max(A, B, C)

SubAgent Implementation Details​

A SubAgent isn't a simplified Agent — it's a fully capable, independently executing entity with completely isolated context. The following details come from the backend source code:

Independent Sub-Sessions​

Each SubAgent creates an independent sub-session with an ID format of sub_{parentSessionID}_{timestamp}. The sub-session has its own conversation history, fully isolated from the main session. The main session's context is never polluted by subtask intermediate steps.

Recursion Protection​

SubAgents automatically filter out three dangerous tools:

  • run_subagent — prevents SubAgents from infinitely nesting more SubAgents
  • create_worktree_binding — avoids branch operation conflicts within subtasks
  • start_code_review — review workflows should be controlled by the main session

Additionally, the entire builtin_subagent MCP server is excluded from the SubAgent's tool list.

Intelligent Result Summarization​

When a SubAgent completes, its results need to be returned to the main session. But the raw conversation could be very long — returning it directly would pollute the main session's context.

Helix's handling strategy:

  • If the result is ≤ 2,000 characters, return it directly
  • If the result exceeds 2,000 characters, AI generates a distilled summary of ≤ 500 characters
  • If summarization fails, the result is truncated

This ensures the main session always receives clean, distilled subtask results rather than raw data dumps.

Full Tool Capabilities​

Despite context isolation, SubAgents can still use nearly all tools — file read/write, shell commands, LSP code analysis, search, and more. A SubAgent isn't a "weakened" Agent; it's a fully capable specialist focused on a specific task.

Dual Agent Mode: Two-Model Collaboration​

Beyond the Manager / Execution / SubAgent three-layer architecture, Helix also offers a unique Dual Agent mode — letting two different models (typically Claude and DeepSeek) engage in structured collaboration on the same problem.

Four-Phase Flow​

PhaseDescriptionExecution
ThinkingClaude and DeepSeek independently think about the same problemParallel
DiscussionCross-review — each model critiques the other's answerMulti-round
SynthesisClaude combines the best of both approaches into a final solutionSingle pass
ExecutionExecute according to the final plan (reserved phase)Optional

Why Two Models?​

Different models have different blind spots. Claude is stronger in structured reasoning and security analysis; DeepSeek has advantages in code understanding and cost-effectiveness. Having them think independently and then cross-review means blind spots get caught by the other party, producing a more comprehensive final solution.

Phased Display in the UI​

In helix, Dual Agent mode execution is displayed with clear phase separators:

  • Each phase begins with a --- Phase Name --- divider
  • Different models' responses are labeled with their respective roles (Claude / DeepSeek)
  • The synthesis phase is marked with 🎯 Final Solution
  • Tool calls display as 🔧 AgentName calls tool

The Real Value of Parallel Scheduling​

Time Efficiency​

Traditional serial approach:
  Task A (30s) → Task B (25s) → Task C (20s) = Total 75s

Helix parallel approach:
  Task A (30s) ─┐
  Task B (25s) ─┼─→ Total 30s
  Task C (20s) ─┘

Context Quality​

In serial execution, each task's intermediate output piles up in the main conversation, continuously degrading input quality for subsequent tasks. With parallel execution, the main session only receives distilled summaries, keeping context consistently clean.

User Observability​

In helix, SubAgent status updates in real time:

  • On creation: shows the subtask description and its parent session link
  • During execution: users can open an independent window to watch the SubAgent's live conversation
  • On completion: summary results automatically return to the main session

When to Use SubAgents​

✅ Good fit for SubAgents:

  • "Search multiple modules for security risks and migration blockers in parallel"
  • "Analyze backend and frontend change impact separately"
  • "Investigate references across multiple repos before making changes"
  • Any investigation or analysis task with independent branches

❌ Not ideal for SubAgents:

  • Single-file simple edits
  • Tasks with strict sequential dependencies between steps
  • Lightweight tasks where SubAgent startup overhead would outweigh the benefit