AG2 (AutoGen 2.0)

Overview

AG2 (formerly AutoGen) is Microsoft Research's next-generation multi-agent conversation framework. Version 2.0 represents a complete rewrite with improved architecture, better performance, and enhanced developer experience. It enables developers to build sophisticated multi-agent systems through natural conversation patterns.

Key Features

💬 Conversation-Centric Programming

AG2's core philosophy is that complex problems are best solved through conversation:

import autogen

# Define agents with specific roles
user_proxy = autogen.UserProxyAgent(
    name="UserProxy",
    is_termination_msg=lambda x: x.get("content", "") and "TERMINATE" in x.get("content", ""),
    human_input_mode="NEVER",
    max_consecutive_auto_reply=10,
    code_execution_config={"work_dir": "coding"}
)

assistant = autogen.AssistantAgent(
    name="Assistant",
    llm_config={"config_list": [{"model": "gpt-4o", "api_key": "..."}]},
    system_message="You are a helpful AI assistant."
)

# Start conversation
user_proxy.initiate_chat(
    assistant,
    message="Write a Python function to calculate Fibonacci numbers.",
)

🔄 Group Chat Management

Orchestrate multiple agents in structured group conversations:

from autogen import GroupChat, GroupChatManager

# Define participants
agents = [user_proxy, assistant, coder, reviewer]

# Create group chat
group_chat = GroupChat(
    agents=agents,
    messages=[],
    max_round=12,
    speaker_selection_method="auto"
)

# Manage the conversation
manager = GroupChatManager(
    groupchat=group_chat,
    llm_config={"config_list": [{"model": "gpt-4o"}]}
)

# Start group discussion
user_proxy.initiate_chat(
    manager,
    message="Design a REST API for a task management system."
)

🧪 Code Execution Agents

Built-in code execution with safety controls:

import autogen

# Agent that can execute code
code_executor = autogen.UserProxyAgent(
    name="CodeExecutor",
    is_termination_msg=lambda x: x.get("content", "") and "TERMINATE" in x.get("content", ""),
    human_input_mode="NEVER",
    code_execution_config={
        "work_dir": "coding",
        "use_docker": True,  # Safe sandboxed execution
        "timeout": 60
    }
)

# Agent that writes code
coder = autogen.AssistantAgent(
    name="Coder",
    llm_config={"config_list": [{"model": "gpt-4o"}]},
    system_message="You are a Python expert. Write clean, efficient code."
)

# Code generation and execution workflow
coder.initiate_chat(
    code_executor,
    message="Write and run a function to sort a list using quicksort."
)

📊 Flexible Agent Behaviors

Customize agent behavior with system messages and tools:

from autogen import AssistantAgent, UserProxyAgent
from autogen.tools import Tool

# Custom tool
@Tool
def search_web(query: str) -> str:
    """Search the web for information."""
    return web_search_results

# Agent with tools
researcher = AssistantAgent(
    name="Researcher",
    llm_config={"config_list": [{"model": "claude-3-5-sonnet"}]},
    system_message="You are a research assistant. Use tools to gather information.",
    tools=[search_web]
)

🎯 Human-in-the-Loop

Seamless human intervention at any point:

# Configure for human approval
user_proxy = UserProxyAgent(
    name="UserProxy",
    human_input_mode="ALWAYS",  # Always ask for human input
    is_termination_msg=lambda x: x.get("content", "") and "TERMINATE" in x.get("content", "")
)

# Or conditional human input
user_proxy = UserProxyAgent(
    name="UserProxy",
    human_input_mode="TERMINATE",  # Only ask when agent wants to terminate
    is_termination_msg=lambda x: x.get("content", "") and "TERMINATE" in x.get("content", "")
)

Installation

# Core package
pip install pyautogen

# With code execution (requires Docker)
pip install pyautogen[web-surfer,docker]

# With all optional dependencies
pip install pyautogen[all]

Supported Models

Provider	Models	Status
OpenAI	GPT-4o, GPT-4 Turbo, o1, o3	✅ Full
Anthropic	Claude 3.5 Sonnet, Claude 3 Opus	✅ Full
Google	Gemini 1.5 Pro, Gemini 2.0	✅ Full
Azure OpenAI	All Azure models	✅ Full
Ollama	Local models	✅ Full
Mistral	Mistral Large, Small	✅ Full
DeepSeek	DeepSeek V3, R1	✅ Full

Advanced Patterns

Heterogeneous Agent Teams

from autogen import AssistantAgent, UserProxyAgent

# Different agents for different tasks
writer = AssistantAgent(
    name="Writer",
    llm_config={"config_list": [{"model": "gpt-4o"}]},
    system_message="You are a creative writer."
)

editor = AssistantAgent(
    name="Editor",
    llm_config={"config_list": [{"model": "claude-3-5-sonnet"}]},
    system_message="You are a meticulous editor."
)

user_proxy = UserProxyAgent(
    name="UserProxy",
    human_input_mode="NEVER"
)

# Team workflow
user_proxy.initiate_chat(
    writer,
    message="Write a blog post about AI agents."
)

user_proxy.initiate_chat(
    editor,
    message="Edit this blog post: {writer_output}"
)

Sequential Handoffs

from autogen import Agent

# Chain agents sequentially
researcher = AssistantAgent(name="Researcher", ...)
analyst = AssistantAgent(name="Analyst", ...)
writer = AssistantAgent(name="Writer", ...)

# Sequential handoff
research_result = researcher.generate_reply(messages)
analysis_result = analyst.generate_reply(research_result)
final_output = writer.generate_reply(analysis_result)

Pros

• ✅ Microsoft Backed: Strong research support and enterprise focus
• ✅ Conversation Paradigm: Natural way to model complex workflows
• ✅ Code Execution: Built-in safe code execution with Docker
• ✅ Human-in-the-Loop: Excellent support for human intervention
• ✅ Flexible Architecture: Works for simple and complex scenarios
• ✅ Active Community: Large, active research community
• ✅ Multi-Language: Python and .NET support

Cons

• ❌ Learning Curve: Conversation paradigm takes time to master
• ❌ Documentation: Can be scattered across examples and docs
• ❌ API Changes: Rapid evolution leads to breaking changes
• ❌ Performance: Conversation overhead for simple tasks
• ❌ Debugging: Harder to debug multi-agent conversations

When to Use

Choose AG2 when:

• You're building complex multi-agent systems
• You need code execution capabilities
• You want human-in-the-loop support
• You're in a Microsoft/.NET ecosystem

Consider alternatives when:

• You want simpler agent orchestration (try CrewAI)
• You need type safety (try PydanticAI)
• You're building a quick prototype (try SmolAgents)

Use Cases

Use Case	Why AG2
Multi-Agent Systems	Natural conversation paradigm for complex workflows
Code Generation & Execution	Built-in safe code execution with Docker sandboxing
Human-in-the-Loop	Seamless human intervention at any point in the conversation
Research & Prototyping	Microsoft-backed research with active academic community

Comparison with Alternatives

Feature	AG2	CrewAI	LangGraph	AutoGen v1
Paradigm	Conversation-centric	Role-based	Graph-based	Conversation-centric
Code Execution	✅ Built-in	⚠️ Via tools	⚠️ Via tools	✅ Built-in
Human-in-the-Loop	✅ Excellent	⚠️ Limited	⚠️ Manual	✅ Good
Microsoft Backing	✅ Yes	❌ No	❌ No	✅ Yes (v1)
Learning Curve	Medium-High	Low	Medium	Medium
Best for	Complex multi-agent	Role-based teams	Custom orchestration	Legacy projects

Best Practices

1. Define clear agent roles — Use specific system messages for each agent
2. Use UserProxyAgent wisely — Configure human_input_mode appropriately
3. Set termination conditions — Define clear is_termination_msg criteria
4. Leverage group chat — Use GroupChatManager for multi-agent coordination
5. Enable code execution safely — Use Docker sandboxing for untrusted code

Troubleshooting

Issue	Solution
Agent stuck in loop	Check termination conditions are reachable
Code execution fails	Verify Docker is running and workspace permissions
Messages not routing	Check speaker_selection_method in GroupChat
LLM API errors	Verify config_list has valid API keys

Resources

• Official Docs: https://microsoft.github.io/autogen/
• GitHub: https://github.com/microsoft/autogen
• Examples: https://github.com/microsoft/autogen/tree/main/notebook
• Discord: https://discord.gg/pAbnFJrkgZ

Comparison

Feature	AG2	CrewAI	LangGraph
Paradigm	Conversation	Role-based	Graph-based
Code Execution	✅ Built-in	⚠️ Via tools	⚠️ Via tools
Human-in-the-Loop	✅ Excellent	⚠️ Limited	⚠️ Manual
Learning Curve	Medium-High	Low	Medium
Microsoft Support	✅ Yes	❌ No	❌ No

---

Last updated: May 2026