Agent Swarm Contracts

Role-Scoped Handoff & Conflict-Resolution Framework for Multi-Agent Systems. Everything below is the full kit — copy it straight into your repo. Nothing else to download.

1. AGENT-SWARM-CONTRACTS.md — the methodology

Why swarms fail without contracts

2026's multi-agent swarm frameworks made it trivial to spin up a dozen coordinated agents with shared memory and retrieval. They did not make it trivial to keep those agents from stepping on each other. In practice, three failure modes show up in almost every swarm within the first few runs:

  • Silent overwrite — Agent B rewrites a file Agent A just finished, because neither one knew the other owned it.
  • Duplicate work — two agents solve the same subtask because the task boundary was implicit instead of written down.
  • Unresolved contradiction — Agent A concludes X, Agent B concludes not-X, and the orchestrator merges both into the final answer because nothing forced a resolution.

All three come from the same root cause: roles, ownership, and disagreement-handling were never written down as contracts the agents (and the orchestrator) actually follow. This kit is that contract layer. It is framework-agnostic — it assumes only that you have an orchestrator and two or more worker agents, whether that's Claude Code subagents, a CrewAI crew, an AutoGen group chat, or a hand-rolled LangGraph.

The Role Contract

Every agent in the swarm gets a Role Contract before it runs. A Role Contract answers four questions, and only four:

  1. Mandate — the one thing this agent is responsible for producing.
  2. Authority boundary — which files, resources, or state this agent may write to, and which it may only read.
  3. Inputs it can trust — which upstream agents' outputs it is allowed to treat as ground truth without re-verifying.
  4. Escalation trigger — the specific condition under which this agent must stop and hand off rather than proceed on its own judgment.

A contract that doesn't fit in these four fields is a sign the role is too broad and should be split. See role-contract-template.md below for the fillable version.

The Handoff Object

Agents don't hand off with a sentence in a chat log — they hand off with a structured object every agent and the orchestrator can parse the same way. See handoff-schema.json below. The three fields that matter most:

  • claims — what the sending agent asserts is now true, with a confidence level, so the receiving agent knows what still needs verification versus what it can build on.
  • owns — the exact resource list the sending agent is releasing ownership of. Nothing is "up for grabs" until it appears here.
  • open_conflicts — anything the sending agent noticed that contradicts another agent's prior claim, flagged rather than silently overwritten.

Shared-Memory Boundaries

When a swarm shares one memory/RAG store, give every write a namespace tied to the Role Contract that produced it (e.g. research.*, codegen.*, qa.*). Reads can cross namespaces freely; writes cannot. This single rule eliminates most silent-overwrite failures without needing a lock manager: an agent can only conflict with itself.

The Conflict Resolution Ladder

When two agents produce claims that contradict each other, resolve in this fixed order — never let the orchestrator pick ad hoc:

  1. Freshness — if one claim supersedes the other in the same namespace (a later write to the same key), the later one wins automatically.
  2. Authority — if the namespaces differ, the agent whose Role Contract mandate covers that domain wins (e.g. the QA agent's verdict on "does this pass tests" beats the codegen agent's opinion on the same question).
  3. Confidence delta — if neither 1 nor 2 applies, compare the confidence levels declared in each claims entry. A gap of one full level or more (e.g. high vs. low) resolves it.
  4. Escalate to human or judge agent — if none of the above resolves it, this is a genuine unresolved conflict. Stop the swarm on this thread and surface both claims side by side rather than merging them. This is the one step every team skips, and the one that prevents shipped contradictions.

Full detail and a worked decision tree are in conflict-resolution-playbook.md.

Worked example

A three-agent swarm (Research, Codegen, QA) is asked to fix a flaky test. Research claims (confidence: high) the flake is a race condition in a shared fixture. Codegen, working in parallel, claims (confidence: medium) the flake is a timeout value that's too low, and patches it. QA re-runs the suite ten times and finds the flake persists three times — contradicting Codegen's fix. Under the ladder: same namespace (qa.* vs codegen.*) → different namespaces → authority resolves it, because QA's mandate is exactly "does this pass," so QA's claim wins and the swarm re-opens the task with Research's original race-condition claim promoted to primary hypothesis — instead of the orchestrator quietly reporting "fixed."

Anti-patterns

  • The chatty handoff — passing free-text summaries between agents instead of the structured Handoff Object. Free text is exactly where claims, ownership, and conflicts get lost.
  • The all-access agent — a role with no authority boundary "to be safe." This is precisely the agent that causes silent overwrites, because everything looks like it's in scope.
  • Orchestrator-as-tiebreaker — letting the orchestrator's own judgment resolve claim conflicts instead of the fixed ladder. This reintroduces the exact ad hoc inconsistency the ladder exists to remove.

2. role-contract-template.md

## Role Contract — [agent name]

**Mandate:** (the one thing this agent is responsible for producing)

**Authority boundary:**
- May write: [resources / files / namespace]
- May read only: [resources / files / namespace]

**Trusted inputs:**
- From [agent]: [what claims may be used without re-verification]

**Escalation trigger:**
- Stop and hand off when: [specific, checkable condition — not "if unsure"]

3. handoff-schema.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "AgentHandoff",
  "type": "object",
  "required": ["from_agent", "to_agent", "claims", "owns", "open_conflicts"],
  "properties": {
    "from_agent": { "type": "string" },
    "to_agent": { "type": "string" },
    "timestamp": { "type": "string", "format": "date-time" },
    "claims": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["statement", "confidence"],
        "properties": {
          "statement": { "type": "string" },
          "confidence": { "type": "string", "enum": ["low", "medium", "high"] },
          "namespace": { "type": "string" }
        }
      }
    },
    "owns": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Resources this agent is releasing ownership of"
    },
    "open_conflicts": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["with_agent", "claim_a", "claim_b"],
        "properties": {
          "with_agent": { "type": "string" },
          "claim_a": { "type": "string" },
          "claim_b": { "type": "string" },
          "resolved": { "type": "boolean", "default": false }
        }
      }
    }
  }
}

4. conflict-resolution-playbook.md

## Conflict Resolution Ladder — decision tree

1. Same namespace, different timestamps?
   -> YES: later write wins. Log it. Done.
   -> NO: go to 2.

2. Different namespaces?
   -> YES: does one agent's Role Contract mandate explicitly cover
      this claim's domain?
        -> YES: that agent's claim wins. Log it. Done.
        -> NO: go to 3.
   -> NO (same namespace, same timestamp): go to 3.

3. Compare declared confidence levels.
   -> Gap of >= 1 level (e.g. high vs low, high vs medium)?
        -> YES: higher-confidence claim wins. Log it. Done.
        -> NO: go to 4.

4. Unresolved. Do NOT merge both claims into a single output.
   -> Mark open_conflicts[].resolved = false
   -> Halt the affected thread
   -> Surface both claims, their source agents, and the evidence
      each cited, to a human or a designated judge agent.

5. quick-start.md

## Quick start by framework

**Claude Code subagents**
- Put each subagent's Role Contract in its `.claude/agents/*.md` frontmatter
  as a `mandate` and `authority_boundary` field.
- Have the orchestrating agent construct a Handoff Object (as JSON) in its
  prompt to the next subagent instead of a free-text summary.

**CrewAI**
- Map Role Contract -> Agent `role` + `backstory` (mandate),
  and `allow_delegation` / tool access -> authority boundary.
- Emit the Handoff Object as the Task `output_pydantic` model passed
  between tasks.

**AutoGen**
- One Role Contract per participant in the GroupChat.
- Use a custom `speaker_selection_method` that applies the Conflict
  Resolution Ladder instead of round-robin when two agents' last
  messages contain contradictory claims.

**LangGraph**
- Role Contract fields become node metadata.
- The Handoff Object is the shared state object passed along edges;
  add `open_conflicts` as a state key so it survives across nodes.

Author

Built by Ukiyo Productions — an original methodology developed in response to 2026's wave of multi-agent swarm-deployment frameworks. Not affiliated with, and not derived from the source code of, any specific open-source project. Part of a 100+ product marketplace built for founders, operators, and agencies working with AI agents.