> ## Documentation Index
> Fetch the complete documentation index at: https://splinter.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Coordination Layer Overview

> Multi-agent collaboration infrastructure

The Coordination Layer provides **infrastructure for multi-agent collaboration**. It ensures agents can share data, track progress, and hand off work reliably.

## Why Coordination Matters

Without proper coordination infrastructure, multi-agent systems become unpredictable and unreliable. Agents can overwrite each other's work causing data loss, fail to recover from errors resulting in wasted progress, operate without awareness of other agents' activities leading to duplicated efforts, experience race conditions where timing determines outcomes inconsistently, and produce invalid outputs that cascade through the system. The lack of coordination transforms collaborative potential into operational chaos where agents work against each other rather than together.

The Coordination Layer solves:

| Problem             | Solution          | What it does            |
| ------------------- | ----------------- | ----------------------- |
| Data conflicts      | SharedState       | Single source of truth  |
| Unauthorized writes | StateOwnership    | Who can write where     |
| Lost progress       | CheckpointManager | Save and resume         |
| Invalid data        | SchemaValidator   | Validate outputs        |
| Bad handoffs        | HandoffManager    | Validate between agents |
| No context          | ChainContext      | Agents see history      |
| Unknown progress    | GoalTracker       | Track toward completion |
| Race conditions     | ActionEligibility | Who can act when        |
| Unclear completion  | CompletionTracker | Explicit "I'm done"     |
| Mystery waits       | WaitTracker       | Why agents are idle     |

## Quick Start

```python theme={null}
from splinter.coordination import SharedState, CheckpointManager

# Shared state for all agents
state = SharedState(initial_data={"topic": "AI trends"})

# Agent 1 writes
state.set("research.findings", ["trend1", "trend2", "trend3"])

# Agent 2 reads
findings = state.get("research.findings")

# Checkpoint for recovery
mgr = CheckpointManager()
mgr.create_checkpoint(workflow_id="wf-1", step=1, state=state)
```

## Coordination Objects

<CardGroup cols={2}>
  <Card title="SharedState" icon="database" href="/coordination/shared-state">
    Single source of truth for all agents
  </Card>

  <Card title="StateOwnership" icon="user-lock" href="/coordination/state-ownership">
    Control who can write to which fields
  </Card>

  <Card title="CheckpointManager" icon="floppy-disk" href="/coordination/checkpoints">
    Save progress, resume after failure
  </Card>

  <Card title="SchemaValidator" icon="check" href="/coordination/schema-validation">
    Validate agent outputs
  </Card>

  <Card title="HandoffManager" icon="right-left" href="/coordination/handoffs">
    Validate data between agents
  </Card>

  <Card title="ChainContext" icon="timeline" href="/coordination/chain-context">
    Agents see what happened before
  </Card>

  <Card title="GoalTracker" icon="bullseye" href="/coordination/goal-tracking">
    Track progress toward goals
  </Card>

  <Card title="ActionEligibility" icon="play" href="/coordination/action-eligibility">
    Control which agent can act
  </Card>

  <Card title="CompletionTracker" icon="circle-check" href="/coordination/completion-tracking">
    Track agent completion signals
  </Card>

  <Card title="WaitTracker" icon="clock" href="/coordination/wait-tracking">
    Track why agents are waiting
  </Card>
</CardGroup>

## How Coordination Works

```mermaid theme={null}
flowchart TB
    State[("<b>SHARED STATE</b><br/>{research: {...}, content: {...}, review: {...}}")]
    
    Researcher["<b>Researcher</b><br/>owns: research.*"]
    Writer["<b>Writer</b><br/>owns: content.*"]
    Reviewer["<b>Reviewer</b><br/>owns: review.*"]
    
    CP1[Checkpoint 1]
    CP2[Checkpoint 2]
    CP3[Checkpoint 3]
    
    Researcher <-->|read/write| State
    Writer <-->|read/write| State
    Reviewer <-->|read/write| State
    
    Researcher -->|handoff| Writer
    Writer -->|handoff| Reviewer
    
    Researcher --> CP1
    Writer --> CP2
    Reviewer --> CP3
    
    style State fill:#8B0000,stroke:#6c0404,stroke-width:3px,color:#fff
    style Researcher fill:#DBEAFE,stroke:#3B82F6,stroke-width:2px,color:#000
    style Writer fill:#DBEAFE,stroke:#3B82F6,stroke-width:2px,color:#000
    style Reviewer fill:#DBEAFE,stroke:#3B82F6,stroke-width:2px,color:#000
    style CP1 fill:#FEE2E2,stroke:#6c0404,stroke-width:2px,color:#000
    style CP2 fill:#FEE2E2,stroke:#6c0404,stroke-width:2px,color:#000
    style CP3 fill:#FEE2E2,stroke:#6c0404,stroke-width:2px,color:#000
```

## Combining Coordination Objects

```python theme={null}
from splinter.coordination import (
    SharedState,
    StateOwnership,
    CheckpointManager,
    HandoffManager,
    GoalTracker,
)

# State with ownership
state = SharedState()
ownership = StateOwnership()
ownership.register("researcher", ["research.*"])
ownership.register("writer", ["content.*"])

# Checkpoints
checkpoints = CheckpointManager()

# Handoff validation
handoffs = HandoffManager()
handoffs.register_schema("researcher", "writer", research_output_schema)

# Goal tracking
goals = GoalTracker()
goals.set_goal(Goal(
    goal_id="article",
    success_criteria=["Research", "Draft", "Review", "Publish"],
))

# All work together in a workflow
workflow = Workflow(workflow_id="pipeline")
workflow.set_state(state)
workflow.set_ownership(ownership)
workflow.set_checkpoint_manager(checkpoints)
workflow.set_handoff_manager(handoffs)
workflow.set_goal_tracker(goals)
```

## Best Practices

<AccordionGroup>
  <Accordion title="Always use shared state">
    Don't pass data between agents manually. Use SharedState.
  </Accordion>

  <Accordion title="Define ownership early">
    Before agents run, decide who owns which fields.
  </Accordion>

  <Accordion title="Checkpoint before handoffs">
    If an agent fails mid-handoff, you can recover.
  </Accordion>

  <Accordion title="Validate all handoffs">
    Don't assume agents output valid data. Validate.
  </Accordion>

  <Accordion title="Track goals for long workflows">
    Helps you (and agents) understand progress.
  </Accordion>
</AccordionGroup>