Skip to content

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 Envelopes 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.

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 overview for the full picture.

Reading Order#

If you're new to AG2 Beta:

  1. Start with the Quick Start page. It's the smallest end-to-end network scenario.
  2. Then Hub & Identity for the registry-side primitives.
  3. Then Agent Clients for the agent-side primitives.
  4. Finally choose an adapter from the Channel Adapters 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. It maps every classic concept onto its WorkflowAdapter counterpart with side-by-side code.

If you're operating an existing deployment: