Assemble a multiagent coordinator

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

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

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.

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-27"

1. Create the coordinator Agent

   Use the same harness, SandboxProfile, Runner pool, lifecycle hooks, and memory mounts as the member releases. The model routing profile may differ.

   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.

2. Authorize the coordinator

   Create a live use_agent PermissionAssignment from the coordinator to every member:

   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:

   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:

   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
   
3. Publish and freeze the roster

   Publication resolves bare member ids and atomically guards every selected AgentRelease:

   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.

4. Deploy the coordinator

   Sessions admit against the deployment, so publish its first revision from the release:

   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.

5. Start one coordinator Session

   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.

Multiagent coordinators

Roster resolution, publication, and authority boundaries.

Multiagent threads

Persistent child threads, shared files, and lifecycle.