# AG2: features, protocols, quickstart

## TL;DR

AG2 is an Apache-2.0 Python agent framework maintained by a volunteer community; the project diverged from the AutoGen codebase in November 2024. Version 1.0 moved the classic `autogen` API into a separate `ag2-classic` package and introduced an async `Agent` plus a hub-based multi-agent network. It suits Python teams that want MCP, A2A and AG-UI built in.

## Key facts

| Field | Value |
| --- | --- |
| Type | Framework |
| Languages / SDKs | Python |
| License | Apache-2.0 |
| Pricing model | Unknown |
| Orchestration pattern | Other |
| GitHub stars | 4,970 (as of 2026-10-01) |
| GitHub forks | 731 |
| Last push | 2026-09-30 |
| Latest release | v1.1.1 |
| Repository | [ag2ai/ag2](https://github.com/ag2ai/ag2) |
| Website | [ag2.ai](https://ag2.ai) |
| Documentation | [docs.ag2.ai](https://docs.ag2.ai/) |
| Last verified | 2026-09-30 |

## Key features

- Async `Agent` API: `agent.ask()` starts a turn and `reply.ask()` continues the same conversation. ([source](https://docs.ag2.ai/docs/user-guide/quick-start/))
- `ag2.network`: a hub with registry, write-ahead logs and audit log, plus typed channels (conversation, consulting, discussion, workflow). ([source](https://docs.ag2.ai/docs/user-guide/network/overview/))
- Subagents: `Agent.as_tool()` exposes one agent as a tool of another, each call running on its own isolated stream. ([source](https://docs.ag2.ai/docs/user-guide/subagents/))
- Opt-in harness pieces: a `KnowledgeStore` for persistent memory, context assembly policies and history compaction. ([source](https://docs.ag2.ai/docs/user-guide/agent_harness/))
- MCP in both directions: `MCPToolkit` consumes MCP servers and `ag2.mcp.MCPServer` serves an agent to MCP clients. ([source](https://docs.ag2.ai/docs/user-guide/tools/serving_mcp/))
- `ag2.a2a`: serve an agent over A2A (JSON-RPC, REST or gRPC) or call a remote A2A agent as a model provider. ([source](https://docs.ag2.ai/docs/user-guide/a2a/overview/))
- `AGUIStream` bridges an agent to AG-UI events, including run interrupts and tool-call approval in the frontend. ([source](https://docs.ag2.ai/docs/user-guide/ag-ui/overview/))
- ACP client that launches and drives CLI coding agents (Claude Code, Codex, OpenCode, Kilo Code) as AG2 agents. ([source](https://docs.ag2.ai/docs/user-guide/acp/client/))

## Architecture and orchestration pattern

Pattern: Other.

AG2 v1.0 is built around an async `Agent` that calls a model provider, runs the tool-calling loop and publishes every step (model calls, tool calls, human-input requests) as events on a stream. Optional harness components add context assembly policies, a path-based `KnowledgeStore` for memory across runs, history compaction and sub-task delegation. Middleware covers retries, token budgets and similar concerns.

Multi-agent work has two routes. Within one agent, other agents can be attached as tools with `Agent.as_tool()`; the calling model decides when to delegate. For coordinated teams, `ag2.network` sets up a hub-and-spoke network: the hub holds the registry, per-channel write-ahead logs, governance rules and an audit log, and agents exchange envelopes over channels whose adapter sets the rules (free two-party conversation, one-question consulting, round-robin discussion, or a workflow driven by a declarative, JSON-serialisable `TransitionGraph`). The workflow adapter is the documented replacement for the classic `GroupChat`. The hub runs in-process by default or over WebSocket for multi-process deployments.

State is externalised behind `History`, `Storage` and `Stream` protocols that can be backed by Redis or a database. `agent.resume()` rebuilds a turn from recorded events, and network channel transcripts can be replayed from the write-ahead log.

### Human in the loop

A tool can call `context.input(...)` to pause the run and ask a person; the agent's `hitl_hook` decides how the question is answered (CLI prompt, web UI, queue). The built-in `approval_required()` tool middleware asks the user to approve or deny a specific tool call before it runs, with an option to always allow that tool for the rest of the conversation. In a network, a `HumanClient` joins channels as a non-LLM participant that your UI drives. Over AG-UI, a run can end with an interrupt and be resumed by a later run on the same thread, and a gated tool call can be sent to the frontend for approval. When AG2 drives a CLI coding agent over ACP, its permission requests go to the same hook unless `permission_policy` is set to auto-approve or deny.

### Harnesses it can drive

- Claude Code ([evidence](https://docs.ag2.ai/docs/user-guide/acp/client/))
- Codex ([evidence](https://docs.ag2.ai/docs/user-guide/acp/client/))
- OpenCode ([evidence](https://docs.ag2.ai/docs/user-guide/acp/client/))

## Protocols

| Protocol | Support | Evidence | Note |
| --- | --- | --- | --- |
| MCP | Yes (checked 2026-09-30) | [link](https://docs.ag2.ai/docs/user-guide/tools/serving_mcp/) | Client and server: `MCPToolkit` / `MCPServerTool` consume MCP servers, and `ag2.mcp.MCPServer` exposes an AG2 agent to any MCP client (`ag2[mcp]` extra). |
| A2A | Yes (checked 2026-09-30) | [link](https://docs.ag2.ai/docs/user-guide/a2a/overview/) | Client and server: `A2AServer` serves an agent over JSON-RPC, REST or gRPC and `A2AConfig` lets an agent call a remote A2A endpoint; needs `ag2[a2a]` plus `a2a-sdk` transport extras for serving. |
| AG-UI | Yes (checked 2026-09-30) | [link](https://docs.ag2.ai/docs/user-guide/ag-ui/overview/) | Server side: `ag2.ag_ui.AGUIStream` emits AG-UI text, tool-call, state-snapshot and interrupt events (`ag2[ag-ui]` extra); the AG-UI README also lists AG2 under 1st-party integrations. |

## Best for

- Orchestrating CLI coding agents such as Claude Code, Codex and OpenCode from Python over ACP ([shortlist](https://multiagentguide.top/best/coding-agents.md))
- Multi-agent setups that need turn-order rules, an audit log and replayable transcripts ([shortlist](https://multiagentguide.top/best/enterprise-governance.md))
- Agents that other systems must reach over MCP, A2A or AG-UI without third-party adapters
- New Python projects that can start directly on the v1.0 async API

## Not for

- Existing code built on `import autogen`, `ConversableAgent` or `GroupChat` that cannot absorb a rewrite; that code belongs on `ag2-classic`
- Non-Python stacks; the framework is Python only
- AG-UI deployments behind a plain round-robin load balancer, since resuming an interrupted turn needs sticky routing

## Quickstart

```sh
pip install "ag2[openai]"
```

Install verified 2026-09-30 (uv venv, Python 3.12.13, macOS arm64: `uv pip install ag2[openai]` ok, `from ag2 import Agent` ok, ag2 1.1.0. Packages came from the mirrors.aliyun.com mirror, so the version is the one that mirror served on this date. Install and import check only; not a functional test.).

```python
import asyncio
from ag2 import Agent
from ag2.config import OpenAIConfig

config = OpenAIConfig("gpt-4o-mini")  # reads OPENAI_API_KEY
researcher = Agent("researcher", prompt="Return three short factual findings.", config=config)
writer = Agent("writer", prompt="Turn the notes you get into one clear paragraph.", config=config)
coordinator = Agent("coordinator", config=config,
    prompt="Delegate research first, then pass the findings to the writer.",
    tools=[researcher.as_tool(description="Research a topic and return findings."),
           writer.as_tool(description="Write prose from notes passed as context.")])

async def main() -> None:
    reply = await coordinator.ask("Write a short note on the A2A protocol.")
    print(reply.body)

asyncio.run(main())
```

### Common pitfalls

- Requires Python >= 3.10. Only minimal dependencies install by default; add the extra for your provider (`ag2[openai]`, `ag2[anthropic]`, `ag2[gemini]`, ...).
- Provider configs read the standard environment variable (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`).
- `pip install ag2` (v1.0+) no longer ships the `autogen` import name or `ConversableAgent` / `GroupChat`; code using them needs `pip install ag2-classic`, and moving it to v1.0 is a rewrite, not an upgrade (see the group chat migration guide).
- The API is async throughout; call `ask()` from inside an event loop.
- Protocol features are extras: `ag2[mcp]`, `ag2[a2a]` (serving also needs `a2a-sdk[http-server]` or `a2a-sdk[grpc]`), `ag2[ag-ui]`, `ag2[acp]`.

Official quickstart: https://docs.ag2.ai/docs/user-guide/quick-start/

## Pros

- MCP works in both directions: agents can use MCP tools and can themselves be served as MCP servers. ([source](https://docs.ag2.ai/docs/user-guide/tools/serving_mcp/))
- A2A server and client ship in the package, with JSON-RPC, REST and gRPC bindings. ([source](https://docs.ag2.ai/docs/user-guide/a2a/overview/))
- AG-UI support is built in, including interrupts and frontend approval of tool calls. ([source](https://docs.ag2.ai/docs/user-guide/ag-ui/overview/))
- Can launch and supervise Claude Code, Codex and OpenCode sessions through ACP and stream their steps. ([source](https://docs.ag2.ai/docs/user-guide/acp/client/))
- The network hub records a write-ahead log and audit trail and enforces per-agent rules. ([source](https://docs.ag2.ai/docs/user-guide/network/overview/))

## Cons

- AG2 v1.0 is not a drop-in upgrade from AG2 Classic: the agent model, orchestration and imports all changed. ([source](https://github.com/ag2ai/ag2/blob/main/README.md))
- Older tutorials using `import autogen`, `ConversableAgent` or `GroupChat` target the separate `ag2-classic` package and do not run on `ag2` 1.x. ([source](https://github.com/ag2ai/ag2/blob/main/README.md))
- An interrupted AG-UI turn is held in one process: resumes need sticky routing, and a restart drops held turns. ([source](https://docs.ag2.ai/docs/user-guide/ag-ui/overview/))
- `agent.resume()` can fail on providers that attach required metadata to replayed calls, such as Gemini 3.x thought signatures. ([source](https://docs.ag2.ai/docs/user-guide/resume/))
- The website promotes hosted products (AG2 Space, an AgentOS platform) behind a request-access form with no published pricing. ([source](https://ag2.ai))

## Alternatives

- [AutoGen](https://multiagentguide.top/tools/autogen.md) ([AG2 vs AutoGen](https://multiagentguide.top/compare/ag2-vs-autogen.md))
- [Microsoft Agent Framework](https://multiagentguide.top/tools/microsoft-agent-framework.md)
- [CrewAI](https://multiagentguide.top/tools/crewai.md)
- [OpenAI Agents SDK (Python)](https://multiagentguide.top/tools/openai-agents-sdk.md)
- [Pydantic AI](https://multiagentguide.top/tools/pydantic-ai.md)

## FAQ

### How is AG2 different from AutoGen?

AG2's docs say it diverged from the AutoGen codebase in November 2024. In v1.0 it moved the AutoGen-style API to `ag2-classic` and switched to an async `Agent` and a hub-based network, while Microsoft's AutoGen is in maintenance mode.

### Can I still use `import autogen` and `ConversableAgent`?

Yes, through AG2 Classic: `pip install ag2-classic`, documented at classic.docs.ag2.ai. The `ag2` package from v1.0 no longer includes that namespace.

### Does AG2 support MCP, A2A and AG-UI?

Yes, all three are first-party. MCP works as client and server, A2A as client and server, and `AGUIStream` exposes agents to AG-UI frontends. Each needs its own install extra.

### Can AG2 drive Claude Code or Codex?

Yes. With `ag2[acp]`, `ClaudeCodeConfig`, `CodexConfig` and `OpenCodeConfig` launch those CLIs as ACP agents, and AG2 streams their messages, tool calls and permission prompts.

### Is AG2 free?

The framework is Apache-2.0. The AG2 website also advertises hosted products behind a request-access form without public pricing, so the pricing model is listed as unknown.

## Sources

- [AG2 GitHub repository](https://github.com/ag2ai/ag2)
- [AG2 documentation](https://docs.ag2.ai/)
- [AG2 README (AG2 Classic split, install, examples)](https://github.com/ag2ai/ag2/blob/main/README.md)
- [AG2 homepage](https://ag2.ai)
- [AG2 overview: why AG2 exists (docs)](https://docs.ag2.ai/docs/user-guide/motivation/)
- [AG2 Quick Start (docs)](https://docs.ag2.ai/docs/user-guide/quick-start/)
- [Multi-Agent Network overview (AG2 docs)](https://docs.ag2.ai/docs/user-guide/network/overview/)
- [Migrating from Group Chat (AG2 docs)](https://docs.ag2.ai/docs/user-guide/network/migration_from_group_chat/)
- [Subagents (AG2 docs)](https://docs.ag2.ai/docs/user-guide/subagents/)
- [The Agent Harness (AG2 docs)](https://docs.ag2.ai/docs/user-guide/agent_harness/)
- [Human in the Loop (AG2 docs)](https://docs.ag2.ai/docs/user-guide/context/human_in_the_loop/)
- [Approval Required middleware (AG2 docs)](https://docs.ag2.ai/docs/user-guide/tools/approval_required/)
- [Resuming a turn (AG2 docs)](https://docs.ag2.ai/docs/user-guide/resume/)
- [MCP Servers as tools (AG2 docs)](https://docs.ag2.ai/docs/user-guide/tools/mcp_servers/)
- [Serving an Agent as an MCP Server (AG2 docs)](https://docs.ag2.ai/docs/user-guide/tools/serving_mcp/)
- [A2A Protocol overview (AG2 docs)](https://docs.ag2.ai/docs/user-guide/a2a/overview/)
- [AG-UI integration overview (AG2 docs)](https://docs.ag2.ai/docs/user-guide/ag-ui/overview/)
- [Driving CLI Coding Agents as an ACP Client (AG2 docs)](https://docs.ag2.ai/docs/user-guide/acp/client/)
- [Human Clients in the network (AG2 docs)](https://docs.ag2.ai/docs/user-guide/network/human_client/)
- [AG2 Classic repository](https://github.com/ag2ai/ag2-classic)
- [AG2 Classic documentation](https://classic.docs.ag2.ai)
- [AG2 v1.1.1 release](https://github.com/ag2ai/ag2/releases/tag/v1.1.1)
- [AG-UI README, supported integrations](https://github.com/ag-ui-protocol/ag-ui/blob/main/README.md)

## Unknown fields

pricing_model: the framework is Apache-2.0, but ag2.ai promotes AG2 Space and an AgentOS platform behind 'Request Access' and no pricing page exists (https://ag2.ai/pricing returned 404 on 2026-09-30), so it is unclear whether a paid hosted product is offered.

Corrections or removal requests: support@multiagentguide.top

---

Data as of 2026-10-01. Not affiliated with listed projects. HTML version: https://multiagentguide.top/tools/ag2