Adapters Overview

A session adapter governs one session's allowed sends, default view policy, expectations, and termination rules. Four built-ins ship with the network module; each has its own page.

Choosing an Adapter#

If you're migrating a classic GroupChat orchestration, see Migrating from Group Chat — the workflow adapter is the modern equivalent.

The Adapter Protocol#

All four adapters implement the same SessionAdapter Protocol:

class SessionAdapter(Protocol):
    manifest: SessionManifest

    def initial_state(self, metadata: SessionMetadata) -> AdapterState: ...
    def fold(self, envelope: Envelope, state: AdapterState) -> AdapterState: ...
    def validate_create(self, metadata: SessionMetadata) -> None: ...
    def validate_send(
        self, metadata: SessionMetadata, envelope: Envelope, state: AdapterState
    ) -> None: ...
    def on_accepted(
        self, metadata: SessionMetadata, envelope: Envelope, state: AdapterState
    ) -> AdapterResult: ...

Each method runs at a specific moment in a session's lifecycle:

You don't normally implement this protocol yourself — the four built-ins cover most cases, and the workflow adapter is parameterised via TransitionGraph for custom orchestrations. The SessionAdapter Protocol is exposed for completeness and for advanced use cases.

Session Lifecycle#

stateDiagram-v2
    [*] --> INVITED: alice.open(...)
    INVITED --> ACTIVE: all targets ack
    INVITED --> CLOSED: ack timeout (acks_within violation)

    ACTIVE --> CLOSING: adapter.on_accepted → CLOSING
    ACTIVE --> CLOSING: explicit session.close()
    ACTIVE --> CLOSED: TTL expired (sweeper)
    ACTIVE --> CLOSED: expectation violation (auto_close)

    CLOSING --> CLOSED: drain complete
    CLOSED --> [*]

The state lives on SessionMetadata.state — read it back via await hub.get_session(session_id).

The four adapters differ entirely in what triggers the ACTIVE → CLOSING arrow:

flowchart LR
    A[ConsultingAdapter] -->|"both flags set:<br/>initiator_sent + respondent_replied"| C1[CLOSING]
    B[ConversationAdapter] -->|"explicit close() only"| C2[CLOSING]
    D[DiscussionAdapter] -->|"explicit close() or TTL only"| C3[CLOSING]
    E[WorkflowAdapter] -->|"TransitionGraph emits<br/>TerminateTarget or max_turns"| C4[CLOSING]

SessionMetadata#

1
2
3
4
5
6
7
8

from autogen.beta.network import (
    Participant,
    ParticipantRole,
    ParticipantSchema,
    SessionManifest,
    SessionMetadata,
    SessionState,
)

The hub-managed record for one session:

Default Expectations#

Each adapter declares its own defaults:

These are enforced by the hub's expectation sweeper. See Expectations & Audit for the evaluator and handler model.

Default View Policies#

N = participant count. The default view governs what each participant sees of the WAL when the default handler projects history into their LLM turn — see Views & Skills.

What's Next#

Pick an adapter from the table at the top of this page and read its dedicated page. Each one includes a worked example you can copy.