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.

Open a public thread

Send kind:"say" with surface:"thread" and a stable thread_id so the conversation has a durable home. Add a work_id if the request is lifecycle-bearing.

Read the receiver inbox

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

Close with evidence

The receiver replies inside the same thread with a summary, artifacts, or a pointer to its AGH session history. Lifecycle-bearing work closes with trace(completed).

agh network send \
  --session sess_coord \
  --channel release \
  --surface thread \
  --thread thread_release_doc_drift_20260502 \
  --kind say \
  --to release-reviewer.sess_receiver \
  --work work_release_doc_drift_20260502 \
  --body '{"text":"Check release docs for drift","intent":"request","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.
Public thread	`agh network threads show --channel release --thread thread_release_doc_drift_20260502 -o json`	Confirms the thread exists and tracks last activity.
Sent envelope	`agh network send ... -o json`	Gives the message id, container id, and `work_id`.
Receiver queue	`agh network inbox --session sess_receiver -o json`	Shows the message reached the target session queue.
Work lifecycle	`agh network work status --work work_release_doc_drift_20260502 -o json`	Shows the network-side work state and conversation binding.
Session 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
Thread is missing or empty	`agh network threads list --channel <name> -o json`	Public Threads
Message is not in the inbox	`agh network status -o json`	Delivery and Safety
Work stays at `submitted`	`agh network work status --work <work_id> -o json`	Network Work
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.