How LoopX Handles Multi-Agent Coordination and Peer Handoffs: Architecture and Implementation

LoopX treats multi-agent workflows as isolated execution lanes that share a common goal surface, using handoff hints extracted at launch and a control-plane handoff engine to coordinate peer-to-peer transitions based on runtime observations.

LoopX is an open-source multi-agent orchestration framework that enables complex workflows through peer-to-peer agent coordination. Understanding how LoopX implements multi-agent coordination and peer handoffs requires examining its visible launcher payload construction and the control-plane handoff engine. This architecture ensures that agents can safely yield control to peers only when specific runtime conditions, readiness flags, and budget constraints are satisfied.

Launcher Payload Construction and Handoff Hint Extraction

The coordination process begins in loopx/visible_multi_agent_launcher.py, where the system parses user-provided launch specifications to construct per-lane payloads.

Extracting Handoff Hints from Role Definitions

When building the visible multi-agent payload, the launcher inspects each role definition for handoff signals. According to the source code in loopx/visible_multi_agent_launcher.py (lines 53-57), the system extracts hints using a fallback chain:

handoff_hints = _as_string_list(
    raw_role.get("handoff")
    or raw_role.get("handoff_hints")
    or raw_role.get("interaction_hints")
)

These hints are later used by the control-plane to determine when an agent should pass control to a peer.

Shared Goal Surface Configuration

All lanes share a consistent view of the workflow through the shared goal surface. As implemented in loopx/visible_multi_agent_launcher.py (lines 84-87), the payload builder attaches the same goal_id and registry/runtime roots to every lane:

# Conceptual representation from the shared_goal_surface block

{
    "goal_id": "my-project-goal",
    "registry_root": "LOOPX_REGISTRY",
    "runtime_root": "LOOPX_RUNTIME_ROOT"
}

This ensures that while each lane maintains isolated state, all agents operate on a consistent view of the shared frontier.

Quota Guards and Frontier Projection

The launcher also configures quota guards and frontier projections (lines 15-16), giving each lane a view of the shared todo/quota frontier while preserving lane-scoped isolation for safety and reproducibility.

Control-Plane Handoff Engine

The loopx/control_plane/handoff/ package implements the actual handoff contract, providing read-models and gating mechanisms that validate when peer transitions can occur.

Handoff Readiness Detection

The loopx/control_plane/handoff/handoff_runs.py module exposes read-model functions that inspect recent runs to determine handoff eligibility. In loopx/status.py (lines 2305-2308), the is_handoff_ready_run function evaluates whether a handoff condition is satisfied:

def is_handoff_ready_run(run: dict[str, Any]) -> bool:
    return _is_handoff_ready_run_read_model(
        handoff_ready_classifications=HANDOFF_READY_CLASSIFICATIONS,
    )

Similarly, is_custom_post_handoff_work_run checks for completion of post-handoff work requirements.

Handoff Contracts and Budget Projections

The project_handoff.py and handoff_budget_contract.py modules expose handoff readiness and budget projections. These projections allow the status subsystem to determine if an agent may safely yield its turn based on resource availability and completion criteria.

The Handoff Gate Todo

To enforce handoff conditions at execution time, LoopX uses the HandoffGate todo class defined in loopx/control_plane/todos/handoff_gate.py. As referenced in loopx/status.py (lines 213-219), this gate blocks a lane's execution until projected criteria are met:

class HandoffGate(Todo):
    def is_blocked(self, context):
        return not is_handoff_ready_run(context["run"])

The gate ensures that peer handoffs happen only after the required state—such as a "post_handoff_run_seen" flag—is observed.

Multi-Agent Coordination Flow

The complete coordination process follows five distinct stages:

1. Launch: The user supplies a launch spec containing roles (agents) and optional handoff_hints.
2. Payload Build: build_visible_multi_agent_payload_from_spec translates each role into a lane definition, attaching extracted handoff hints to the lane's metadata.
3. Runtime Start: Each lane runs its own Codex/TUI turn, but all lanes point at the shared goal surface (LOOPX_REGISTRY_and_LOOPX_RUNTIME_ROOT).
4. Handoff Evaluation: During a turn, the runtime queries handoff read-models via the status API. If the handoff budget permits, the handoff_gate todo clears, and the current lane yields control.
5. Peer Activation: The next lane reads the updated shared frontier (including new quota or material projections) and continues execution, completing the handoff.

Practical Example: Configuring a Multi-Agent Launch

Here is a complete example of a launch specification that enables peer handoffs between a researcher and reviewer:

# Example launch spec (JSON-like) used by the visible launcher

spec = {
    "goal_id": "my-project-goal",
    "roles": [
        {
            "agent_id": "researcher-1",
            "role_id": "researcher",
            "handoff_hints": ["review-material"],
            "skill": {"required_skill": "research"},
        },
        {
            "agent_id": "reviewer-1",
            "role_id": "reviewer",
            "handoff_hints": ["approve-output"],
            "skill": {"required_skill": "review"},
        },
    ],
}

This configuration allows the researcher to signal readiness for handoff via the "review-material" hint, while the reviewer waits for the handoff gate to clear before activating.

Summary

• LoopX implements multi-agent coordination through isolated lanes that share a common goal surface defined in loopx/visible_multi_agent_launcher.py.
• Handoff hints are extracted at launch time from role definitions and stored in per-lane metadata.
• The control-plane handoff engine in loopx/control_plane/handoff/ provides read-models (is_handoff_ready_run, is_custom_post_handoff_work_run) that evaluate runtime conditions.
• The HandoffGate todo enforces handoff criteria by blocking execution until readiness and budget projections are satisfied.
• Peer activation occurs only after the current lane yields control and the next lane reads the updated shared frontier.

Frequently Asked Questions

What is a "lane" in LoopX multi-agent coordination?

In LoopX, a lane represents an isolated execution context for a single agent. Each lane maintains its own state while sharing access to the shared goal surface, which contains the common goal_id and registry/runtime roots. This design ensures that agents can operate independently while remaining coordinated through a consistent view of the workflow frontier.

How does LoopX determine when an agent should hand off to a peer?

LoopX determines handoff timing through a combination of handoff hints provided at launch and runtime observations. The is_handoff_ready_run function in loopx/status.py evaluates whether recent runs satisfy the handoff conditions encoded in HANDOFF_READY_CLASSIFICATIONS. Additionally, the handoff_budget_contract.py checks resource availability before allowing the HandoffGate todo to clear.

What prevents an agent from handing off work prematurely?

The HandoffGate todo class in loopx/control_plane/todos/handoff_gate.py acts as a blocking mechanism. Its is_blocked method queries the status API to verify that is_handoff_ready_run returns true and that required post-handoff flags (like "post_handoff_run_seen") are present in the runtime state. This ensures handoffs occur only after the current agent has completed its obligations.

Where are handoff hints defined in a LoopX workflow?

Handoff hints are defined in the launch specification at the role level. According to loopx/visible_multi_agent_launcher.py (lines 53-57), the system checks for hints in the handoff, handoff_hints, or interaction_hints keys of each role dictionary. These hints inform the control-plane's decision-making process regarding when transitions between specific agent types should occur.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}