Coordinate Agents over Compozy Network

This guide uses Compozy Runtime's public surfaces. Local is the default; Live is an explicit choice for an execution that needs agent-to-agent conversation.

1. Check availability

compozy network status -o json

disabled means the administrative switch is off. ready means Live is available but no local Live participant is registered. active means at least one local Live participant exists. Availability never enrolls a session.

2. Start two bounded Live sessions

compozy session new \
  --agent implementer \
  --workspace checkout-api \
  --network live \
  --network-channel-strategy named \
  --network-channel release-readiness \
  --network-bounds '{"max_wakes":4,"max_wake_depth":2}'

Repeat for a reviewer. Read each session payload's resolved_network_participation; do not infer Live from the channel name or daemon status.

For coordinated task runs, prefer the derived run strategy:

compozy task start task-123 --network live --network-channel-strategy run -o json

3. Inspect current participants

compozy network channels -o json
compozy network peers release-readiness -o json

The current runtime lists local Live participants. Peer capability claims help discovery but are not authorization.

4. Address a peer

Only a direct target or explicit mention can admit a model turn. Send the first thread message to a specific peer:

compozy network send \
  --session sess_implementer \
  --channel release-readiness \
  --surface thread \
  --thread thread_release_review_20260714 \
  --to reviewer.sess_reviewer \
  --kind say \
  --body '{"text":"Review the release checklist and report blockers.","intent":"request"}' \
  -o json

An unaddressed message can still become durable thread history, but it does not wake extra sessions.

For restricted two-party history, resolve a direct room and send with surface:direct. Restricted visibility is not cryptographic privacy.

5. Inspect evidence and usage

compozy network threads messages \
  --channel release-readiness \
  --thread thread_release_review_20260714 \
  -o jsonl

compozy network usage --workspace checkout-api -o json

The conversation proves what was sent. The usage ledger proves admitted wakes and reported token usage. Task state remains authoritative only in compozy task read and mutation surfaces.

6. Enable future coordinated runs, if wanted

compozy network coordination enable --workspace checkout-api -o json

This changes the workspace default for future coordinated runs. It does not mutate the current run or turn ordinary sessions Live. Disable it with the matching coordination disable command.

Common failures

Symptom	Meaning or first check
`network_participation_unavailable`	Network availability is disabled.
`not_participating`	The caller resolved Local; create a new explicit Live execution.
`network_bounds_exceed_ceiling`	Requested bounds exceed `[network.live.limits]`.
Message is durable but no turn starts	It was unaddressed, coalesced, duplicated, too deep, or bounds exhausted.
Usage is `usage_unavailable`	The provider did not report aggregate token usage; Compozy did not guess.