Parallel Subagent Orchestration

Introduction

Welcome back to Codex Subagents & Multi-Agent Orchestration! You have completed the first lesson where we explored subagent isolation and output contracts. Those foundational concepts enable us to run reliable, contained AI operations with predictable results. In this second lesson, we are scaling up: Parallel Subagents + Deterministic Aggregation. Instead of running a single isolated subagent, we will orchestrate multiple subagents working concurrently on different parts of a codebase. Each subagent will analyze a specific scope, and we will combine their results into a unified report. By the end of this lesson, you will understand how to build supervisor scripts that coordinate parallel AI work while maintaining full observability and control.

Why Parallel Execution Matters

When analyzing a large codebase, running subagents sequentially can be time-consuming. If each subagent takes 30 seconds, analyzing three different packages would require 90 seconds of sequential execution. With parallel execution, all three run simultaneously, reducing total time to roughly 30 seconds. Beyond speed, parallelism offers other benefits: Scope isolation : Each subagent stays focused on its assigned area without contamination from other scopes. Independent failures : If one subagent fails, others can still succeed and return useful results. Resource utilization : Modern systems have multiple cores; parallel execution leverages this capacity. The challenge lies in coordination: launching multiple processes, collecting their outputs, and merging results into a coherent whole. This is where deterministic aggregation becomes essential.

The Architecture

Our approach involves three key components working together. First, a runner function executes individual subagents, capturing their output and metadata. Second, a parallel executor launches multiple runners concurrently and collects results as they complete. Third, an aggregator function combines these individual results into a unified report. This architecture maintains the isolation principles from our previous lesson while adding coordination. Each subagent still operates within strict boundaries with a JSON contract, but now we are managing multiple subagents as a cohesive workflow. The supervisor script becomes the orchestrator, deciding what tasks to run, monitoring their execution, and synthesizing their findings.

Join the 1M+ learners on CodeSignal

Be a part of our community of 1M+ users who develop and demonstrate their skills on CodeSignal

Aggregation Strategy

With all results collected, aggregation builds a deterministic, traceable report. Start with a consistent skeleton:

Python

def aggregate(results: List[Dict[str, Any]]) -> Dict[str, Any]:
    combined = {
        "status": "success",
        "summaries": [],
        "findings": [],
        "failures": [],
    }

    saw_partial = False
    failed_count = 0

def aggregate(results: List[Dict[str, Any]]) -> Dict[str, Any]:
    combined = {
        "status": "success",
        "summaries": [],
        "findings": [],
        "failures": [],
    }

    saw_partial = False
    failed_count = 0

Process each result using a simple status lattice. Failed results are recorded in the failures list, while partial results still contribute summaries and findings but downgrade the overall status:

Python

    for r in results:
        status = r.get("status")

        if status == "failed":
            failed_count += 1
            combined["failures"].append({
                "scope": r.get("scope"),
                "summary": r.get("summary"),
                "runtime_ms": r.get("runtime_ms"),
                "reason": r.get("reason"),
                "error": r.get("error"),
                "exit_code": r.get("exit_code"),
            })
        else:
            if status == "partial":
                saw_partial = True

            combined["summaries"].append({
                "scope": r.get("scope"),
                "summary": r.get("summary"),
            })
            combined["findings"].extend([
                {"scope": r.get("scope"), "finding": f}
                for f in r.get("findings", [])
            ])

    for r in results:
        status = r.get("status")

        if status == "failed":
            failed_count += 1
            combined["failures"].append({
                "scope": r.get("scope"),
                "summary": r.get("summary"),
                "runtime_ms": r.get("runtime_ms"),
                "reason": r.get("reason"),
                "error": r.get("error"),
                "exit_code": r.get("exit_code"),
            })
        else:
            if status == "partial":
                saw_partial = True

            combined["summaries"].append({
                "scope": r.get("scope"),
                "summary": r.get("summary"),
            })
            combined["findings"].extend([
                {"scope": r.get("scope"), "finding": f}
                for f in r.get("findings", [])
            ])

Finally, compute the overall status deterministically: if everything failed, mark the run as "failed"; otherwise, any failed or partial result downgrades the run to "partial"; only all-success results keep the overall status at "success":

Python

    if failed_count == len(results):
        combined["status"] = "failed"
    elif failed_count > 0 or saw_partial:
        combined["status"] = "partial"

    return combined

    if failed_count == len(results):
        combined["status"] = "failed"
    elif failed_count > 0 or saw_partial:
        combined["status"] = "partial"

    return combined

This preserves useful output from partial runs while ensuring the top-level status accurately reflects degraded subagent outcomes.

Introduction

Why Parallel Execution Matters

The Architecture

Join the 1M+ learners on CodeSignal

Running a Single Subagent

Executing the Subagent Process

Capturing Timing Metrics

Extracting the JSON Contract from CLI Events

Handling Invalid Output

Enriching the Result

Launching Parallel Agents

Collecting Results

Aggregation Strategy

Writing the Output

Putting It All Together

Conclusion and Next Steps