Skip to content
AgPy

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 autogen 0.14.1 (AG2 Classic), ag2 1.3.2 and autogen-agentchat 0.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.

Your importsYou are onStatusPaths
import autogen, from autogen import ConversableAgent with pyautogen ≤ 0.2.x installedAutoGen 0.2 (Microsoft, pre-fork)UnmaintainedA or B
import autogen with autogen or ag2<1.0 installedAG2 ClassicMaintenance modeB
from autogen_agentchat ..., from autogen_core ...Microsoft AutoGen 0.4–0.7ArchivedC
import ag2AG2 1.xActive—

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.

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.

Terminal window
pip uninstall -y pyautogen
pip 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.

requirements.txt
autogen[openai]>=0.14.1,<0.15

Typical code keeps working unchanged:

from autogen import AssistantAgent, LLMConfig, UserProxyAgent
from 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, but LLMConfig({...}) / LLMConfig.from_json(path="OAI_CONFIG_LIST") is the current form. config_list_from_json is no longer exported at the top of autogen; import it from autogen.llm_config.config if you still need it.
  • Code executors: pass an executor object (LocalCommandLineCodeExecutor, DockerCommandLineCodeExecutor) in code_execution_config["executor"]; combining executor with work_dir / use_docker keys raises ValueError. The plain {"work_dir": ..., "use_docker": ...} form without executor still works.
  • Swarms: SwarmAgent / initiate_swarm_chat lived in autogen.agentchat.contrib.swarm_agent up to ag2 0.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 pin ag2==0.13.* until you can.
  • Contrib modules that depended on third-party libraries may need their extras (autogen[retrievechat], autogen[a2a], …).

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, tool
from ag2.config import OpenAIConfig
@tool
def 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)
ClassicAG2 1.x
ConversableAgent(name, system_message=..., llm_config=...)Agent(name, prompt=..., config=OpenAIConfig(...))
LLMConfig / OAI_CONFIG_LISTOne 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 patternsag2.network.Hub + a workflow channel driven by a TransitionGraph
Swarms, handoffs, nested chatsChannels on the Network; agent.as_tool(...) for sub-agents
LocalCommandLineCodeExecutor / DockerCommandLineCodeExecutorSandboxCodeTool / SandboxShellTool from ag2.tools with a LocalEnvironment (trusted code), DockerEnvironment or DaytonaEnvironment
autogen.testing.TestAgentag2.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:

  1. Replace each LLMConfig with one provider config object and move keys to environment variables.
  2. Turn registered functions into @tool functions passed in tools=[...]. The executor agents go away, because AG2 1.x runs tools itself.
  3. Replace initiate_chat with await agent.ask(...) and wrap entry points in asyncio.run.
  4. Replace human_input_mode with a tool that calls await context.input(...), plus hitl_hook= on the agent.
  5. Rebuild group chats as a workflow channel with a TransitionGraph (upstream guide: “Migrating from Group Chat” on docs.ag2.ai).
  6. Port tests last: scripted TestAgent replies become TestConfig(...) 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-framework 1.26.0) is Microsoft’s designated successor, with an official AutoGen migration guide mapping AssistantAgent, teams and GraphFlow onto 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 → workflow channels with a TransitionGraph; ReplayChatCompletionClient → ag2.testing.TestConfig).

Until you migrate, pin your AutoGen versions exactly (see the AgentChat & Core reference), including integration dependencies such as mcp<2.

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.


DateChanges
2026-10-21Moved 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.