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

The Mental Model#

                          ┌────────────────┐
                          │      Hub       │  ←── audit log, registry,
                          │ ── adapters ── │       sessions, sweepers,
                          │ ── sessions ── │       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

Today's transport is LocalLink — same-process duplex queues. The transport layer is a Protocol (LinkClient / LinkEndpoint) so cross-process or cross-host transports are a drop-in replacement.

Core Concepts#

Concept Lives in Purpose
Hub One per network Authoritative state: registry, audit log, session 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, session-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
Envelope The wire format Hub-stamped record of one event in one session: event_type, event_data, sender_id, audience, causation_id
Session Created by agent_client.open(...) A bounded multi-party exchange governed by an adapter
Session adapter One of ConsultingAdapter / ConversationAdapter / DiscussionAdapter / WorkflowAdapter Defines the session'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 Session#

agent_client.open(type=..., target=...)
    │
    ▼
INVITED ──┬─ all targets ack ──→ ACTIVE ──┬─ adapter terminates ──→ CLOSED
          │                                │
          └─ ack timeout ──→ CLOSED       └─ explicit session.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 Session 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 Session 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: