AG2 v1.0: A Protocol-Driven Agent Framework That Breaks with Its AutoGen Past

What AG2 v1.0 Actually Changes

AG2 v1.0 is not an incremental release. The README is explicit: the top-level package is now `ag2`, and the classic `autogen.*` namespace has moved to a separate repository, `ag2ai/ag2-classic`. That split is the single most important fact for anyone evaluating this project. The classic agent classes like `ConversableAgent`, `AssistantAgent`, and `GroupChat` are no longer shipped with `pip install ag2`. The new core agent is simply called `Agent`, and multi-agent orchestration is handled by something called a Network, described as a hub plus channels. The README warns that AG2 v1.0 is not a drop-in upgrade from Classic: the agent model, orchestration, and imports all changed. If you have existing AutoGen-based code, this is not a migration; it is a rewrite. The project is positioning itself as an AgentOS, but the v1.0 release is really a breaking architectural pivot.

The Mechanism: Async-First and Protocol-Driven

The README states that AG2 is async throughout. That is a design choice with real consequences: it means the framework is built around coroutines and event loops rather than the blocking, synchronous calls that dominated the original AutoGen. The phrase "protocol-driven framework" appears in the README's important note, suggesting that agent interactions are defined by protocols rather than by concrete class hierarchies. The README does not provide a detailed data-flow diagram, but it does mention a Network model with a hub and channels. A hub likely routes messages between channels, each channel representing a communication path for a group of agents. This is a departure from the classic GroupChat pattern, where a single manager coordinated turns. The docs link points to a migration guide for group chat users, which implies the new model is not backward-compatible. Without running the code, the exact semantics of hubs and channels are not fully specified in the README, but the architectural direction is clear: more structured, more asynchronous, and less dependent on a central chat manager.

Getting Started: Installation and First Agent

The README provides concrete installation commands. For Windows or Linux, it is `pip install ag2[openai]`; for Mac, it is `pip install 'ag2[openai]'` with quotes to protect the brackets. Python 3.10 or later is required. The base install has minimal dependencies, and you are expected to add an extra that matches your model provider: `ag2[openai]`, `ag2[anthropic]`, `ag2[gemini]`, `ag2[ollama]`, and so on. API keys are read from standard environment variables, so you export `OPENAI_API_KEY` or `ANTHROPIC_API_KEY` rather than hardcoding them. Alternatively, you can pass a key explicitly with `OpenAIConfig(model="gpt-4o-mini", api_key=...)`, which the README says is useful when each request has its own key. The quick start example is cut off in the README, but the pattern is clear: import `ag2`, create an `Agent`, and run it asynchronously. The README mentions a Playground at playground.ag2.ai and a separate examples repository, which are useful for seeing actual code before you install.

The Classic Split: A Real Limitation for Existing Users

The biggest limitation is the forced fork. The README states that if your code contains `import autogen`, `from autogen import ConversableAgent, GroupChat`, or similar, you are on Classic and should stay on it. Classic remains maintained and installable via `pip install ag2-classic`, but it is now a separate project with its own documentation site. That means two distributions, two import namespaces, and two sets of docs to track. For teams with large AutoGen codebases, upgrading to AG2 v1.0 is not an option without rewriting agent definitions, orchestration logic, and import statements. The README explicitly says AG2 v1.0 is not a drop-in upgrade. This is a genuine failure mode: if you adopt AG2 v1.0 expecting to reuse classic patterns, you will hit a wall. The framework is also async throughout, which is a learning curve for developers who are not comfortable with asyncio. The README does not mention any sync compatibility layer, so assume you must write async code.

The Alternative: AG2 Classic and Its GroupChat Model

The obvious alternative is AG2 Classic, which is the original AutoGen-derived framework. The README describes it as having the `autogen.*` namespace and classes like `ConversableAgent`, `AssistantAgent`, `UserProxyAgent`, `GroupChat` and `GroupChatManager`, plus swarms, `register_function`, and `LLMConfig` or `OAI_CONFIG_LIST`. Classic supports nested and sequential chat patterns. The core difference is orchestration: Classic uses a GroupChat with a manager to coordinate turns among agents, while AG2 v1.0 uses a Network with a hub and channels. That is not a cosmetic change; it changes how you design agent interactions. If you need the mature GroupChat pattern, or you have code that uses `OAI_CONFIG_LIST` for model configuration, Classic is the safer choice. The README even provides a table comparing the two, with Classic's core agent being `ConversableAgent` and AG2's being `Agent`. For new projects, the question is whether you want the newer Network model or the battle-tested GroupChat. The README points to a migration guide for group chat users, which suggests the maintainers expect many to need help making the switch.

Maintenance and Licensing

The project is licensed under Apache-2.0, which is permissive and allows commercial use, modification, and redistribution, with the requirement to preserve copyright notices. The repository is actively maintained, with the last push dated 2026-09-08 and recent releases v1.0.2, v1.0.3, and v1.0.4 in the weeks before. The README states that the project is maintained by a group of volunteers from several organizations, and it invites contact to become a maintainer. That is a double-edged sword: volunteer maintenance can mean slower response times, but the release cadence suggests ongoing activity. The maintenance cost for users is significant because of the split. You must choose between two distributions and keep track of which one you are on. The README does not detail a deprecation policy for Classic, but it says Classic remains maintained and installable. For upgrade cost, the v1.0 release is a major breaking change, so you should budget for rewriting code if you move from Classic. The documentation sites are separate, which adds overhead when searching for answers.

Who Should Use AG2 v1.0 and What to Verify

AG2 v1.0 is for developers who are starting fresh and want a modern, async-first framework with explicit provider extras and a structured Network model. It is not for teams with existing AutoGen code unless they are prepared to rewrite. Before adopting, verify that your Python environment is 3.10 or higher, and check that your preferred model provider has an extra (e.g., `ag2[openai]`). Also confirm that the Network model supports the interaction patterns you need, such as human-in-the-loop workflows and tool use, which the README lists as features but does not detail for v1.0. The README mentions autonomous and human-in-the-loop workflows, but the specifics are in the docs, not the README, so you should read the quick start and the Network overview before committing. If you are unsure, try the Playground or the examples repository to see whether the new paradigm fits your use case. The async requirement is non-negotiable, so assess your team's comfort with asyncio.

Editorial conclusion

Adopt AG2 v1.0 if you are starting a new multi-agent project and want a modern, async-first framework with explicit provider extras and a hub-and-channel orchestration model. Do not adopt it if you rely on the classic AutoGen API: the README states that `import autogen`, `ConversableAgent`, and `GroupChat` are now in a separate distribution, `ag2-classic`, and that AG2 v1.0 is not a drop-in upgrade. Before committing, verify that your existing agent patterns can be expressed as a Network of channels and that your Python environment is >= 3.10. Also check the migration guide for group chat users if you are coming from Classic. If you need the mature, well-documented GroupChat patterns, pin `ag2-classic` instead of `ag2>=1.0`.

Official sources

1. ag2ai/ag2 on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases