AutoGen v0.4 represents a significant rearchitecture of Microsoft’s multi-agent framework, shifting from the monolithic agent classes of earlier versions to a more modular, event-driven design built around the Actor model. If you have used AutoGen v0.2 or v0.3, v0.4 will feel substantially different — the concepts carry over but the API and the mental model for building agents have changed. This guide covers what is new in v0.4, how to set up a working multi-agent system, and the patterns that work well in the new architecture.
What Changed in AutoGen v0.4
The core change in v0.4 is the move to an Actor model for agent communication. In earlier versions, agents communicated by directly calling each other’s methods — a tight coupling that made complex agent topologies difficult to build and debug. In v0.4, agents are actors that communicate by sending and receiving messages asynchronously through a runtime. Each agent has a mailbox; messages arrive in the mailbox; the agent processes them and optionally sends responses. This decoupling makes it possible to build genuinely complex multi-agent systems — where agents run concurrently, messages route through broker agents, and the overall topology is flexible — without the tangled call graphs of earlier versions.
The other significant change is the separation of concerns in the new package structure. AutoGen v0.4 is split into autogen-core (the runtime and messaging infrastructure), autogen-agentchat (higher-level abstractions for conversational agents, the closest equivalent to the old API), and autogen-ext (integrations with external tools and services). Most developers starting with v0.4 will use autogen-agentchat, which provides the familiar AssistantAgent and UserProxyAgent classes but rebuilt on the new runtime.
Installation and Setup
Install the packages you need for your use case. For most multi-agent conversational workflows, autogen-agentchat and an LLM client package are sufficient. AutoGen v0.4 supports OpenAI, Azure OpenAI, Anthropic, Google Gemini, and local models through its model client abstraction. The model client is configured separately from the agents, which makes it straightforward to switch LLM providers without changing agent code.
Configuration follows a cleaner pattern than earlier versions — model clients are instantiated as Python objects rather than passed as configuration dictionaries, and the type system is stricter, which catches configuration errors at import time rather than at runtime when the first message is sent.
Figure 1 — AutoGen v0.4 architecture: key concepts
Building a Two-Agent System with AgentChat
The AgentChat layer provides the most accessible entry point into v0.4. The two core agent types — AssistantAgent and UserProxyAgent — work similarly to their predecessors but with cleaner APIs. An AssistantAgent wraps an LLM model client and optional tools; a UserProxyAgent represents human input or automated task execution. Together they form the basic two-agent conversational pattern that covers most use cases.
The key difference from earlier versions is how conversations are run. In v0.4, conversations run inside a Team — a coordination object that manages message routing, tracks termination conditions, and handles the asynchronous message passing between agents. You define the team’s agents and termination condition (a maximum number of turns, a specific termination phrase, or a custom condition), then run the team with an initial task message.
Termination Conditions
Termination conditions are first-class objects in v0.4, which makes them composable and testable in a way they were not in earlier versions. The built-in conditions cover the most common cases:
- MaxMessageTermination — stop after N messages, the simplest safety boundary
- TextMentionTermination — stop when a specific string appears in a message, useful for agents that signal completion with “TASK_COMPLETE” or similar
- TokenUsageTermination — stop when token usage exceeds a budget, useful for cost control in production
Conditions can be combined with AND/OR operators: stop when either the text termination condition triggers OR the max messages limit is reached. This composability makes it straightforward to build multi-condition stopping logic that would have required custom code in earlier versions.
Tool Use in v0.4
Tools in AutoGen v0.4 are regular Python functions decorated with type annotations. The framework generates the JSON schema for the LLM automatically from the function signature and docstring — you do not write the schema manually. This is a significant improvement over earlier versions where tool schema definitions were verbose and error-prone. The docstring becomes the tool description that the LLM sees; the parameter annotations become the schema. Write clear, specific docstrings and the LLM will use the tools correctly.
Tool registration happens at agent instantiation — pass a list of functions to the AssistantAgent’s tools parameter. The agent’s model client automatically uses these tools in its API calls. Tool execution happens in the agent’s process method, which handles the full call-execute-respond cycle without requiring you to implement the execution loop yourself — this is one of the ways AgentChat provides value over the raw autogen-core API.
Multi-Agent Topologies: RoundRobin and Selector
Beyond the basic two-agent pattern, v0.4 provides built-in team topologies for common multi-agent arrangements. RoundRobinGroupChat routes messages to each agent in turn — useful for critique-and-revise workflows where you want each agent to process every message. SelectorGroupChat uses an LLM to decide which agent should respond to each message, enabling dynamic routing based on message content — a researcher agent gets research questions, a coder agent gets implementation requests, a critic agent gets work to review.
These topologies replace the manual orchestration that was required in earlier AutoGen versions. Rather than writing custom code to decide which agent should speak next, you describe the routing logic in natural language and SelectorGroupChat’s selector LLM handles the decision. For complex multi-agent systems with specialised agents, this reduces the amount of custom orchestration code significantly while producing more flexible routing behaviour.
Persistence and State
v0.4 introduces proper state management for agents and teams. Teams can be serialised to JSON, saved, and resumed — a missing capability in earlier versions that made long-running agentic workflows fragile. If a long task is interrupted, the team state can be restored and the task continued from where it stopped rather than restarted from scratch. For production agentic systems where tasks may take minutes or hours, this persistence is a practical necessity rather than a nice-to-have.
Migrating from v0.2 / v0.3
The migration from earlier AutoGen versions is not trivial — v0.4 is not backward compatible. The main changes to address: agent classes have moved (import from autogen_agentchat rather than autogen), conversations now run inside a Team rather than being initiated directly between agents, and tool definitions use Python type annotations rather than JSON schema dictionaries. The AutoGen documentation provides a migration guide, and the most efficient approach for existing projects is to rewrite agent definitions and conversation flows from scratch using the new API rather than trying to adapt the old code incrementally — the conceptual shift is significant enough that a clean rewrite is usually faster than a patched migration.
AutoGen v0.4 is a meaningfully better foundation for multi-agent systems than its predecessors — the Actor model makes complex topologies tractable, the composable termination conditions reduce boilerplate, the clean tool definition API removes a persistent friction point, and the state persistence makes production deployments viable. The migration cost is real but worth it for projects that will continue to develop, and the new architecture’s benefits compound as agent systems grow in complexity.
Observability and Debugging in v0.4
AutoGen v0.4 includes built-in observability through message logging at the team level. The Team class accepts a log handler that receives every message exchanged between agents, making it straightforward to record the full conversation trace for debugging. For production deployments, connecting this log handler to a structured logging system or an observability platform gives you a complete audit trail of every agent decision and tool call. The message log is also the primary debugging tool when an agent behaves unexpectedly — reading the exact sequence of messages and tool results usually makes the problem clear. v0.4’s clean message model (every interaction is a message with a well-defined type and structure) makes this log much more readable than the mixture of print statements and exception traces that characterised debugging in earlier versions.
When to Use AutoGen vs a Hand-Built Agent
AutoGen v0.4 is the right choice when your use case involves multiple specialised agents that need to collaborate, when you want the built-in multi-agent topologies (RoundRobin, Selector) rather than writing custom routing logic, or when you need the team state persistence for long-running tasks. A hand-built agent loop is the right choice when you need complete control over every aspect of the agent’s behaviour, when the framework’s abstractions add more complexity than they remove for your specific use case, or when you are building an agent that will be embedded in a larger system where a framework dependency is undesirable. Both approaches are valid; the right choice depends on the complexity of the agent topology, the importance of customisability, and whether the framework’s built-in capabilities match your requirements closely enough to justify the learning curve and dependency.