AutoGen Conversation Template

Overview

Template for building multi-agent conversation flows with Microsoft's AutoGen framework. AutoGen provides a conversation-centric programming model for building multi-agent systems where agents can autonomously converse, collaborate, and solve tasks together.

What is AutoGen?

AutoGen is a framework for building multi-agent conversation systems with LLMs. Key features include:

• Conversation-centric: Focus on agent conversations rather than rigid workflows
• Flexible agent roles: Define agents with specific roles, capabilities, and personalities
• Human-in-the-loop: Seamless integration of human feedback in conversations
• Code execution: Built-in code interpreter for executing generated code
• Group chat: Multi-agent group conversations with manager orchestration
• Extensible: Custom agents, tools, and conversation patterns

Template Structure

autogen-template/
├── src/
│   ├── __init__.py
│   ├── agents.py           # Agent definitions and configurations
│   ├── conversation.py     # Conversation patterns and flows
│   ├── groupchat.py        # Group chat management
│   ├── tools.py            # Custom tools and functions
│   ├── memory.py           # Conversation memory management
│   └── utils.py            # Utility functions
├── examples/
│   ├── two_agent.py        # Two-agent conversation example
│   ├── group_chat.py       # Group chat example
│   ├── human_in_loop.py    # Human-in-the-loop example
│   └── code_execution.py   # Code execution example
├── config/
│   └── llm_config.yaml     # LLM configuration
├── tests/
│   ├── test_agents.py
│   └── test_conversation.py
├── main.py                 # Entry point
├── requirements.txt
└── README.md

Installation

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install AutoGen
pip install pyautogen

# Install optional dependencies
pip install pyautogen[teachable]  # For teachable agents
pip install pyautogen[long-context]  # For long context handling

# Or install all extras
pip install pyautogen[all]

Core Concepts

Agent Basics

# agents.py
from autogen import ConversableAgent, AssistantAgent, UserProxyAgent
from autogen.agentchat.contrib.capabilities import TransformMessages

# Configuration
llm_config = {
    "config_list": [
        {
            "model": "gpt-4o",
            "api_key": "YOUR_OPENAI_API_KEY",
        }
    ],
    "temperature": 0.7,
    "cache_seed": 42,  # For reproducibility
}

# Create assistant agent
assistant = ConversableAgent(
    name="Assistant",
    system_message="You are a helpful AI assistant. Help the user with their tasks.",
    llm_config=llm_config,
    human_input_mode="NEVER",  # Never ask for human input
    max_consecutive_auto_reply=10,  # Max auto-replies before stopping
)

# Create user proxy agent (for human interaction)
user_proxy = UserProxyAgent(
    name="User",
    human_input_mode="ALWAYS",  # Always ask for human input
    is_termination_msg=lambda msg: msg.get("content") is not None and "TERMINATE" in msg.get("content"),
    code_execution_config={
        "work_dir": "coding",
        "use_docker": False,
    },
)

Specialized Agent Types

# AssistantAgent - For LLM-powered assistance
assistant = AssistantAgent(
    name="Research_Assistant",
    system_message="""You are a research assistant specialized in finding and analyzing information.
    
    Your responsibilities:
    1. Search for relevant information on given topics
    2. Analyze and synthesize findings
    3. Provide well-cited, accurate responses
    4. Ask clarifying questions when needed
    
    Always cite your sources and be transparent about uncertainty.""",
    llm_config=llm_config,
)

# UserProxyAgent - For human interaction
user_proxy = UserProxyAgent(
    name="Human_User",
    system_message="A human user who provides feedback and makes decisions.",
    human_input_mode="TERMINATE",  # Ask for input until TERMINATE is said
    max_consecutive_auto_reply=0,  # No auto-replies
    code_execution_config={
        "work_dir": "coding",
        "use_docker": False,
        "last_n_messages": 3,
    },
)

# Agent with specific capabilities
coding_agent = AssistantAgent(
    name="Coding_Assistant",
    system_message="""You are an expert software engineer.
    
    Your responsibilities:
    1. Write clean, efficient, well-documented code
    2. Follow best practices and design patterns
    3. Write tests for all code
    4. Explain your code clearly
    
    Preferred languages: Python, JavaScript, TypeScript""",
    llm_config=llm_config,
    code_execution_config={
        "work_dir": "coding",
        "use_docker": False,
    },
)

Conversation Patterns

Two-Agent Conversation

# conversation.py
from autogen import ConversableAgent, UserProxyAgent, register_function
from autogen.oai import OpenAIWrapper

def initiate_conversation():
    """Start a two-agent conversation."""
    
    # Configure agents
    llm_config = {
        "config_list": [{"model": "gpt-4o", "api_key": "YOUR_API_KEY"}],
    }
    
    assistant = ConversableAgent(
        name="Assistant",
        system_message="You are a helpful assistant.",
        llm_config=llm_config,
        human_input_mode="NEVER",
    )
    
    user = UserProxyAgent(
        name="User",
        human_input_mode="ALWAYS",
        is_termination_msg=lambda msg: msg.get("content") is not None and "TERMINATE" in msg.get("content"),
    )
    
    # Start conversation
    user.initiate_chat(
        assistant,
        message="Help me write a Python function to calculate the factorial of a number.",
        max_turns=5,
    )

def register_tools():
    """Register custom tools with agents."""
    
    def search_web(query: str) -> str:
        """Search the web for information."""
        # Implement search logic
        return "Search results..."
    
    def calculate(x: float, y: float, operation: str) -> float:
        """Perform a mathematical calculation."""
        operations = {
            "add": lambda a, b: a + b,
            "subtract": lambda a, b: a - b,
            "multiply": lambda a, b: a * b,
            "divide": lambda a, b: a / b if b != 0 else float('inf'),
        }
        return operations[operation](x, y)
    
    # Register with assistant
    register_function(
        search_web,
        caller=assistant,
        executor=user,
        name="search_web",
        description="Search the web for information.",
    )
    
    register_function(
        calculate,
        caller=assistant,
        executor=user,
        name="calculate",
        description="Perform a mathematical calculation.",
    )

Group Chat

# groupchat.py
from autogen import GroupChat, GroupChatManager, ConversableAgent

def create_group_chat():
    """Create a multi-agent group chat."""
    
    # Define agents
    llm_config = {"config_list": [{"model": "gpt-4o", "api_key": "YOUR_API_KEY"}]}
    
    researcher = ConversableAgent(
        name="Researcher",
        system_message="You are a researcher who gathers and analyzes information.",
        llm_config=llm_config,
        human_input_mode="NEVER",
    )
    
    writer = ConversableAgent(
        name="Writer",
        system_message="You are a writer who creates engaging content.",
        llm_config=llm_config,
        human_input_mode="NEVER",
    )
    
    editor = ConversableAgent(
        name="Editor",
        system_message="You are an editor who reviews and improves content.",
        llm_config=llm_config,
        human_input_mode="NEVER",
    )
    
    manager = ConversableAgent(
        name="Manager",
        system_message="You are a project manager who coordinates the team.",
        llm_config=llm_config,
        human_input_mode="NEVER",
    )
    
    # Create group chat
    groupchat = GroupChat(
        agents=[researcher, writer, editor, manager],
        messages=[],
        max_round=12,
        speaker_selection_method="round_robin",  # Options: auto, round_robin, manual, random
    )
    
    # Create group chat manager
    group_chat_manager = GroupChatManager(
        groupchat=groupchat,
        llm_config=llm_config,
    )
    
    # Initiate conversation
    researcher.initiate_chat(
        group_chat_manager,
        message="Let's create a blog post about AI agents. Researcher, start by gathering information.",
    )

def create_ad_hoc_group_chat():
    """Create a dynamic group chat with speaker selection."""
    
    # Define agents
    llm_config = {"config_list": [{"model": "gpt-4o", "api_key": "YOUR_API_KEY"}]}
    
    agents = [
        ConversableAgent(name="Researcher", system_message="Gather information.", llm_config=llm_config, human_input_mode="NEVER"),
        ConversableAgent(name="Writer", system_message="Write content.", llm_config=llm_config, human_input_mode="NEVER"),
        ConversableAgent(name="Editor", system_message="Edit content.", llm_config=llm_config, human_input_mode="NEVER"),
    ]
    
    # Create group chat with auto speaker selection
    groupchat = GroupChat(
        agents=agents,
        messages=[],
        max_round=10,
        speaker_selection_method="auto",  # LLM decides who speaks next
    )
    
    manager = GroupChatManager(groupchat=groupchat, llm_config=llm_config)
    
    # Start conversation
    agents[0].initiate_chat(
        manager,
        message="Create a technical blog post about machine learning.",
    )

Human-in-the-Loop

# human_in_loop.py
from autogen import ConversableAgent, UserProxyAgent

def human_in_the_loop():
    """Demonstrate human-in-the-loop conversation."""
    
    llm_config = {"config_list": [{"model": "gpt-4o", "api_key": "YOUR_API_KEY"}]}
    
    # Agent that can think and act
    assistant = ConversableAgent(
        name="Assistant",
        system_message="You are a helpful assistant that can perform tasks.",
        llm_config=llm_config,
        human_input_mode="NEVER",
        max_consecutive_auto_reply=3,
    )
    
    # User proxy that asks for human input
    user_proxy = UserProxyAgent(
        name="User",
        human_input_mode="TERMINATE",  # Ask for input until TERMINATE
        is_termination_msg=lambda msg: msg.get("content") is not None and "TERMINATE" in msg.get("content"),
        code_execution_config={"work_dir": "coding", "use_docker": False},
    )
    
    # Start conversation
    user_proxy.initiate_chat(
        assistant,
        message="Write a Python script to analyze sales data and create a chart.",
        max_turns=10,
    )

def conditional_human_input():
    """Conditionally ask for human input."""
    
    def should_ask_human(msg):
        """Decide whether to ask for human input."""
        # Only ask for human input on certain conditions
        content = msg.get("content", "")
        return "approval" in content.lower() or "confirm" in content.lower()
    
    user_proxy = UserProxyAgent(
        name="User",
        human_input_mode="TERMINATE",
        is_termination_msg=should_ask_human,
    )

Code Execution

# code_execution.py
from autogen import ConversableAgent, UserProxyAgent

def execute_code():
    """Demonstrate code execution capabilities."""
    
    llm_config = {"config_list": [{"model": "gpt-4o", "api_key": "YOUR_API_KEY"}]}
    
    # Coding assistant
    coder = ConversableAgent(
        name="Coder",
        system_message="""You are an expert Python programmer.
        
        When asked to write code:
        1. Write clean, well-documented code
        2. Include error handling
        3. Write tests
        4. Explain your approach
        
        Always use the code_execution tool to run your code.""",
        llm_config=llm_config,
        human_input_mode="NEVER",
    )
    
    # User proxy with code execution
    user = UserProxyAgent(
        name="User",
        human_input_mode="NEVER",
        is_termination_msg=lambda msg: msg.get("content") is not None and "TERMINATE" in msg.get("content"),
        code_execution_config={
            "work_dir": "coding",
            "use_docker": False,
            "last_n_messages": 3,
        },
    )
    
    # Start conversation
    user.initiate_chat(
        coder,
        message="Write a Python function to calculate the Fibonacci sequence and test it.",
        max_turns=5,
    )

def docker_code_execution():
    """Execute code in Docker container for safety."""
    
    user = UserProxyAgent(
        name="User",
        human_input_mode="NEVER",
        code_execution_config={
            "work_dir": "coding",
            "use_docker": True,  # Use Docker for isolation
            "docker_image": "python:3.11-slim",
        },
    )

Advanced Features

Teachable Agents

# agents with teaching capabilities
from autogen.agentchat.contrib.capabilities import Teachability

llm_config = {"config_list": [{"model": "gpt-4o", "api_key": "YOUR_API_KEY"}]}

assistant = ConversableAgent(
    name="Teachable_Assistant",
    system_message="You are a teachable assistant that learns from user feedback.",
    llm_config=llm_config,
    human_input_mode="NEVER",
)

# Add teachability capability
teachability = Teachability(
    verbosity=0,
    reset_db=False,
    path_to_db_dir="./tmp/teachability_db",
    recall_threshold=1.5,
)

teachability.add_to_agent(assistant)

# Now the assistant can learn from conversations

Long Context Handling

# Handle conversations that exceed context limits
from autogen.agentchat.contrib.capabilities import TransformMessages, TextCompression

llm_config = {"config_list": [{"model": "gpt-4", "api_key": "YOUR_API_KEY"}]}

assistant = ConversableAgent(
    name="Long_Context_Assistant",
    system_message="You are a helpful assistant.",
    llm_config=llm_config,
    human_input_mode="NEVER",
)

# Add text compression capability
compressor = TextCompression(
    text_compressor=TextCompression(),
)

compressor.add_to_agent(assistant)

Custom Tools

# tools.py
from autogen import ConversableAgent, register_function
from typing import Annotated

def register_custom_tools(agent: ConversableAgent):
    """Register custom tools with an agent."""
    
    def search_duckduckgo(query: str) -> str:
        """Search DuckDuckGo for information."""
        from duckduckgo_search import DDGS
        with DDGS() as ddgs:
            results = list(ddgs.text(query, max_results=5))
        return str(results)
    
    def get_weather(location: str) -> str:
        """Get current weather for a location."""
        import requests
        response = requests.get(f"https://api.open-meteo.com/v1/forecast?latitude={location}&current_weather=true")
        return str(response.json())
    
    def calculate_bmi(weight: float, height: float) -> float:
        """Calculate Body Mass Index."""
        return weight / (height ** 2)
    
    # Register tools
    register_function(
        search_duckduckgo,
        caller=agent,
        executor=agent,
        name="search",
        description="Search the web for information.",
    )
    
    register_function(
        get_weather,
        caller=agent,
        executor=agent,
        name="get_weather",
        description="Get current weather for a location.",
    )
    
    register_function(
        calculate_bmi,
        caller=agent,
        executor=agent,
        name="calculate_bmi",
        description="Calculate Body Mass Index from weight (kg) and height (m).",
    )

Memory Management

# memory.py
from autogen import ConversableAgent
from autogen.agentchat.contrib.capabilities import TransformMessages

def add_message_memory(agent: ConversableAgent):
    """Add message memory to an agent."""
    
    transform_messages = TransformMessages()
    transform_messages.add_to_agent(agent)

def conversation_summary():
    """Summarize long conversations."""
    
    from autogen.agentchat.contrib.capabilities import TransformMessages, MessageHistory
    
    # Add message history capability
    history = MessageHistory(
        max_messages=100,  # Keep last 100 messages
    )
    
    history.add_to_agent(agent)

Configuration

LLM Configuration File

# config/llm_config.yaml
config_list:
  - model: gpt-4o
    api_key: ${OPENAI_API_KEY}
    base_url: https://api.openai.com/v1
  
  - model: gpt-4o-mini
    api_key: ${OPENAI_API_KEY}
    base_url: https://api.openai.com/v1
  
  - model: claude-3-5-sonnet-20241022
    api_key: ${ANTHROPIC_API_KEY}
    base_url: https://api.anthropic.com/v1

default_config:
  temperature: 0.7
  cache_seed: 42
  timeout: 300
  max_tokens: 4096

model_priorities:
  - gpt-4o
  - claude-3-5-sonnet-20241022
  - gpt-4o-mini

Agent Configuration

# config/agents.yaml
agents:
  researcher:
    name: Researcher
    system_message: |
      You are a research assistant specialized in finding and analyzing information.
      Your responsibilities:
      1. Search for relevant information on given topics
      2. Analyze and synthesize findings
      3. Provide well-cited, accurate responses
      4. Ask clarifying questions when needed
    human_input_mode: NEVER
    max_consecutive_auto_reply: 10
  
  writer:
    name: Writer
    system_message: |
      You are a technical content writer.
      Your responsibilities:
      1. Write clear, engaging content
      2. Structure content logically
      3. Use appropriate tone for the audience
      4. Include examples and explanations
    human_input_mode: NEVER
    max_consecutive_auto_reply: 10
  
  editor:
    name: Editor
    system_message: |
      You are a meticulous content editor.
      Your responsibilities:
      1. Check for factual accuracy
      2. Improve clarity and flow
      3. Ensure consistent tone
      4. Verify citations and references
    human_input_mode: NEVER
    max_consecutive_auto_reply: 10
  
  user_proxy:
    name: User
    human_input_mode: TERMINATE
    is_termination_msg: "TERMINATE"
    code_execution_config:
      work_dir: coding
      use_docker: false

Examples

Example 1: Two-Agent Problem Solving

# examples/two_agent.py
from autogen import ConversableAgent, UserProxyAgent

def solve_problem():
    llm_config = {"config_list": [{"model": "gpt-4o", "api_key": "YOUR_API_KEY"}]}
    
    assistant = ConversableAgent(
        name="Math_Assistant",
        system_message="You are a math tutor who explains concepts clearly.",
        llm_config=llm_config,
        human_input_mode="NEVER",
    )
    
    user = UserProxyAgent(
        name="Student",
        human_input_mode="ALWAYS",
        is_termination_msg=lambda msg: msg.get("content") is not None and "TERMINATE" in msg.get("content"),
    )
    
    user.initiate_chat(
        assistant,
        message="Explain the concept of derivatives in calculus with examples.",
        max_turns=5,
    )

if __name__ == "__main__":
    solve_problem()

Example 2: Multi-Agent Content Creation

# examples/content_creation.py
from autogen import GroupChat, GroupChatManager, ConversableAgent

def create_content():
    llm_config = {"config_list": [{"model": "gpt-4o", "api_key": "YOUR_API_KEY"}]}
    
    researcher = ConversableAgent(
        name="Researcher",
        system_message="You gather information and facts.",
        llm_config=llm_config,
        human_input_mode="NEVER",
    )
    
    writer = ConversableAgent(
        name="Writer",
        system_message="You write engaging content.",
        llm_config=llm_config,
        human_input_mode="NEVER",
    )
    
    editor = ConversableAgent(
        name="Editor",
        system_message="You review and improve content.",
        llm_config=llm_config,
        human_input_mode="NEVER",
    )
    
    groupchat = GroupChat(
        agents=[researcher, writer, editor],
        messages=[],
        max_round=15,
        speaker_selection_method="auto",
    )
    
    manager = GroupChatManager(groupchat=groupchat, llm_config=llm_config)
    
    researcher.initiate_chat(
        manager,
        message="Create a blog post about the benefits of exercise.",
    )

if __name__ == "__main__":
    create_content()

Example 3: Code Generation and Execution

# examples/code_execution.py
from autogen import ConversableAgent, UserProxyAgent

def generate_and_run_code():
    llm_config = {"config_list": [{"model": "gpt-4o", "api_key": "YOUR_API_KEY"}]}
    
    coder = ConversableAgent(
        name="Python_Coder",
        system_message="You are a Python expert. Write clean, tested code.",
        llm_config=llm_config,
        human_input_mode="NEVER",
    )
    
    user = UserProxyAgent(
        name="User",
        human_input_mode="NEVER",
        is_termination_msg=lambda msg: msg.get("content") is not None and "TERMINATE" in msg.get("content"),
        code_execution_config={
            "work_dir": "coding",
            "use_docker": False,
        },
    )
    
    user.initiate_chat(
        coder,
        message="Write a Python script to fetch data from an API and save it to a CSV file.",
        max_turns=5,
    )

if __name__ == "__main__":
    generate_and_run_code()

Testing

Unit Tests

# tests/test_agents.py
import pytest
from autogen import ConversableAgent

def test_agent_creation():
    llm_config = {"config_list": [{"model": "gpt-4o", "api_key": "test_key"}]}
    
    agent = ConversableAgent(
        name="Test_Agent",
        system_message="Test agent",
        llm_config=llm_config,
        human_input_mode="NEVER",
    )
    
    assert agent.name == "Test_Agent"
    assert agent.system_message == "Test agent"

def test_agent_reply():
    llm_config = {"config_list": [{"model": "gpt-4o", "api_key": "test_key"}]}
    
    agent = ConversableAgent(
        name="Test_Agent",
        system_message="You are a test agent that always replies 'Hello!'",
        llm_config=llm_config,
        human_input_mode="NEVER",
    )
    
    reply = agent.generate_reply(messages=[{"content": "Hi", "role": "user"}])
    assert reply is not None

Integration Tests

# tests/test_conversation.py
import pytest
from autogen import ConversableAgent, UserProxyAgent

@pytest.mark.asyncio
async def test_two_agent_conversation():
    llm_config = {"config_list": [{"model": "gpt-4o", "api_key": "test_key"}]}
    
    assistant = ConversableAgent(
        name="Assistant",
        system_message="You are helpful.",
        llm_config=llm_config,
        human_input_mode="NEVER",
    )
    
    user = UserProxyAgent(
        name="User",
        human_input_mode="NEVER",
        is_termination_msg=lambda msg: "TERMINATE" in msg.get("content", ""),
    )
    
    # Test conversation
    await user.a_initiate_chat(
        assistant,
        message="Say hello",
        max_turns=2,
    )
    
    # Verify conversation happened
    assert len(user.chat_messages) > 0

Best Practices

Agent Design

1. Clear system messages: Be specific about roles and responsibilities
2. Appropriate human_input_mode: Use NEVER for automation, ALWAYS for interaction
3. Set max_consecutive_auto_reply: Prevent infinite loops
4. Define termination conditions: Use is_termination_msg clearly

Conversation Design

1. Start with clear context: Provide background in the initial message
2. Use max_turns: Limit conversation length to control costs
3. Implement proper termination: Use TERMINATE keyword or custom conditions
4. Handle errors gracefully: Catch exceptions and provide fallbacks

Code Execution Safety

1. Use Docker: Isolate code execution in containers
2. Limit work_dir: Restrict to specific directories
3. Validate code: Review generated code before execution
4. Set timeouts: Prevent infinite loops in code

Troubleshooting

Common Issues

Agents not responding:

• Check LLM API key is valid
• Verify model name is correct
• Ensure human_input_mode is appropriate

Infinite conversation loops:

• Set max_consecutive_auto_reply
• Define clear termination conditions
• Use max_turns parameter

Code execution failures:

• Check work_dir exists and is writable
• Verify Docker is running (if using Docker)
• Review code for syntax errors

High API costs:

• Use smaller models (gpt-4o-mini)
• Set appropriate max_turns
• Enable caching with cache_seed

Debugging

# Enable verbose logging
import logging
logging.basicConfig(level=logging.DEBUG)

# Check agent state
print(agent.chat_messages)
print(agent._oai_messages)

# Trace conversation
for msg in user.chat_messages[assistant]:
    print(f"{msg['role']}: {msg['content']}")

Resources

• AutoGen Documentation: https://microsoft.github.io/autogen/
• AutoGen Examples: https://microsoft.github.io/autogen/docs/Examples
• AutoGen GitHub: https://github.com/microsoft/autogen
• AutoGen Discord: https://discord.gg/pAbnFJrkgZ

---

Last updated: May 2026