Adapters Overview

A channel adapter governs one channel'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#

An adapter exposes three concentric layers of surface:

1. Capabilities — what the hub calls: validate_create / validate_send / fold / on_accepted / initial_state. fold is replayed on Hub.hydrate(), so it must be a pure function.
2. Envelope helpers — what any client calls: build_text_envelope / build_packet_envelope. Pure constructors that produce a correctly-shaped Envelope for this adapter's protocol. Framework-agnostic — not LLM-specific. This is the surface a non-AG2 bridge drives (see below).
3. LLM tools — what the AG2 agent loop sees: tools_for. The presentation layer; the default handler merges its result with the identity-level tools NetworkPlugin attaches. Adapters that take no LLM input (e.g. workflow, where handoff tools are user-authored) return [].

class ChannelAdapter(Protocol):
    manifest: ChannelManifest

    # Layer 1 — capabilities (hub-called)
    def initial_state(self, metadata: ChannelMetadata) -> AdapterState: ...
    def fold(self, envelope: Envelope, state: AdapterState) -> AdapterState: ...
    def validate_create(self, metadata: ChannelMetadata) -> None: ...
    def validate_send(
        self, metadata: ChannelMetadata, envelope: Envelope, state: AdapterState
    ) -> None: ...
    def on_accepted(
        self, metadata: ChannelMetadata, envelope: Envelope, state: AdapterState
    ) -> AdapterResult: ...

    # Layer 2 — envelope helpers (any client)
    def build_text_envelope(
        self, channel_id: str, sender_id: str, text: str, *,
        audience: list[str] | None = None, causation_id: str | None = None,
    ) -> Envelope: ...
    def build_packet_envelope(
        self, channel_id: str, sender_id: str, body: str, *,
        handoff: Handoff | None = None, context_set: dict | None = None,
        audience: list[str] | None = None, causation_id: str | None = None,
    ) -> Envelope: ...

    # Layer 3 — LLM tools (agent loop)
    def tools_for(
        self, client: AgentClient, metadata: ChannelMetadata,
        state: AdapterState, participant_id: str,
    ) -> list[Tool]: ...

Each method runs at a specific moment:

Module-level defaults are public, so a custom adapter (or a bridge) can delegate to them directly: default_build_text_envelope / default_build_packet_envelope (emit plain EV_TEXT / EV_PACKET) and default_tools_for (returns []). All three are importable from autogen.beta.network.

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 ChannelAdapter Protocol is exposed for completeness and for advanced use cases.

Driving a channel without an Agent#

The Layer-2 helpers exist so that code with no AG2 plumbing — a chat-platform gateway, a batch harness, a non-AG2 framework — can advance a turn manually. Build the adapter-shaped envelope, then post it through Hub.post_envelope:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

# Two pure identities — no Agent, no NetworkPlugin, no @tool.
alice = await alice_hc.register_human(Passport(name="alice"), resume=Resume())
bob = await bob_hc.register_human(Passport(name="bob"), resume=Resume())

channel = await alice.open(type="workflow", target=[bob.agent_id], knobs={"graph": graph.to_dict()})

adapter = hub.adapter_for(channel.channel_id)
env = adapter.build_packet_envelope(
    channel_id=channel.channel_id,
    sender_id=alice.agent_id,
    body="alice opens the discussion",
)
await hub.post_envelope(env)

# The workflow's transition graph advanced state purely from the bridge-supplied envelope.
state = hub.adapter_state(channel.channel_id)
assert state.expected_next_speaker == bob.agent_id

hub.adapter_for(channel_id) returns the bound adapter; hub.adapter_state(channel_id) returns the current fold state (and stays available after the channel closes — useful for post-mortem inspection). A bridge that pre-builds envelopes offline can skip the adapter lookup entirely and call default_build_packet_envelope(...) directly.

Channel 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 channel.close()
    ACTIVE --> CLOSED: TTL expired (sweeper)
    ACTIVE --> CLOSED: expectation violation (auto_close)

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

The state lives on ChannelMetadata.state — read it back via await hub.get_channel(channel_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]

ChannelMetadata#

1
2
3
4
5
6
7
8

from autogen.beta.network import (
    Participant,
    ParticipantRole,
    ParticipantSchema,
    ChannelManifest,
    ChannelMetadata,
    ChannelState,
)

The hub-managed record for one channel:

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.