AutoGen Tutorial: AgentChat, Teams, Termination, and the v0.2 Migration Boundary

Direct answer: a new AutoGen project in 2026 should not start from the v0.2 mental model of ConversableAgent + GroupChatManager + human_input_mode + max_round. Current AutoGen is organized around the high-level AgentChat API, the event-driven Core runtime, and Extensions. Multi-agent collaboration uses AssistantAgent plus Teams, while stopping behavior is expressed with TerminationCondition.

Legacy APIs still matter for migration because many old codebases use them. They should not be mixed into current examples as though the imports, state model and human-input behavior were unchanged.

First question: do you actually need multiple agents?

Current AutoGen guidance recommends starting with a single agent and its tools for simpler tasks. Teams require extra scaffolding:

• multiple system prompts and shared context;
• speaker selection;
• termination conditions;
• team state persistence and recovery;
• per-agent tool permissions;
• cross-agent error propagation;
• additional model calls and token cost.

A Planner/Coder/Reviewer/Summarizer architecture is not automatically better than one well-scoped AssistantAgent with two tools.

The current layers: AgentChat, Core, and Extensions

AgentChat

This is the starting point for most application developers. It provides agents, teams, messages, termination and state abstractions.

Common building blocks include:

• AssistantAgent
• UserProxyAgent
• RoundRobinGroupChat
• SelectorGroupChat
• Swarm
• GraphFlow

Core

Core is the lower-level asynchronous, event-driven runtime. Use it when you need custom actors, message routing, distributed behavior or your own higher-level framework rather than ordinary AgentChat applications.

Extensions

Provider model clients, code executors and other integrations live in Extensions, keeping the high-level agent layer separate from specific model and execution backends.

Minimal current team: two AssistantAgents with RoundRobinGroupChat

from autogen_agentchat.agents import AssistantAgent
from autogen_agentchat.conditions import MaxMessageTermination, TextMentionTermination
from autogen_agentchat.teams import RoundRobinGroupChat

researcher = AssistantAgent(
    "researcher",
    model_client=model_client,
    system_message="Collect evidence and state source boundaries. Do not invent facts.",
)

reviewer = AssistantAgent(
    "reviewer",
    model_client=model_client,
    system_message="Review evidence. Reply APPROVE only when requirements are satisfied.",
)

termination = (
    TextMentionTermination("APPROVE")
    | MaxMessageTermination(max_messages=12)
)

team = RoundRobinGroupChat(
    [researcher, reviewer],
    termination_condition=termination,
)

result = await team.run(task="Review this migration plan.")

The production question is not whether two agents can chat. It is who can speak, what each agent can do, when the run must stop, and what state survives after it stops.

Termination: do not teach max_round as the current API

Older v0.2 examples frequently use max_round and is_termination_msg. Current AgentChat uses composable termination conditions.

Typical controls include:

• MaxMessageTermination for a hard message budget;
• TextMentionTermination for an explicit completion signal;
• TimeoutTermination for a time budget;
• handoff, external-event, or custom termination logic where appropriate.

A production team should normally combine a business completion condition with a hard budget limit. Depending only on a model to emit a magic TERMINATE string is brittle.

RoundRobin, Selector, Swarm, or GraphFlow?

RoundRobinGroupChat

Members take turns in a predictable sequence. It is easier to regression-test, but every member gets a turn even if the role is not needed at that moment.

SelectorGroupChat

The team chooses the next speaker based on context. It is more flexible for larger role sets but requires better agent descriptions, selector constraints, termination and observability for incorrect speaker choices.

Swarm

Use Swarm when responsibility moves through explicit agent handoffs.

GraphFlow

When the workflow already has clear dependencies, branches or ordering constraints, GraphFlow can be a better fit than asking a model to freely select the next speaker. Transactional or approval-heavy flows generally benefit from explicit topology.

Current UserProxyAgent: do not copy human_input_mode from v0.2

A typical v0.2 UserProxyAgent example used:

human_input_mode="ALWAYS" | "TERMINATE" | "NEVER"
max_consecutive_auto_reply=...

Current AgentChat UserProxyAgent is an agent for collecting human input and can use a custom input_func.

The important production issue is waiting time. If a person may answer minutes or hours later, do not keep one web request or worker blocked. Prefer:

1. stop the team at a handoff/termination boundary;
2. persist team state and an application approval ID;
3. release the worker;
4. collect the human decision;
5. load state and resume in a later request.

Team state is not a business transaction ledger

AgentChat can save and load agent/team state, but that does not make external side effects exactly-once.

Keep at least three layers separate:

• AutoGen state — internal agent/team execution context;
• business workflow state — pending, approved, rejected, expired, completed;
• side-effect ledger — whether email, payment, publishing or database writes already happened.

Before resuming, re-check tool version, current authorization, approval expiry and idempotency results.

Apply least privilege per agent

Do not give the entire team one unrestricted tool registry.

A safer split is:

• Researcher: read-only retrieval;
• Planner: business context reads, no production writes;
• Executor: only the controlled write tools needed by the current task;
• Reviewer: evidence and test results, read-only;
• publish/delete/payment: separate approval gate.

Least privilege limits damage even if speaker selection or model reasoning goes wrong.

v0.2 migration: APIs that should not be mixed into a current tutorial

v0.2 pattern	Current treatment
ConversableAgent	Legacy migration context; use current AgentChat agents for new projects
GroupChatManager	Legacy migration context; use Teams
human_input_mode	v0.2 UserProxy configuration; current UserProxyAgent uses the new input model
max_round	Old GroupChat turn cap; use termination conditions
is_termination_msg	Old termination hook; use composable termination conditions
pyautogen	Do not assume it is the current Microsoft package source; follow the official migration guidance

The official migration guide describes v0.2 to v0.4 as a breaking rewrite and warns that releases of the pyautogen package after 0.2.34 are no longer from Microsoft. Historical v0.2 systems should pin the correct package path rather than mixing generations.

AutoGen and Microsoft Agent Framework

Microsoft now publishes an official migration guide from AutoGen to Microsoft Agent Framework and positions Agent Framework as the newer multi-language agent/workflow SDK direction.

That does not mean every working AutoGen application should be rewritten immediately. A more useful migration process is:

1. isolate model clients, tools, state, approval and orchestration boundaries;
2. confirm which current AutoGen behaviors are actually limiting the product;
3. migrate one representative workflow as a control;
4. compare API stability, recovery semantics, platform integration and maintenance cost;
5. migrate further only when the benefits are measurable.

A new framework release is not itself a business case for migration.

FAQ

Are multiple agents automatically more accurate?

No. Multiple agents add independent model calls, context transfer and additional failure paths. Measure task success, tool error rate, model calls per task, token cost, human intervention and final acceptance rate.

Can SelectorGroupChat replace a business state machine?

No. Speaker selection decides who talks next. It does not define authoritative order, payment or approval state. Strong business constraints still belong in an explicit workflow or database state machine.

More to Explore

• AI Agent Frameworks 2026: LangGraph, Google ADK, AI SDK and Microsoft Agent Framework
• Complete AI Agent Engineering Guide
• LangGraph Human-in-the-loop approval
• AI Agent Tool Authorization Policy Gate

Topic path / AI Agents

Continue from one agent pattern to the complete production system

The AI Agent hub organizes architecture, memory, tool use, evaluation, security, deployment and multi-agent coordination into a single learning path.

Open AI Agent hub → Review the architecture guide Subscribe