Merging Agent Outputs

Merging parallel agent outputs is the payoff for good decomposition — and the punishment for bad decomposition. If your dependency graph was clean and your independence criteria were strict, merging is a straightforward git merge of non-overlapping branches. If your decomposition had hidden dependencies, merging becomes a conflict resolution nightmare that can negate the time saved by parallelism.

Three merge strategies handle production scenarios. Branch-per-agent: each agent works on a dedicated branch, and outputs are merged sequentially into the target branch. The merge order follows the dependency graph — upstream agents merge first. Patch-based merging: each agent produces a patch file rather than committing directly, and a merge agent applies patches in dependency order, resolving conflicts as they arise. Workspace merging: all agents work in the same workspace with file-level locks, and the orchestrator ensures no two agents modify the same file simultaneously.

from agents import Agent, Runner
import subprocess

def merge_agent_branches(branches: list[str], target: str = "main"):
    """Merge agent branches in dependency order."""
    results = []
    for branch in branches:
        # Attempt merge
        result = subprocess.run(
            ["git", "merge", branch, "--no-ff",
             "-m", f"Merge {branch} into {target}"],
            capture_output=True, text=True
        )
        if result.returncode != 0:
            # Conflict detected — invoke resolver agent
            resolver = Agent(
                name="merge-resolver",
                model="o3",
                instructions=f"""
                Resolve merge conflicts between {target} and {branch}.
                Preserve the intent of both branches.
                Run tests after resolving to verify correctness.
                """,
            )
            Runner.run(resolver, f"Resolve: {result.stderr}")
        results.append({"branch": branch, "clean": result.returncode == 0})
    return results

1. Define merge order Merge branches in dependency-graph order: upstream (no dependencies) first, downstream (depends on others) last. This minimizes conflicts.
2. Automate conflict detection Before merging, run a dry-run merge to detect conflicts. Flag them for human review or route to a resolver agent.
3. Validate after merge Run the full test suite after each merge step. A clean merge does not guarantee correct behavior — tests catch semantic conflicts that git cannot detect.