AutoGen and AG2 Migration Guide
Which migration path applies to your AutoGen code — AutoGen 0.2 to AG2 Classic, Classic to AG2 1.x, or Microsoft AutoGen 0.4+ to Agent Framework or AG2 — with verified before/after code.
Checked 2026-11-19 against
autogen0.14.1 (AG2 Classic),ag21.3.2 andautogen-agentchat0.7.5.
An earlier version of this page said Microsoft AutoGen had been “rebranded as AG2 (AutoGen 2.0)” and that switching was a matter of renaming the package. That was wrong. AG2 is a fork created in November 2024 by AutoGen’s original authors from the AutoGen 0.2 code base; Microsoft continued its own project, rewrote it as 0.4 (January 2025), put it into maintenance mode in favour of Microsoft Agent Framework, and has since archived the repository. “Migrating to AG2” therefore means different things depending on which AutoGen you have.
Which AutoGen do you have?
Section titled “Which AutoGen do you have?”| Your imports | You are on | Status | Paths |
|---|---|---|---|
import autogen, from autogen import ConversableAgent with pyautogen ≤ 0.2.x installed | AutoGen 0.2 (Microsoft, pre-fork) | Unmaintained | A or B |
import autogen with autogen or ag2<1.0 installed | AG2 Classic | Maintenance mode | B |
from autogen_agentchat ..., from autogen_core ... | Microsoft AutoGen 0.4–0.7 | Archived | C |
import ag2 | AG2 1.x | Active | — |
Watch the package names: pyautogen now installs Microsoft’s autogen-agentchat, autogen installs AG2 Classic, and ag2>=1.0 installs the new AG2 framework, which no longer contains the autogen module.
Path A: AutoGen 0.2 → AG2 Classic
Section titled “Path A: AutoGen 0.2 → AG2 Classic”The lowest-effort move: AG2 Classic kept the 0.2 API, so most code runs with only a dependency change. Choose this to keep an existing system alive; Classic receives security and critical fixes only.
pip uninstall -y pyautogenpip install "autogen[openai]" # or: pip install "ag2[openai]<1.0"The upstream ag2 README mentions pip install ag2-classic, but no package of that name is on PyPI; the Classic distribution is autogen.
autogen[openai]>=0.14.1,<0.15Typical code keeps working unchanged:
from autogen import AssistantAgent, LLMConfig, UserProxyAgentfrom autogen.coding import LocalCommandLineCodeExecutor
llm_config = LLMConfig({"api_type": "openai", "model": "gpt-6-luna"})
assistant = AssistantAgent("assistant", llm_config=llm_config)user_proxy = UserProxyAgent( "user_proxy", human_input_mode="NEVER", code_execution_config={"executor": LocalCommandLineCodeExecutor(work_dir="coding")},)# user_proxy.initiate_chat(assistant, message="Write a function that returns the nth prime.")Things that do need changing:
- Config lists:
{"config_list": [...]}dicts still work, butLLMConfig({...})/LLMConfig.from_json(path="OAI_CONFIG_LIST")is the current form.config_list_from_jsonis no longer exported at the top ofautogen; import it fromautogen.llm_config.configif you still need it. - Code executors: pass an executor object (
LocalCommandLineCodeExecutor,DockerCommandLineCodeExecutor) incode_execution_config["executor"]; combiningexecutorwithwork_dir/use_dockerkeys raisesValueError. The plain{"work_dir": ..., "use_docker": ...}form withoutexecutorstill works. - Swarms:
SwarmAgent/initiate_swarm_chatlived inautogen.agentchat.contrib.swarm_agentup toag20.13.x and were removed in 0.14.0. Port them to group-chat patterns with handoffs (autogen.agentchat.group.patterns,agent.handoffs; see Group-chat patterns and handoffs), or pinag2==0.13.*until you can. - Contrib modules that depended on third-party libraries may need their extras (
autogen[retrievechat],autogen[a2a], …).
Path B: AG2 Classic → AG2 1.x
Section titled “Path B: AG2 Classic → AG2 1.x”AG2 1.0 (July 2026) replaced the Classic API with an async, event-driven framework imported as ag2. This is a rewrite of your agent code, not an upgrade.
Before (Classic):
from autogen import ConversableAgent, LLMConfig, register_function
llm_config = LLMConfig({"api_type": "openai", "model": "gpt-6-luna"})assistant = ConversableAgent("assistant", system_message="Use tools when helpful.", llm_config=llm_config)user = ConversableAgent("user", human_input_mode="NEVER", llm_config=False)
def get_weather(city: str) -> str: return f"It is sunny in {city}."
register_function(get_weather, caller=assistant, executor=user, description="Get the weather for a city.")# user.initiate_chat(assistant, message="Weather in Paris?", max_turns=2)After (AG2 1.x):
import asyncio
from ag2 import Agent, toolfrom ag2.config import OpenAIConfig
@tooldef get_weather(city: str) -> str: """Get the weather for a city.""" return f"It is sunny in {city}."
assistant = Agent( "assistant", prompt="Use tools when helpful.", config=OpenAIConfig(model="gpt-6-luna"), tools=[get_weather],)
# reply = asyncio.run(assistant.ask("Weather in Paris?")); print(reply.body)| Classic | AG2 1.x |
|---|---|
ConversableAgent(name, system_message=..., llm_config=...) | Agent(name, prompt=..., config=OpenAIConfig(...)) |
LLMConfig / OAI_CONFIG_LIST | One provider config object per model (OpenAIConfig, AnthropicConfig, …) |
register_function(f, caller=..., executor=...) | @tool + tools=[...]; no executor agent |
initiate_chat(...) / generate_reply(...) | await agent.ask(...), then await reply.ask(...) to continue |
human_input_mode="ALWAYS" | a tool calling await context.input(...) + hitl_hook= |
GroupChat / GroupChatManager / group-chat patterns | ag2.network.Hub + a workflow channel driven by a TransitionGraph |
| Swarms, handoffs, nested chats | Channels on the Network; agent.as_tool(...) for sub-agents |
LocalCommandLineCodeExecutor / DockerCommandLineCodeExecutor | SandboxCodeTool / SandboxShellTool from ag2.tools with a LocalEnvironment (trusted code), DockerEnvironment or DaytonaEnvironment |
autogen.testing.TestAgent | ag2.testing.TestConfig |
autogen.beta.* (preview in ag2 0.11.4–0.14) | Same names, imported from ag2 |
CodeExecutionTool and ShellTool in ag2.tools are different: they are provider-hosted tools that run code in the model provider’s own sandbox (for example OpenAI’s container), not on your machine, so they are not drop-in replacements for Classic executors.
Porting order that works well:
- Replace each
LLMConfigwith one provider config object and move keys to environment variables. - Turn registered functions into
@toolfunctions passed intools=[...]. The executor agents go away, because AG2 1.x runs tools itself. - Replace
initiate_chatwithawait agent.ask(...)and wrap entry points inasyncio.run. - Replace
human_input_modewith a tool that callsawait context.input(...), plushitl_hook=on the agent. - Rebuild group chats as a
workflowchannel with aTransitionGraph(upstream guide: “Migrating from Group Chat” on docs.ag2.ai). - Port tests last: scripted
TestAgentreplies becomeTestConfig(...)turns.
The AG2 guide covers the 1.x API in full, including a Network example equivalent to a sequential group chat.
Path C: Microsoft AutoGen 0.4+ → Agent Framework or AG2
Section titled “Path C: Microsoft AutoGen 0.4+ → Agent Framework or AG2”Code using autogen_agentchat / autogen_core shares no API with AG2 (Classic or 1.x); moving it to AG2 is a rewrite. Because Microsoft AutoGen is archived, choose a maintained target:
- Microsoft Agent Framework (
agent-framework1.26.0) is Microsoft’s designated successor, with an official AutoGen migration guide mappingAssistantAgent, teams andGraphFlowonto agents and Workflows. See the Agent Framework guide. - AG2 1.x if you prefer the community project: the concepts map reasonably well (
AssistantAgent→Agent;FunctionTool→@tool;GraphFlow/SelectorGroupChat→workflowchannels with aTransitionGraph;ReplayChatCompletionClient→ag2.testing.TestConfig).
Until you migrate, pin your AutoGen versions exactly (see the AgentChat & Core reference), including integration dependencies such as mcp<2.
Troubleshooting
Section titled “Troubleshooting”ModuleNotFoundError: No module named 'autogen' after an upgrade. ag2 was upgraded to 1.x, or pyautogen now resolves to Microsoft AutoGen. Install autogen (Classic) or pin ag2<1.0, or port to import ag2.
ModuleNotFoundError: No module named 'autogen_agentchat'. The code is Microsoft AutoGen 0.4+; install autogen-agentchat and autogen-ext[openai], not ag2.
TypeError: LLMConfig.from_json() takes 1 positional argument. Pass the file as a keyword: LLMConfig.from_json(path="OAI_CONFIG_LIST") (or env="OAI_CONFIG_LIST").
ValueError: 'work_dir' in code_execution_config is not valid when 'executor' is set. Move work_dir / timeout onto the executor object.
Both autogen and ag2 installed in one environment. autogen and ag2<1.0 provide the same autogen module and will overwrite each other; keep one.
Resources
Section titled “Resources”- AG2: docs.ag2.ai · github.com/ag2ai/ag2
- AG2 Classic: classic.docs.ag2.ai · github.com/ag2ai/ag2-classic
- Microsoft AutoGen (archived): github.com/microsoft/autogen
- Microsoft Agent Framework: github.com/microsoft/agent-framework
Revision history
Section titled “Revision history”| Date | Changes |
|---|---|
| 2026-10-21 | Moved from /autogen-guide/python/autogen_to_ag2_migration_guide/; now the single migration page (the Classic and 1.x comprehensive guides link here). Swarm removal in 0.14.0, the code-executor mapping and a porting order added. |