AutoGen Documentation

Introduction

AutoGen is a Microsoft research project that provides a framework for building multi-agent conversation systems. It enables developers to create sophisticated AI applications through natural agent-to-agent conversations.

Installation

pip install pyautogen

Quick Start

Define Your Agents

from autogen import AssistantAgent, UserProxyAgent

assistant = AssistantAgent(
    name="assistant",
    system_message="You are a helpful assistant.",
)

user_proxy = UserProxyAgent(
    name="user_proxy",
    code_execution_config={"work_dir": "coding", "use_docker": False},
    human_input_mode="NEVER",
)

Start a Conversation

user_proxy.initiate_chat(
    assistant,
    message="Write and run Python code to print 'Hello World'",
)

Conversation Patterns

Two-Agent Conversation

user_proxy.initiate_chat(assistant, message="...")

Group Chat

from autogen import GroupChat, GroupChatManager

group_chat = GroupChat(agents=[assistant, user_proxy], messages=[])
manager = GroupChatManager(groupchat=group_chat)
user_proxy.initiate_chat(manager, message="...")

Code Execution

AutoGen can automatically write and execute code:

assistant = AssistantAgent(
    name="assistant",
    llm_config={"config_list": config_list},
)

user_proxy = UserProxyAgent(
    name="user_proxy",
    code_execution_config={"work_dir": "coding", "use_docker": False},
)

user_proxy.initiate_chat(
    assistant,
    message="Plot a chart of NVDA and TESLA stock price change YTD",
)

Human-in-the-Loop

user_proxy = UserProxyAgent(
    name="user_proxy",
    human_input_mode="ALWAYS",  # Always ask for human input
)

Use Cases

AutoGen excels in scenarios requiring natural multi-agent conversations and emergent behavior:

Use Case	Why AutoGen
Multi-Agent Research	Agents debate and refine answers through conversation
Code Generation & Review	Assistant writes code, reviewer critiques, iterates
Creative Collaboration	Multiple agents brainstorm and iterate on ideas
Customer Service Teams	Triage → Specialist → Resolution agents in conversation
Educational Tutors	Multiple tutor agents with different teaching styles

Pros & Cons

✅ Pros

• Natural conversation model — Intuitive for building conversational systems
• Low barrier to entry — Simple API, easy to get started
• Built-in code execution — Agents can write and run code automatically
• Human proxy pattern — Humans participate naturally in conversations
• Group chat support — Multi-agent discussions with automatic speaker selection
• Emergent behavior — Let agents figure out the best approach collaboratively
• Microsoft backing — Active development, good documentation, enterprise support
• Flexible termination — Custom termination messages and conditions

❌ Cons

• Implicit state — Conversation history is the state, less explicit than LangGraph
• Limited persistence — No built-in checkpointing for long-running workflows
• Less control over flow — Emergent behavior can be unpredictable
• No streaming optimization — Streaming support is basic compared to LangGraph
• Python-centric — Primary focus on Python (JS support is limited)
• Can be slow — Multi-turn conversations can be expensive with LLM calls

Comparison with Alternatives

Feature	AutoGen	LangGraph	CrewAI
Paradigm	Conversation-centric	Stateful graphs	Role-based teams
State	Implicit (messages)	Explicit TypedDict	Implicit (messages)
Control Flow	Implicit via conversation	Explicit edges	Sequential/hierarchical
Human-in-the-loop	Built-in (human proxy)	Advanced (interrupt)	Basic
Code execution	Built-in	Via tools	Via tools
Learning curve	Low	Medium-High	Low-Medium
Best for	Conversations, prototyping	Production workflows	Content pipelines

Real-World Examples

Example 1: Code Generation with Review

from autogen import AssistantAgent, UserProxyAgent

# Code writer agent
coder = AssistantAgent(
    name="coder",
    system_message="You are an expert Python programmer. Write clean, efficient code.",
    llm_config={"config_list": [{"model": "gpt-4", "api_key": "YOUR_KEY"}]},
)

# Code reviewer agent
reviewer = AssistantAgent(
    name="reviewer",
    system_message="You are a senior code reviewer. Check for bugs, security issues, and best practices.",
    llm_config={"config_list": [{"model": "gpt-4", "api_key": "YOUR_KEY"}]},
)

# User proxy for human input
user_proxy = UserProxyAgent(
    name="user",
    human_input_mode="TERMINATE",  # Ask until TERMINATE message
    code_execution_config={"work_dir": "coding", "use_docker": False},
)

# Start a conversation with the reviewer involved
user_proxy.initiate_chat(
    coder,
    message="Write a Python function to calculate the Fibonacci sequence",
    max_turns=5,
)

Example 2: Research Team with Group Chat

from autogen import AssistantAgent, GroupChat, GroupChatManager

# Specialized agents
researcher = AssistantAgent(
    name="researcher",
    system_message="You are a research specialist. Find and summarize relevant information.",
)

analyst = AssistantAgent(
    name="analyst",
    system_message="You are a data analyst. Analyze trends and draw insights.",
)

writer = AssistantAgent(
    name="writer",
    system_message="You are a technical writer. Transform research into clear articles.",
)

# Create group chat
groupchat = GroupChat(
    agents=[researcher, analyst, writer],
    messages=[],
    max_round=12,
    speaker_selection_method="auto",  # Auto-select next speaker
)

manager = GroupChatManager(
    groupchat=groupchat,
    llm_config={"config_list": [{"model": "gpt-4", "api_key": "YOUR_KEY"}]},
)

# Start the conversation
user_proxy.initiate_chat(
    manager,
    message="Research and write about the latest developments in AI agents",
)

Best Practices

1. Use clear system messages — Guide agent behavior effectively with detailed instructions.
2. Leverage code execution — Let agents write and test code for validation.
3. Use human-in-the-loop — For critical decisions, set human_input_mode="TERMINATE".
4. Start simple — Begin with two-agent conversations, then scale to groups.
5. Set max_turns — Prevent infinite conversation loops.
6. Use termination messages — Define clear "TERMINATE" conditions.
7. Custom speaker selection — For group chats, consider speaker_selection_method.

Troubleshooting

Issue	Solution
Infinite loops	Set max_turns and clear termination messages
Agent not responding	Check LLM config and API key validity
Code execution fails	Verify work_dir exists and has write permissions
Group chat not working	Ensure all agents have llm_config set
Poor output quality	Improve system messages with more context

Resources

• AutoGen Documentation
• GitHub Repository
• Examples Gallery
• AutoGen Blog
• Discord Community

---

Last updated: June 2026