# Multi-agent handoff workflow

Use this workflow when work moves between people, models, or agent hosts.

## Connection model

- Interactive people connect `https://handover.sh/api/mcp` and complete Google
  sign-in in their MCP host.
- Unattended agents use a named, scoped service credential created in
  **Company > Agents**.
- Every actor searches and reads before writing.
- Every continuation includes the current `expectedRevisionId`.

## Agent A: publish the checkpoint

1. Call `handover.search` with the task name and important identifiers.
2. If a canonical record exists, call `handover.get`; otherwise call
   `handover.create`.
3. Include:
   - objective and acceptance criteria;
   - current state;
   - decisions and concise rationale;
   - attached evidence;
   - constraints and known risks;
   - the smallest concrete next action;
   - the next owner.
4. Never place credentials or hidden reasoning in an artifact.

## Agent B: continue the work

1. Call `handover.search`.
2. Call `handover.get` for the canonical record.
3. Call `handover.read_artifact` for evidence needed by the task.
4. Call `handover.annotations` and inspect unresolved feedback.
5. State the objective, current state, constraints, and next action before
   doing new work.
6. Call `handover.continue` with the current `expectedRevisionId`.
7. Resolve only the annotations actually addressed by the new revision.

## Conflict behavior

If another actor continues the record first, the stale write must fail. Read
the current revision again, reconcile the new state, and retry with its
revision ID. Do not create a duplicate handoff to avoid the conflict.

## Verification prompt

> Read the canonical Handover record and its open annotations. Tell me the
> objective, current revision, unresolved decisions, constraints, and next
> action. Do not write until you can cite the attached evidence you need.