AG2 Beta

AG2 Beta (autogen.beta) is an async, protocol-driven Python framework for building AI agents - covering agents, tools, multi-agent networks, structured output, memory, and evaluation. This file indexes the Beta documentation for LLMs and coding assistants.

Build with autogen.beta only. The classic autogen API (ConversableAgent, initiate_chat, GroupChat) is retired at v1.0 - do not use it. For ready-made setup, install the AG2 Skills with npx skills add ag2ai/ag2-skills.

Documentation

• AG2 Beta: The original AutoGen project released with its first public preview in September 2023, and AG2 later diverged from that codebase in November 2024 to continue building on its core ideas.
• Agent Communication: Agents are the central primitive in AG2 Beta. They maintain state, interact with models, execute tools, and handle user interactions through a clean, conversation-focused API.
• Model Configuration: The AG2 framework provides an explicit, predictable, and type-safe way to configure Large Language Models (LLMs) for your agents. The configuration API is designed to provide a consistent developer...
• Resuming a Turn: agent.ask(...) starts a turn from a new message on the agent's current stream. agent.resume(...) does the same job from a recorded trajectory: you hand it a list of past events, and it re-enters the...
• Structured Output: Structured output constrains the model's final message so you can parse it into a typed Python value-a number, a dataclass, a Pydantic model, or the result of your own validator-instead of treating...
• Prompt Management: Agents can be initialized with a static system prompt. You can provide a single string or a list of strings:
• Depends: The Depends mechanism allows you to calculate and inject dependencies dynamically at execution time.
• Skills: Skills let an agent load specialized instructions on demand instead of carrying every capability in its system prompt. They follow the agentskills.io convention: each skill is a directory that an...
• Middleware: Middleware lets you intercept and customize how an AG2 Beta agent runs a turn. It's the right tool when you want to add cross-cutting behavior such as logging, retries, history trimming, request...
• Telemetry: AG2 Beta includes a TelemetryMiddleware that emits OpenTelemetry spans for agent turns, LLM calls, tool executions, and human-in-the-loop interactions.
• Testing: AG2 provides a built-in TestConfig utility in the autogen.beta.testing module to help you write unit tests for your agents. It allows you to mock LLM responses and simulate tool execution scenarios...
• The Agent Harness: A bare Agent is just a model loop. The harness is the set of opt-in primitives you compose onto it to give it richer capabilities - context assembly, persistent knowledge, sub-task spawning, and the...
• Tasks: A Task is a framework-core wrapper any Agent can use to give a unit of work a trackable lifecycle. While the task is active, the framework emits TaskStarted, TaskProgress, TaskCompleted, TaskFailed...
• Subagents: Subagents let agents delegate work to other agents through tool calling. The calling agent's LLM decides when and what to delegate, and each sub-task runs on its own isolated stream with independent...
• AG2 Compatibility: The autogen.beta.Agent is designed to be fully compatible with existing AG2 architectures, including Group Chats and sequential workflows. By calling the as_conversable() method, you can seamlessly...
• Coding with AI Assistants: Set up your AI coding assistant (Claude Code, Cursor, Copilot, Codex, Windsurf, or any agent) so it can build AG2 Beta apps with you using current, accurate APIs and examples.
• Contribution Policy: AG2 is what it is today because of its contributors. This page explains how contributions will work in the v1.0 era - what lives in Core, what lives as an Extension, and what we ask of contributors...
• Next Steps

Multimodality

• Multimodal Inputs: AG2 agents can process images, audio, video, and documents alongside text. The input event system provides a unified API across providers - you create inputs the same way regardless of which model...
• Image Generation: Some providers can produce images as part of an agent's reply. Generated images are always returned the same way - as a list of BinaryResult objects on reply.files - regardless of which provider...

Tools

• Agent Tools: Tools allow agents to interact with the outside world. By providing tools, you enable your agents to perform actions such as executing code, fetching data from APIs, querying databases, or performing...
• Toolkits: A Toolkit groups related tools into a single, reusable unit. Instead of passing individual tools one by one, you can bundle them into a toolkit and pass the whole collection to an agent. This is...
• Common Tools: AG2 ships with ready-made tools and toolkits that bundle related function tools into a single Toolkit. Unlike built-in provider tools, these run locally as regular Python functions and work with...
• MCP Servers: MCP (Model Context Protocol) is a protocol introduced by Anthropic that aims to standardize how tools and prompts are exposed to LLMs. It can be thought of as a superset of regular Tools, created to...
• Built-in Provider Tools: AG2 includes built-in tools that map to server-side capabilities offered by LLM providers. These tools are executed by the provider's API - not locally - and require no function implementation on...
• Code Execution: AG2 supports two ways to let an agent run code: have the LLM provider execute it inside their own sandbox, or run it client-side through a sandboxed backend you control. Both produce the same...
• Sandbox Shell Tool: SandboxShellTool lets an agent run shell commands inside an environment you choose - a local subprocess, a Docker container, a Daytona sandbox, or any custom backend. Unlike the provider-native...
• Tool middleware: Tool middleware lets you wrap one function tool with async hooks that run immediately around its execution-the same idea as an agent's on_tool_execution() Middleware, but attached at tool definition...
• Approval Required: approval_required() is a built-in tool middleware that gates tool execution on human approval. When the agent tries to call a tool decorated with this middleware, the user is prompted to approve or...

Context Features

• Conversation Variables: Variables provide a flexible way to store, share, and inject contextual information between agents and tools. Unlike hardcoded configurations, variables allow you to dynamically pass state-like API...
• Dependency Injection: Dependency Injection (DI) is a design pattern used to pass complex objects or services into your tools at runtime, rather than hardcoding them or re-instantiating them repeatedly. This keeps your...
• Human in the Loop: Agents often need guidance or approval from human users to proceed safely and effectively. The Human-in-the-Loop (HITL) feature allows an agent to temporarily pause its execution and wait for human...

Evaluation

• Evaluation: Evaluation is how you measure whether your agent actually works. The framework runs your agent over a dataset of tasks, scores each run on multiple properties, and gives you aggregate metrics you can...
• Get started: A hands-on walk-through: by the end you'll have run a real evaluation and understood every line. We build it up one concept at a time - no prior eval experience assumed.
• Scorers: A scorer is a function that grades one agent run and produces a structured feedback record. Run it across N tasks and you get N feedback records - which the framework aggregates into pass rates...
• Datasets & Runs: This page covers the core of the offline eval pipeline: building a Suite of tasks, calling run_agent(), reading the RunResult, and grading traces that already exist. (Saving runs and comparing them...
• Comparing variants: To answer "which is best?" - across models, prompts, tools, middleware, or whole builds - run the same suite under several named variants and rank them on a leaderboard.
• Pairwise comparison: Sometimes "which answer is better?" is easier and more reliable than scoring each answer in isolation - especially for subjective quality. run_pairwise runs two variants over the same suite and asks...
• Persistence & tracking: Every run is saved to disk. That's what turns "run an eval once" into "track an agent over its lifetime" - comparing each version against its past selves to confirm improvements and catch regressions...

Voice & Realtime

• Voice & Realtime Overview: autogen.beta.live is the AG2 Beta module for building voice-enabled agents. It covers two complementary patterns: a turn-by-turn STT -> Agent -> TTS pipeline built on top of a regular Agent, and a...
• Speech-to-Text and Text-to-Speech: The STT -> Agent -> TTS flow turns any existing Agent into a voice agent without changing the agent itself. Speech-to-text is added as a pipeline wrapper; text-to-speech is added as an observer that...
• LiveAgent - Realtime Voice Sessions: LiveAgent is a full-duplex voice agent backed by a provider's realtime API. Unlike the turn-by-turn STT/TTS pipeline, it opens a single bidirectional session for the entire conversation - audio flows...

Advanced Features

• Files API: The Beta Files API provides a provider-agnostic interface for uploading, listing, reading, and deleting files used by multimodal workflows. It wraps each provider's native files endpoint behind a...
• Events Streaming: The Stream in AG2 Beta is a central event bus that facilitates communication between agents and system components. It operates on an event-driven architecture where components can publish events...
• Observers: Observers let you attach lightweight, read-only event listeners directly to an Agent. Under the hood, each observer is a regular Stream subscriber - but you register it on the Agent instead of...
• Watches: A Watch is a reactive trigger primitive. You arm it on a Stream, and it fires a callback when its condition is met - where "condition" can be an event match, a count, a time window, a schedule, or a...
• Knowledge Store: A KnowledgeStore is a virtual, path-based key-value store with filesystem-like semantics. It gives agents a durable place to persist conversation logs, artifacts, working memory, and any other...
• Assembly: Use it to inject persistent context (working memory, past conversations, observer alerts) and to cap the history footprint (sliding window, token budget) - without touching the event stream itself.
• Compaction: Long-running conversations accumulate events faster than the model's context window can absorb. Use compaction to cap the size of history that flows into the next LLM call.
• Aggregation: Aggregation is how an agent builds up persistent state between conversations - the material that WorkingMemoryPolicy and EpisodicMemoryPolicy read back in on subsequent runs.

Multi-Agent Network

• Multi-Agent Network 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...
• Quick Start: The smallest possible end-to-end network scenario: one in-process hub, two agents, a consulting channel that auto-closes after a single Q-and-A.
• Hub and Identity: The hub is the network's single source of truth: registry, audit log, channel table, write-ahead logs, expectation evaluators, sweepers. Every send, observation, and rule check goes through it.
• Agent Clients and Handlers: The agent-side of the network. Registering an Agent produces an AgentClient - one per registered agent - carrying a notify handler that decides what the agent does when an envelope arrives.
• Human Clients (HITL): A HumanClient is a non-LLM participant on the network - the human-in-the-loop primitive. It is a client in the network, just like LLM agents, so the hub routes envelopes to it exactly the same way.
• Network-Assigned Tools: When you call hub.register(agent, ...) with the default attach_plugin=True, the framework attaches NetworkPlugin to your agent. The plugin does two things:
• Channel 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.
• Conversation Adapter: conversation is a free-form 2-party channel. Either side can send at any time; there's no turn order to enforce, and the adapter never auto-closes. Use it when you want a peer-to-peer back-and-forth...
• Consulting Adapter: consulting is a strict 1-question-1-reply channel. The initiator sends exactly one substantive envelope; the respondent sends exactly one reply; the adapter auto-closes with reason...
• Discussion Adapter: discussion is an N-party round-robin channel. Participants speak in a fixed order, cycling indefinitely until you close it. The adapter enforces "wait your turn" via validate_send; the hub's can_send...
• Workflow Adapter: workflow is the orchestrated multi-party adapter. A declarative TransitionGraph describes who speaks first, what conditions fire, and when the channel terminates. It's the modern replacement for the...
• Context Variables: Channel-scoped mutable state that any participant can read or write, auto-persisted on the WAL, and visible to transition conditions. The modern equivalent of classic ContextVariables from...
• Closing Channels: Every channel terminates with an EV_CHANNEL_CLOSED envelope on the WAL, carrying a free-form reason on event_data["reason"] and on ChannelMetadata.close_reason. Five routes lead there. Pick by who...
• Migrating from Group Chat: This page is for users porting an existing AG2 deployment that uses GroupChat plus Handoffs-style orchestration onto the new autogen.beta.network module. The modern equivalent is the WorkflowAdapter...
• Pattern Cookbook: Side-by-side translations of the canonical multi-agent orchestration patterns from classic (non-beta) AG2 (autogen.agentchat.group) onto the beta WorkflowAdapter. Each pattern lists the classic...
• Pipeline / Sequential Processing: The Pipeline pattern organises agents into a strict linear sequence: each agent processes the previous agent's output, then hands off to the next. Information flows in one direction; the run ends...
• Hierarchical / Tree: The Hierarchical pattern places a coordinator above a set of specialists. The coordinator delegates work, the researcher returns to the coordinator with facts, and the writer is the terminal step...
• Star: The Star pattern places one hub agent at the centre with several specialist spokes. The hub fans out questions to the relevant spoke, collects each reply, and synthesises a final answer. Spokes never...
• Coordinator (Manager + Specialists): A coordinator agent at the centre with several specialists. The coordinator's LLM decides which specialist to consult next via a single generic handoff(to) tool, and ends the conversation via a...
• Escalation: The Escalation pattern flows a request up a tiered support stack. Each tier either resolves the request (terminating the workflow) or escalates to the next tier.
• Redundant: The Redundant pattern sends the same problem to multiple specialists with different perspectives; an evaluator at the end picks the best answer or synthesises across them.
• Feedback Loop: The Feedback Loop pattern alternates a drafter and a reviewer until the reviewer flips a done flag in context, or max_turns fires as the safety cap. Drafter writes, reviewer either approves or gives...
• Context-Aware Routing: The Context-Aware Routing pattern uses a router agent to read the user's request, classify it into a category, and dispatch to the specialist whose domain matches.
• Triage with Tasks: The Triage with Tasks pattern breaks a complex request into typed tasks (research -> writing -> review). Each task type routes to a specialist; tasks process sequentially, respecting prerequisite...
• Envelopes and Events: The Envelope is the wire format for everything that flows between agents on the network. Every send produces one; every observer reads them. This page covers the envelope shape, the built-in event...
• Governance, Audit and Observability: The hub enforces governance and surfaces observability through a few layered seams:
• Task Observation: The bridge between the Task lifecycle primitive and the network's per-agent track record. When an Agent runs an agent.task(..., capability="X") inside a network turn, a TaskMirror forwards the...
• Views and Skills: Two LLM-facing concerns:
• Distributed Deployment: The network is not limited to one process. Replace LocalLink with WsLink and the hub becomes a server that agents anywhere on the network can connect to over WebSocket - entirely over the wire, no...

AG-UI

• AG-UI (Agent-User Interaction) Integration: The Agent-User Interaction (AG-UI) protocol standardizes how frontend applications communicate with agents. In AG2, autogen.ag_ui.AGUIStream bridges a ConversableAgent to AG-UI event streams.
• CopilotKit UI Quickstart for AG-UI: This quickstart shows how to connect a CopilotKit React/Next.js UI to an AG2 backend endpoint that speaks the AG-UI protocol.
• AG-UI backend deep dive: This page expands on the backend of the AG-UI integration: how to secure your endpoint, how tool calls are represented in the protocol, and how to pass per-request context into your tools.

A2A

• A2A Protocol Overview: The autogen.beta.a2a module exposes any AG2 Agent over the Agent2Agent (A2A) protocol and lets one AG2 agent talk to a remote A2A endpoint as if it were a regular LLM provider. The protocol is...
• Exposing an Agent as an A2A Server: A2AServer wraps an existing Agent and produces a transport object you can serve directly. JSON-RPC is the default; the same A2AServer instance can also build REST and gRPC transports that share one...
• Connecting to an A2A Server: A2AConfig is a ModelConfig - pass it to a regular Agent and the remote A2A server becomes that agent's LLM provider. Conversation history, tool calls and streaming are negotiated through the...
• Managing Tasks and Push Notifications: A2A models every conversation as a Task with a server-side lifecycle. autogen.beta.a2a.tasks exposes helpers for inspecting and aborting tasks; autogen.beta.a2a.push manages webhook subscriptions for...
• A2A Advanced Topics: Topics that aren't part of the day-to-day A2A path: human-in-the-loop, transparent reconnects on streaming drops, plugging in a custom executor, and the error hierarchy.

A2UI

• A2UI Protocol Overview: The autogen.beta.a2ui module lets an AG2 Agent produce rich, interactive user interfaces - cards, forms, lists, buttons - instead of plain text, using the A2UI protocol. The LLM emits conversational...
• Serving A2UI over HTTP: A2UIServer wraps a plain autogen.beta.Agent and is a ready-to-serve Starlette ASGI app that speaks canonical A2UI over HTTP. It mirrors autogen.beta.a2a.A2AServer: hold the agent, configure A2UI with...
• Serving A2UI over A2A: A2UI's wire is transport-agnostic, so the same validated A2UI messages can ride an A2A exchange instead of the built-in REST adapter. The autogen.beta.a2ui.a2a submodule wraps a plain...
• A2UI Actions & Round-Trips: A2UI actions are the clickable parts of a UI - buttons that, when pressed, drive what happens next. A clickable button is a function you decorate with @a2ui_action and declare on the transport via...
• Catalogs & Client Capabilities: A catalog is the schema that defines which components and functions an A2UI message may use - buttons, forms, lists, cards, and so on. An A2UI transport validates the agent's output against a...

Extensions

• Exa Search: ExaToolkit gives an agent four related tools powered by the Exa neural search engine: web search, find-similar, content retrieval, and AI-powered answers - all sharing a single client.
• TinyFish Search: TinyFishSearchToolkit gives an agent two related tools powered by TinyFish: web search and browser-rendered page fetch. Use it when an agent needs current search results and then needs to read the...

Code Examples

• Code Examples: End-to-end runnable scripts demonstrating autogen.beta. Each example is self-contained, instantiates a GeminiConfig directly, and exercises one or two specific harness primitives so you can read it...
• Hello Agent: The smallest possible end-to-end example: instantiate an Agent with one model config, call ask(), print the reply, then reuse the same Agent for a second turn. No tools, no harness primitives, no...
• Recipe Builder: A culinary assistant that rescales a classic carbonara recipe from 2 servings to 6. The Agent is given a custom Python function as a tool and a Pydantic model as its response_schema, so the final...
• Travel Planner: A travel-planner Agent walks through five turns of a single conversation: kicking off the trip, layering on budget and travel-mode constraints, swapping a day's activity, and producing a final...
• Token Watchdog: A creative-writing Agent runs with three observers attached: two built-in (TokenMonitor, LoopDetector) and one custom (AlertConsole). The thresholds are deliberately low so a single ask trips the...
• Research Squad: Two complementary multi-Agent patterns in one example. First, a coordinator opts in to the auto-injected run_subtasks tool (via tasks=TaskConfig()) to fan out three independent factual lookups...
• Journal Companion: A daily-journal Agent that genuinely remembers across runs - not by replaying conversation history, but by summarising each session into a /memory/working.md file in a KnowledgeStore and re-injecting...
• Long-Doc Chat: A "remember the last words" chat exercise that stress-tests the assembly chain. Three policies compose to control exactly what the LLM sees on each call - drop non-conversation events, hard-cap to...
• Safety Guard: A custom BaseObserver (PathGuardian) watches every tool call and emits a Severity.FATAL ObserverAlert when an Agent tries to write to a forbidden path like /etc/. The alert routes through AlertPolicy...

Optional

• llms-full.txt: The entire Beta documentation concatenated into a single file.
• AG2 Skills: Installable Agent Skills that teach coding assistants the Beta API.