Handoff Between Agents

This flow is for teams that want agents to coordinate without a human copying terminal output between sessions. The network channel carries the request; the receiving session can inspect its inbox and respond with evidence.

Setup

Check the local network runtime before sending work:

agh network status -o json
agh network channels -o json
agh network peers release -o json

Start the local session that will send the request:

agh session new --workspace project --agent coordinator --channel release --name release-coordinator -o json

Start or identify the receiving session in the same channel. The examples below use sess_receiver as the returned session id.

agh session new --workspace project --agent reviewer --channel release --name release-reviewer -o json
agh network peers release -o json

Flow

Choose the channel

Use a channel that matches the work boundary, such as release, frontend, or runtime.

Send a directed or channel message

Include a stable interaction_id so traces, receipts, and replies can be correlated.

Read the receiver inbox

The target session uses agh network inbox to inspect queued inbound messages.

Close with evidence

The receiver replies with a summary, artifacts, or a pointer to its AGH session history.

agh network send \
  --session sess_coord \
  --channel release \
  --kind request \
  --interaction-id rel-2026-05-02-docs \
  --body '{"task":"Check release docs for drift","evidence_required":["commands","file paths","remaining risk"]}' \
  -o json

agh network inbox --session sess_receiver -o json

Message shape

Keep the body small and explicit:

{
  "task": "Check release docs for drift",
  "scope": ["packages/site/content/runtime", "packages/site/content/protocol"],
  "evidence_required": ["commands", "file paths", "remaining risk"],
  "deadline": "2026-05-02T21:00:00Z"
}

The envelope metadata carries routing and correlation; the body should carry the work request.

Evidence to keep

Evidence	Command	Why it matters
Network runtime	`agh network status -o json`	Shows whether the daemon-owned network is enabled.
Channel membership	`agh network peers release -o json`	Shows the peers visible for the channel.
Sent envelope	`agh network send ... -o json`	Gives the message id and interaction id.
Receiver queue	`agh network inbox --session sess_receiver -o json`	Shows the message reached the target session queue.
Work evidence	`agh session history <receiver-session>`	Shows what the receiver actually did.

Failure path

Symptom	First check	Next page
No peers are visible	`agh network peers <name> -o json`	Channels and Peers
Message is not in the inbox	`agh network status -o json`	Delivery and Safety
Receiver cannot act on request	`agh session status <session-id> -o json`	Session Lifecycle
No close-out evidence appears	`agh session events <session-id> --last 50`	Coordinate Agents over Network

When to use tasks instead

Use network messages for collaboration and handoff. Use tasks when the work needs queue state, claim leases, retries, or durable completion records inside one AGH runtime.