AG2 v1.0: the AgentOS rewrite, and what changed from AutoGen

The problem AG2 solves, and who it is actually for

AG2 is a Python framework for building AI agents and for coordinating several of them on one task. The README lists the pieces it covers: agents that interact with each other, support for multiple LLM providers, tool use, autonomous and human-in-the-loop workflows, and multi-agent conversation patterns. Each of those is a separate problem in a hand-rolled agent loop. Provider differences, tool-call plumbing, and the question of when a human must approve an action all have to be written from scratch otherwise.

The intended reader is a developer, not an end user. The project describes itself as a programming framework, ships as `pip install ag2`, and requires Python 3.10 or newer. There is no hosted product to sign into; the Playground linked from the README is a demonstration surface, not the deliverable. The deliverable is a library you import.

The audience widened in a specific way with v1.0. AG2 now has two distinct user groups: people starting fresh on the protocol-driven framework, and people with existing AutoGen code who should not move at all. The README treats the second group as a first-class concern, which is unusual and worth noting before anything else.

AG2 Classic versus AG2 v1.0: the split that decides your install command

The single most consequential fact in the repository is a rename plus a fork. As of v1.0, the protocol-driven framework is the top-level package, imported as `ag2`. The classic framework moved to its own repository, ag2ai/ag2-classic, with its own documentation site at classic.docs.ag2.ai. The `pip install ag2` distribution no longer ships the `autogen` import name or the classic agent classes.

The README gives a plain test for which side you are on. If your code contains any of the following, you are on Classic. The comment in the README says it directly: stay on it.

import autogen  # the autogen.* namespace
from autogen import ConversableAgent, GroupChat  # classic agent classes
from autogen import AssistantAgent, UserProxyAgent

The mapping between the two is not a rename table. The core agent changed from `ConversableAgent` to `Agent`. Multi-agent orchestration changed from `GroupChat`, swarms and nested chats to something the README calls Network, described as a hub plus channels. The README states plainly that AG2 v1.0 is not a drop-in upgrade from Classic and that the agent model, orchestration and imports all changed. A migration guide for group chat exists in the documentation, but the README does not claim the migration is automatic, and it does not document rollback.

If you are on Classic, the README's instruction is to pin the classic distribution rather than `ag2>=1.0`. That distribution is `ag2-classic`. The README states Classic remains maintained and installable and that existing code keeps working.

Installing AG2 and running a first agent

The install target is PyPI, the package name is `ag2`, and the minimum Python is 3.10. Dependencies are minimal by default, and you add an extra for your model provider. The README lists `ag2[openai]`, `ag2[anthropic]`, `ag2[gemini]` and `ag2[ollama]` as examples of that pattern. On Windows and Linux the README gives the unquoted form.

pip install ag2[openai]

On macOS the README quotes the extra, because the shell would otherwise interpret the brackets. If you copy the Windows form onto a Mac, this is the line that fails.

pip install 'ag2[openai]'

Provider configuration reads the standard environment variable for that provider, so keys stay out of source control. The README shows the OpenAI variable and names the equivalents for Anthropic and Gemini.

export OPENAI_API_KEY="<your-api-key>"     # or ANTHROPIC_API_KEY, GEMINI_API_KEY, ...

The README also documents passing a key explicitly, with `OpenAIConfig(model="gpt-4o-mini", api_key=...)`, and notes the use case: when each request brings its own key. That is the multi-tenant shape, and it is the reason a per-request config object exists at all rather than a single global setting.

One thing the README states that changes how you write the first call: AG2 is async throughout. The sentence is cut off mid-word in the README at the point where the first agent example would appear, so the full first-agent snippet is not available here. The documentation Quick Start at docs.ag2.ai is where the README sends you for the step-by-step version. Treat "async throughout" as a design constraint on your own code, not a detail you can defer.

How orchestration works: hub, channels, and the agent harness

The v1.0 orchestration model is the part that most differs from what AutoGen users remember. The README's comparison table names it Network, and describes it as a hub plus channels. In the classic framework the equivalent role was played by `GroupChat` with a `GroupChatManager`, plus swarms and nested chats. The shape changed from a conversation among peers coordinated by a manager to a topology where a hub and named channels define who can reach whom.

The README also introduces a concept it calls the agent harness, covering knowledge and compaction. Compaction is the interesting half. Long agent runs accumulate context, and something has to decide what survives. The README names the mechanism and stops there; the operational details of when compaction triggers are not in the README, and you should read the documentation before relying on it for a long-running workflow.

Beyond that, the README points at advanced agentic design patterns without enumerating them here. The repository layout shows where the protocol work lives: `examples/a2a/`, `examples/acp/`, `examples/mcp/` and `examples/sandbox/` are separate example directories. Those names correspond to the topics list, which includes `a2a` and `mcp`. The practical reading is that AG2 treats agent-to-agent protocols and tool protocols as first-class integration surfaces rather than user-contributed add-ons.

What the README does not give is a worked multi-agent example with the Network API in it. If your evaluation depends on seeing hub-and-channel code before you commit, the README alone will not settle it.

Where AG2 v1.0 is the wrong choice

The clearest failure mode is upgrading an existing AutoGen codebase in place. The README says v1.0 is not a drop-in upgrade, and it lists three things that all changed: the agent model, the orchestration, and the imports. An upgrade is therefore a rewrite of the coordination layer, not a version bump. If your project is stable and your `GroupChat` topology works, the README's own advice is to stay on Classic and pin `ag2-classic`.

A second boundary is Python version. AG2 requires 3.10 or newer. If you are pinned below that, the framework is not available to you at all, and no extra changes this.

A third is the async requirement. The README states AG2 is async throughout. Code that assumes a synchronous agent loop, or a codebase where the agent call sits inside a synchronous request handler, needs adaptation before the first agent runs. That is a real cost and the README does not offer a synchronous escape hatch.

Finally, consider the maintenance model. The README says the project is maintained by a group of volunteers from several organizations, and it invites contact with the administrators for anyone interested in becoming a maintainer. That is a description of governance, not a defect. It does mean the release cadence depends on volunteers, so if your adoption requires a support contract or a named vendor, this project is not that, and the README does not claim otherwise.

AG2 versus LangGraph: two different answers to the same question

The comparison people search for is AG2 against LangGraph, and the difference is in what each treats as the primary object. AG2's unit is the agent. The README's structure is a list of agent concepts: agents, tools, human in the loop, orchestrating multiple agents, the agent harness. Orchestration exists to connect agents, and the v1.0 Network model is a topology of agents connected through a hub and channels.

LangGraph's unit is the graph. You describe a computation as nodes and edges, and agents are one kind of node inside it. State and transitions are explicit and inspectable, which is why graph frameworks tend to appeal when the control flow itself is the hard part.

Neither is a superset of the other. If your problem is "several agents with different roles need to talk, use tools, and occasionally ask a human," AG2's vocabulary maps onto that directly. If your problem is "I have a state machine with conditional branches and I want to see it drawn," a graph-first framework expresses that more naturally. The honest way to choose is to write down which object you would draw on a whiteboard first: agents, or the flow between them.

One caveat on this comparison. The README does not mention LangGraph, so nothing here comes from the project's own positioning. It is a structural observation about the two models, not a claim about performance or feature coverage.

Licence, release cadence and the cost of staying current

AG2 is licensed under Apache-2.0. The `pyproject.toml` sets `license = "Apache-2.0"` and lists `LICENSE` in `license-files`. Apache-2.0 permits commercial use and modification and includes an explicit patent grant, which is the usual reason teams pick it over a copyleft licence. It also carries attribution and notice obligations. The repository contains a `NOTICE.md` file alongside `license_original/`, which suggests the project tracks upstream provenance; if you redistribute AG2, read those files rather than assuming the licence header alone tells the whole story. Nothing here is legal advice.

On cadence, the release history shows v1.0.2 on 2026-08-15, v1.0.3 on 2026-08-28, and v1.0.4 on 2026-09-07, with the last push to the default branch on 2026-09-08. The `pyproject.toml` version field reads 1.0.5. Three releases in roughly three weeks is a fast cycle for a framework that just changed its orchestration model. Fast is not the same as stable, and it means upgrade cost is a real line item: pin your version and read the release notes before moving.

Development tooling is worth knowing about because it tells you how the project tests. The `justfile` defines a `test` recipe that runs pytest with a marker filter excluding every LLM provider, and a separate `test-llm` recipe that runs the provider-marked tests. The default LLM mark in the `justfile` is `openai or gemini or anthropic or zai or ollama or dashscope`. The practical consequence for a fork or a contribution: the default test run does not touch a model provider, so provider-specific behaviour needs the second recipe and real credentials.

Editorial conclusion

Adopt AG2 v1.0 if you are starting a new Python multi-agent project and want an async framework with a hub-and-channel orchestration model and provider extras you select at install time. Do not adopt it as an upgrade path for existing AutoGen code: v1.0 is explicitly not a drop-in replacement, and the classic classes now live in ag2ai/ag2-classic under the autogen namespace. Before committing, verify three things against your own code: that your Python is 3.10 or newer, that you can pin ag2-classic instead of ag2>=1.0 if any file imports autogen, and that the Network hub-and-channels model covers the orchestration your current GroupChat setup performs, since the README points to a migration guide rather than an automatic conversion.

Frequently asked questions

Official sources

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