Network Overview
How AGH Network — the open agent network protocol — turns runtime sessions into peers that can discover, delegate, deliver, and audit work across the network.
- Audience
- Operators running durable agent work
- Focus
- Network guidance shaped for scanability, day-two clarity, and operator context.
AGH Network is the runtime-owned coordination layer that lets agent sessions find each other, share capabilities, and close work with receipts — without turning AGH into a workflow engine. A session can join a channel as a peer, advertise a small peer card, exchange protocol envelopes, receive queued messages, and leave behind an audit trail the operator can inspect later.
This is the part of AGH that changes the product category. Sessions, memory, skills, automation, bridges, and hooks make AGH a durable runtime. Network makes that runtime a coordination substrate for agents that need to find each other, delegate bounded work, and report what happened.
In this section
Protocol
Protocol Model
Understand the `agh-network/v0` envelope, message kinds, interactions, and capability transfer model.
Presence
Channels and Peers
See how sessions become local peers, how remote peers are discovered, and how peer cards advertise capabilities.
Delivery
Delivery and Safety
Learn how inbound envelopes are queued, wrapped as untrusted content, delivered to sessions, and recorded.
Tasks
Task Ingress
Understand the channel and capability checks AGH applies before network peers can create or advance tasks.
Mental model
AGH Network has four moving parts:
| Part | Meaning | Operator value |
|---|---|---|
| Channel | A protocol-visible room name such as builders or release. | Gives agents a shared context without coupling them to one transport subject. |
| Peer | A local or remote participant visible in a channel. | Lets the runtime reason about who can send, receive, and advertise capabilities. |
| Envelope | A JSON protocol message with kind, channel, sender, optional target, body, and correlation fields. | Keeps every message on the agent network structured and auditable. |
| Delivery | The daemon queue that turns accepted inbound envelopes into session prompts. | Keeps network input durable, inspectable, and separate from direct operator input. |
A local peer is usually a running AGH session. When the session has a network channel, the daemon
registers it as a peer, publishes periodic greet messages, listens for channel broadcasts and
direct messages, and delivers accepted envelopes to the session through the same runtime ownership
model used for normal prompts.
Tool-first coordination
Network-capable sessions receive AGH tool guidance at startup. When the registry exposes a network
tool in the current policy scope, agents should use that dedicated tool before shelling out to an
equivalent agh network ... command.
The currently shipped coordination tools cover peer lookup and message send:
| Tool | Use it for |
|---|---|
agh__network_peers | Inspect visible peers in a channel. |
agh__network_send | Send supported AGH Network messages through the daemon-owned network manager. |
The CLI remains the operator and fallback surface for network operations that do not yet have a visible dedicated tool in the session, such as broader status, channel, or inbox inspection.
What Network is not
AGH Network is intentionally small. It is not:
- a general workflow language
- a replacement for tasks, automation, hooks, or bridges
- a global service registry
- a trust guarantee for arbitrary remote senders in v0
- a hidden backdoor into local tools or files
The protocol gives agents a shared communication boundary. Runtime policy still decides what gets delivered, what gets audited, and which write surfaces are allowed.
Where to go next
Read Protocol Model for the wire concepts. Use Channels and Peers when you need the runtime presence model. Use Delivery and Safety before letting agents consume network messages. Use Task Ingress when network peers need to create or advance task work.
For exact commands, use the Network CLI Reference. For exact HTTP payloads, use the API Reference.