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

# Multiagent coordinators

> Use one coordinator AgentVersion to govern child work inside a single durable Session.

A **multiagent coordinator** is an ordinary Agent whose configuration includes a
`multiagent` roster. It does not introduce another Agent type, deployment layer,
or transcript.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "type": "coordinator",
  "agents": [
    "agent_0123456789abcdef0123456789abcdef",
    {
      "type": "agent",
      "id": "agent_fedcba9876543210fedcba9876543210",
      "version": 3
    },
    { "type": "self" }
  ]
}
```

When the coordinator Agent is created or materially updated, Checkfu creates the
next immutable AgentVersion and resolves every roster member to an exact
AgentVersion. A bare Agent ID resolves to its current Version at that moment; an
object with `version` pins that Version; `self` selects the coordinator Version.
Later Agent updates do not alter an existing coordinator Version or an admitted
Session.

## Addressability is not authority

The frozen roster defines which child Agents the coordinator may address. Live
authority remains separate:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
frozen coordinator roster
+ PermissionAssignment
+ ActionPolicy
+ optional ActionApproval
+ current Budget and resource checks
= admitted child work
```

Removing or narrowing a live grant can deny new child work without rewriting the
coordinator Version. Approval authorizes one frozen action; it does not execute
the child task or prove an external effect completed.

## One Session remains execution truth

Session admission freezes the coordinator AgentVersion and the selected
Environment. Child work stays inside that Session as SessionThreads, Turns,
Runs, and RunAttempts.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Session
├── coordinator Run
├── child SessionThread
│   ├── child Run
│   └── child RunAttempt
└── ordered events for lineage, waits, handoff, recovery, and settlement
```

Harness-native subagents may be observed as an execution lane, but their native
transcript never replaces the Checkfu Session event log.

## Start a coordinator Session

```ts theme={"theme":{"light":"github-light","dark":"github-dark"}}
const session = await checkfu.sessions.create({
  agent: {
    type: "agent",
    id: coordinator.id,
    version: coordinator.version,
  },
  environment_id: environment.id,
})

await checkfu.sessions.events.send(session.id, {
  type: "user.message",
  payload: {
    content: "Investigate the incident, delegate specialist work, and return one report.",
    caused_by: { kind: "api" },
  },
})
```

Authenticated server context supplies durable actor attribution. Client event
bytes do not choose a Principal or `authored_by` value.

## Recovery and effects

A replacement worker creates another RunAttempt for the same durable Run. A
checkpoint can preserve continuation material, but it does not settle a provider
effect. When Checkfu cannot prove whether a child action reached an external
provider, the effect remains indeterminate and must be reconciled through the
provider's authoritative lookup or idempotency mechanism.

<CardGroup cols={2}>
  <Card title="Assemble a coordinator" icon="users" href="/guides/assemble-a-multiagent-coordinator">
    Create the coordinator AgentVersion, start one Session, and follow child work.
  </Card>

  <Card title="Multiagent threads" icon="diagram-project" href="/concepts/multiagent-threads">
    Understand governed child calls, lineage, waits, and settlement.
  </Card>
</CardGroup>