Getting Started with AutoGen: First Multi-Agent System
AutoGen's conversation-based approach makes it straightforward to build multi-agent systems once you understand the core concepts. Agents are defined with system messages that describe their behavior, connected to model providers that power their reasoning, and organized into conversation patterns that determine how they interact. The following steps take you from zero to a working multi-agent system.
Install AutoGen and Dependencies
Start by creating a Python virtual environment and installing AutoGen. The framework requires Python 3.9 or later. Install the core package with pip install autogen-agentchat, which includes the agent abstractions, conversation management, and orchestration components. For code execution support, add the autogen-ext package with the docker extra: pip install autogen-ext
Verify the installation by importing the package in a Python script or interactive session. A successful import of autogen_agentchat confirms that the framework is installed correctly. If you encounter dependency conflicts, ensure you are using a clean virtual environment and that your Python version meets the minimum requirement.
Note that AutoGen is in maintenance mode, and Microsoft recommends the Microsoft Agent Framework for new projects. However, AutoGen remains fully functional and is the simpler starting point for learning multi-agent concepts. The patterns you learn here transfer directly to the Agent Framework.
Configure Your Model Provider
AutoGen needs a connection to an LLM provider to power agent reasoning. The most common configuration uses OpenAI's API. Create a model client configuration that specifies the model name, API key, and any provider-specific settings. Store your API key in an environment variable (OPENAI_API_KEY) rather than hardcoding it in your scripts to avoid accidentally exposing credentials in version control.
The model configuration is a dictionary that you pass to agents when creating them. At minimum, it includes the model identifier (like "gpt-4o" or "gpt-4o-mini") and the API key. For Azure OpenAI, you also specify the API endpoint and API version. AutoGen supports configuration lists that define multiple models with fallback behavior, so agents automatically try the next model if the primary one is unavailable.
For cost-conscious development, start with GPT-4o-mini, which provides capable reasoning at roughly one-twentieth the cost of GPT-4o. Switch to GPT-4o or GPT-4.1 for production use cases that require stronger reasoning, larger context windows, or better instruction following. The model change requires only updating the configuration, not the agent code.
Create Your First Agents
AutoGen provides several agent types, but the two most fundamental are AssistantAgent and UserProxyAgent. The AssistantAgent is an AI-powered agent that responds to messages using the configured LLM. The UserProxyAgent represents the human user and can execute code, call tools, or prompt the user for input depending on its configuration.
Create an AssistantAgent with a descriptive system message that defines its role and capabilities. The system message is the most important configuration because it determines how the agent behaves. A well-crafted system message specifies what the agent should do, what format to use for responses, what constraints to follow, and when to terminate the conversation. Be specific rather than vague: "You are a Python developer who writes clean, well-tested code" is better than "You are helpful."
Create a UserProxyAgent configured for the interaction style you want. Setting human_input_mode to "NEVER" makes the agent fully autonomous, while "ALWAYS" prompts for human input at every turn. For getting started, "TERMINATE" is a good middle ground that runs autonomously until the assistant indicates the task is complete.
Run a Two-Agent Conversation
With both agents created, initiate a conversation by calling the initiate_chat method on one agent with the other agent as the recipient. Pass a message string that describes the task you want the agents to accomplish. The conversation begins immediately, with the two agents exchanging messages until a termination condition is met.
Watch the conversation output to understand how agents collaborate. The user proxy sends the initial task, the assistant analyzes it and responds (often with code), the user proxy executes the code and returns the results, and the assistant reviews the results and iterates if needed. This back-and-forth continues until the assistant determines the task is complete and includes a termination keyword in its response.
Common issues at this stage include the conversation running indefinitely (fix by adding a clear termination instruction in the system message), the assistant not executing code (fix by ensuring the user proxy has code execution configured), or API errors from incorrect model configuration (fix by verifying your API key and model name). The conversation logs provide detailed information about each message exchange for debugging.
Add Tools and Code Execution
Tools extend what agents can do beyond text generation. Register a Python function as a tool by using the register_for_execution decorator on the user proxy and register_for_llm decorator on the assistant. The function's docstring and type hints become the tool description that the LLM uses to decide when and how to call the function.
For code execution, configure the user proxy with a code execution configuration that specifies the execution backend. The LocalCommandLineCodeExecutor runs code directly on your machine, which is simple but provides no isolation. The DockerCommandLineCodeExecutor runs code in Docker containers, providing security isolation at the cost of requiring Docker to be installed and running.
Test tool integration by giving the agents a task that requires the tool. For example, if you registered a weather lookup function, ask the agents to "check the weather in San Francisco and recommend what to wear." The assistant should recognize the need for the weather tool, generate a tool call, and the user proxy should execute the function and return the results.
Build a Group Chat
Group chats bring multiple specialized agents together to collaborate on complex tasks. Create three or more agents with distinct roles, such as a researcher, a coder, and a reviewer. Each agent gets a system message that defines its specialization and explains when it should contribute to the conversation.
Combine the agents into a GroupChat object that manages the conversation flow. The GroupChat requires a list of agents, a maximum number of turns, and a speaker selection method. The "auto" selection method uses an LLM to choose the next speaker based on the conversation context, while "round_robin" cycles through agents in order. Create a GroupChatManager that wraps the group chat and handles the orchestration.
Initiate the group chat by sending a task to the manager. Watch how different agents contribute based on their specializations. The manager selects the most appropriate agent for each turn, agents build on each other's work, and the conversation progresses toward task completion. Adjust system messages and speaker selection if agents are not contributing as expected. Start with three agents and add more only when the conversation flow is working well with a smaller group.
Getting started with AutoGen requires installing the package, configuring a model provider, creating agents with clear system messages, and connecting them in conversation patterns. Start with a simple two-agent conversation, add tools and code execution as needed, and build up to group chats for complex multi-agent collaboration. The patterns you learn apply directly to the Microsoft Agent Framework when you are ready to move to production.