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

> Discover how LoopX architecture handles multi-agent coordination and peer handoffs. Learn about isolated execution lanes, common goal surfaces, and runtime observation for seamless transitions.

- Repository: [huangruiteng/loopx](https://github.com/huangruiteng/loopx)
- Tags: architecture
- Published: 2026-08-07

---

**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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/loopx/visible_multi_agent_launcher.py) (lines 53-57), the system extracts hints using a fallback chain:

```python
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`](https://github.com/huangruiteng/loopx/blob/main/loopx/visible_multi_agent_launcher.py) (lines 84-87), the payload builder attaches the same `goal_id` and registry/runtime roots to every lane:

```python

# 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`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/handoff/handoff_runs.py) module exposes read-model functions that inspect recent runs to determine handoff eligibility. In [`loopx/status.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/status.py) (lines 2305-2308), the `is_handoff_ready_run` function evaluates whether a handoff condition is satisfied:

```python
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`](https://github.com/huangruiteng/loopx/blob/main/project_handoff.py) and [`handoff_budget_contract.py`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/loopx/control_plane/todos/handoff_gate.py). As referenced in [`loopx/status.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/status.py) (lines 213-219), this gate blocks a lane's execution until projected criteria are met:

```python
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:

```python

# 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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/loopx/status.py) evaluates whether recent runs satisfy the handoff conditions encoded in `HANDOFF_READY_CLASSIFICATIONS`. Additionally, the [`handoff_budget_contract.py`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/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`](https://github.com/huangruiteng/loopx/blob/main/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.