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

# Assemble a multiagent coordinator

> Create and publish one coordinator Agent, authorize its subagents, and start one Session.

<Warning>
  This guide is migration-fenced. Its publish and deploy steps use the retired
  AgentRelease/AgentDeployment API. Use the coordinator shape in
  [Agents](/concepts/agents); an Agent update now creates the immutable Version
  automatically. Session launch returns when the CMA Session slice lands.
</Warning>

This guide starts with two compatible, already-published leaf agents. It writes
one coordinator Agent, creates one `use_agent` PermissionAssignment per roster
member, publishes the coordinator so the roster freezes, deploys it, and starts
one Session.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export CHECKFU_API_KEY="your_api_key"
export CHECKFU_WORKSPACE_ID="wrkspc_0123456789abcdef0123456789abcdef"
export CHECKFU_PRINCIPAL_ID="prin_0123456789abcdef0123456789abcdef"
export RESEARCHER_AGENT="agent_0123456789abcdef0123456789abcdef"
export DRAFTER_AGENT="agent_fedcba9876543210fedcba9876543210"
export CHECKFU_HARNESS_PROFILE_ID="hprof_0123456789abcdef0123456789abcdef"
export CHECKFU_MODEL_ROUTING_PROFILE_ID="mrp_0123456789abcdef0123456789abcdef"
export CHECKFU_SANDBOX_PROFILE_ID="sprof_0123456789abcdef0123456789abcdef"
export AUTH="Authorization: Bearer $CHECKFU_API_KEY"
export V="Checkfu-Version: 2026-08-29"
```

<Steps>
  <Step title="Create the coordinator Agent" titleSize="h2">
    Use the same harness, SandboxProfile, Runner pool, lifecycle hooks, and
    memory mounts as the member releases. The model routing profile may differ.

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl -s --request POST "https://api.checkfu.com/v1/agents" \
      --header "$AUTH" --header "$V" \
      --header "Idempotency-Key: support-coordinator-create" \
      --header "Content-Type: application/json" \
      --data "{
        \"name\": \"support-coordinator\",
        \"description\": \"Coordinates support work across specialists\",
        \"instructions\": \"Coordinate research and drafting, compare evidence, and return one answer.\",
        \"harness\": \"checkfu\",
        \"model_routing_profile_key\": \"primary\",
    	\"sandbox_profile_key\": \"standard\",
        \"multiagent\": {
          \"type\": \"coordinator\",
          \"agents\": [\"$RESEARCHER_AGENT\", \"$DRAFTER_AGENT\"]
        }
      }"
    ```

    Save the returned `id` as `COORDINATOR_AGENT` and its `version` as
    `COORDINATOR_RESOURCE_VERSION`.
  </Step>

  <Step title="Authorize the coordinator" titleSize="h2">
    Create a live `use_agent` PermissionAssignment from the coordinator to every member:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    for MEMBER in "$RESEARCHER_AGENT" "$DRAFTER_AGENT"; do
      curl -s --request POST "https://api.checkfu.com/v1/permission-assignments" \
        --header "$AUTH" --header "$V" \
        --header "Idempotency-Key: coordinator-$COORDINATOR_AGENT-$MEMBER" \
        --header "Content-Type: application/json" \
        --data "{
          \"subject\": { \"kind\": \"agent_definition\", \"agent\": \"$COORDINATOR_AGENT\" },
          \"resource\": { \"kind\": \"agent-definition\", \"id\": \"$MEMBER\" },
          \"permission\": \"use_agent\"
        }"
    done
    ```

    Assign the coordinator its runtime resources:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    for SPEC in \
      "harness:$CHECKFU_HARNESS_PROFILE_ID:use_harness" \
      "model-binding:$CHECKFU_MODEL_ROUTING_PROFILE_ID:use_model" \
      "sandbox-profile:$CHECKFU_SANDBOX_PROFILE_ID:use_environment"; do
      IFS=: read -r KIND RESOURCE PERMISSION <<< "$SPEC"
      curl -s --request POST "https://api.checkfu.com/v1/permission-assignments" \
        --header "$AUTH" --header "$V" \
        --header "Idempotency-Key: coordinator-$COORDINATOR_AGENT-$PERMISSION" \
        --header "Content-Type: application/json" \
        --data "{
          \"subject\": { \"kind\": \"agent_definition\", \"agent\": \"$COORDINATOR_AGENT\" },
          \"resource\": { \"kind\": \"$KIND\", \"id\": \"$RESOURCE\" },
          \"permission\": \"$PERMISSION\"
        }"
    done
    ```

    Finally, authorize the invoking Principal on the coordinator:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    for PERMISSION in invoke steer; do
      curl -s --request POST "https://api.checkfu.com/v1/permission-assignments" \
        --header "$AUTH" --header "$V" \
        --header "Idempotency-Key: coordinator-$COORDINATOR_AGENT-principal-$CHECKFU_PRINCIPAL_ID-$PERMISSION" \
        --header "Content-Type: application/json" \
        --data "{
          \"subject\": { \"kind\": \"principal\", \"principal\": \"$CHECKFU_PRINCIPAL_ID\" },
          \"resource\": { \"kind\": \"agent-definition\", \"id\": \"$COORDINATOR_AGENT\" },
          \"permission\": \"$PERMISSION\"
        }"
    done
    ```
  </Step>

  <Step title="Publish and freeze the roster" titleSize="h2">
    Publication resolves bare member ids and atomically guards every selected
    AgentRelease:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl -s --request POST "https://api.checkfu.com/v1/agents/$COORDINATOR_AGENT/releases" \
      --header "$AUTH" --header "$V" \
      --header "Idempotency-Key: support-coordinator-publish" \
      --header "Content-Type: application/json" \
      --data "{
        \"expected_version\": $COORDINATOR_RESOURCE_VERSION,
        \"note\": \"Initial support coordinator roster\"
      }"
    ```

    A successful response identifies the immutable coordinator AgentRelease;
    save its `version` as `COORDINATOR_RELEASE_NUMBER`.
  </Step>

  <Step title="Deploy the coordinator" titleSize="h2">
    Sessions admit against the deployment, so publish its first revision from
    the release:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl -s --request POST "https://api.checkfu.com/v1/agents/$COORDINATOR_AGENT/deploy" \
      --header "$AUTH" --header "$V" \
      --header "Idempotency-Key: support-coordinator-deploy" \
      --header "Content-Type: application/json" \
      --data "{
        \"agent_release_number\": $COORDINATOR_RELEASE_NUMBER,
        \"target_workspace_id\": \"$CHECKFU_WORKSPACE_ID\"
      }"
    ```

    Save the returned `id` as `COORDINATOR_DEPLOYMENT`. Publishing the
    deployment revision also resolves the authored roster into exact member
    AgentDeploymentRevisions, so every member's deployment must already exist
    in this Workspace.
  </Step>

  <Step title="Start one coordinator Session" titleSize="h2">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl -s --request POST "https://api.checkfu.com/v1/sessions" \
      --header "$AUTH" --header "$V" \
      --header "Idempotency-Key: support-coordinator-session-$(uuidgen)" \
      --header "Content-Type: application/json" \
      --data "{
        \"agent_deployment_id\": \"$COORDINATOR_DEPLOYMENT\",
        \"principal\": \"$CHECKFU_PRINCIPAL_ID\",
        \"initial_events\": [{
          \"type\": \"user.message\",
          \"payload\": {
            \"content\": \"Clear the overnight support backlog and return one evidence-backed report.\",
            \"authored_by\": \"$CHECKFU_PRINCIPAL_ID\",
            \"caused_by\": { \"kind\": \"api\" }
          }
        }]
      }"
    ```

    This creates one top-level Session. The coordinator decides which roster
    members to invoke and Checkfu records their child-thread work under it.
  </Step>
</Steps>

<CardGroup cols={2}>
  <Card title="Multiagent coordinators" icon="users" href="/concepts/multiagent-coordinators">
    Roster resolution, publication, and authority boundaries.
  </Card>

  <Card title="Multiagent threads" icon="diagram-project" href="/concepts/multiagent-threads">
    Persistent child threads, shared files, and lifecycle.
  </Card>
</CardGroup>