# Overview

The `autogen.beta.network` module turns one or more `Agent` instances into a **multi-agent network** — a hub-and-spoke topology where a central registry coordinates channel-based, protocol-driven exchanges between named agents.

It is fully **opt-in**. Bare `Agent` continues to work standalone with no behavioural change when this package is not imported. Adopt the network when you need any of the following:

- Multiple agents coordinating on the same task with **enforceable turn order**, expectations, and audit trails.
- A **registry of named agents** that can find each other by capability.
- **Durable messaging** with replayable channel transcripts (write-ahead log).
- **Governance**: per-agent rules (access, rate, inbox, limits), per-adapter expectations, and a hub-side audit log.
- **Sub-task observability**: `agent.task(...)` lifecycle events automatically forwarded to the hub when run inside a network turn.
- **Distributed / cross-process deployment**: replace `LocalLink` with `WsLink` to run the hub and each agent as separate OS processes connected over WebSocket.

## The Mental Model

```
                          ┌────────────────┐
                          │      Hub       │  ←── audit log, registry,
                          │ ── adapters ── │       channels, sweepers,
                          │ ── channels ── │       expectation evaluators
                          │ ── audit log ──│
                          └────────┬───────┘
                                   │  in-process duplex (LocalLink)
                ┌──────────────────┼──────────────────┐
                ▼                  ▼                  ▼
          ┌──────────┐       ┌──────────┐       ┌──────────┐
          │AgentClient│      │AgentClient│      │AgentClient│
          │  alice    │      │   bob     │      │   carol   │
          │  Agent    │      │  Agent    │      │  Agent    │
          └──────────┘       └──────────┘       └──────────┘
```

Each `Agent` is wrapped by an `AgentClient`, which lives behind a `HubClient` and connects to the hub through a `LinkClient`. The hub holds the authoritative state; clients are thin frontends that send and receive `Envelope`s through framed messages on their link.

Note

The default transport is `LocalLink` — same-process duplex queues. Swap it for `WsLink` to run each agent in its own process or on a separate host; the `HubClient` API is unchanged. See [Distributed Deployment](https://docs.ag2.ai/0.14.0/docs/beta/network/distributed/).

## Core Concepts

| Concept | Lives in | Purpose |
| --- | --- | --- |
| `Hub` | One per network | Authoritative state: registry, audit log, channel table, write-ahead logs, expectation evaluators, sweepers |
| `Passport` | Hub registry | Stable identity (`name`, `agent_id`, owner, model) — identifies who's on the network |
| `Resume` | Hub registry | Capability claims (`claimed_capabilities`, `domains`, `summary`) plus hub-mutated `observed` track record |
| `Rule` | Hub registry | Per-agent governance: access lists, rate limits, inbox caps, channel-type allowlists |
| `HubClient` | One per process | Process-side connection to the hub; manages registration and bookkeeping |
| `AgentClient` | One per agent | Wraps a single `Agent`; sends envelopes, receives notify frames, runs handlers |
| `HumanClient` | One per human | Non-LLM participant (HITL) — same envelope plumbing, no `Agent`; your UI drives it via push (`on_envelope`) / pull (`next_envelope`) |
| `HubListener` / `HubArbiter` | Registered on the hub | `HubListener` observes state transitions after the fact (the audit log is one); `HubArbiter` is the gatekeeper consulted _before_ register / open / send / dispatch decisions |
| `Envelope` | The wire format | Hub-stamped record of one event in one channel: `event_type`, `event_data`, `sender_id`, `audience`, `causation_id` |
| `Channel` | Created by `agent_client.open(...)` | A bounded multi-party exchange governed by an adapter |
| Channel adapter | One of `ConsultingAdapter` / `ConversationAdapter` / `DiscussionAdapter` / `WorkflowAdapter` | Defines the channel's allowed sends, default view policy, expectations, and termination rules |
| `TransitionGraph` | Workflow only | Declarative orchestration: who speaks first, what conditions fire, when to terminate |
| `TaskMirror` | Auto-attached per turn | Bridges `Task` lifecycle events into the hub so capability tags update `Resume.observed` |

## Lifecycle of a Channel

```
agent_client.open(type=..., target=...)
    │
    ▼
INVITED ──┬─ all targets ack ──→ ACTIVE ──┬─ adapter terminates ──→ CLOSED
          │                                │
          └─ ack timeout ──→ CLOSED       └─ explicit channel.close() ──→ CLOSING ──→ CLOSED
                  (expectation violation)         or TTL expired
```

The four built-in adapters differ in how they govern the `ACTIVE → CLOSED` transition:

| Adapter | Participants | Turn order | Termination |
| --- | --- | --- | --- |
| `conversation` | Exactly 2 | Free-form (either side, any time) | Explicit close or TTL |
| `consulting` | Exactly 2 | Strict 1Q1R (initiator → respondent) | Auto-closes after respondent's reply |
| `discussion` | 2+ | Round-robin via `ordering="round_robin"` | Explicit close or TTL |
| `workflow` | 2+ | Declarative `TransitionGraph` | Graph terminates (`TerminateTarget` / `max_turns`) |

See the [Channel Adapters](https://docs.ag2.ai/0.14.0/docs/beta/network/adapters_overview/) overview for the full picture.

## Reading Order

If you're new to AG2 Beta:

1. Start with the [Quick Start](https://docs.ag2.ai/0.14.0/docs/beta/network/quick_start/) page. It's the smallest end-to-end network scenario.
2. Then [Hub & Identity](https://docs.ag2.ai/0.14.0/docs/beta/network/hub_and_identity/) for the registry-side primitives.
3. Then [Agent Clients](https://docs.ag2.ai/0.14.0/docs/beta/network/agent_clients/) for the agent-side primitives.
4. Finally choose an adapter from the [Channel Adapters](https://docs.ag2.ai/0.14.0/docs/beta/network/adapters_overview/) overview based on what you're building.

If you're migrating from the classic `GroupChat` / handoff orchestrations:

1. Skim the overview and quick start.
2. Read [Migrating from Group Chat](https://docs.ag2.ai/0.14.0/docs/beta/network/migration_from_group_chat/). It maps every classic concept onto its `WorkflowAdapter` counterpart with side-by-side code.

If you're operating an existing deployment:

- [Governance, Audit & Observability](https://docs.ag2.ai/0.14.0/docs/beta/network/expectations_and_audit/) covers expectations, the audit log, `HubListener` / `HubArbiter`, and turn-failure handling.
- [Task Observation](https://docs.ag2.ai/0.14.0/docs/beta/network/task_observation/) covers per-capability track records.
- [Views & Skills](https://docs.ag2.ai/0.14.0/docs/beta/network/views_and_skills/) covers what each agent sees of its own channel and how its capabilities are advertised.
- [Distributed Deployment](https://docs.ag2.ai/0.14.0/docs/beta/network/distributed/) covers `WsLink`, `serve_ws`, auth, at-least-once delivery, reconnect, and task durability.