AutoGen: understand AgentChat and plan a supported migration

An inherited application imports autogen_agentchat, but the tutorial you found imports autogen. Which code should change? Identify the API generation and the project's support status before treating an example as current guidance.

Before you begin: Understand asynchronous Python, model clients, tools, and bounded agent loops.

Status checked September 10, 2026: Microsoft's official AutoGen repository says AutoGen is in maintenance mode and directs new users to Microsoft Agent Framework. This lesson remains useful for understanding and maintaining existing AutoGen systems. It is not a recommendation to start new production work on an unexamined older tutorial.

Keep the framework layers separate

AutoGen Core supplies an event-driven foundation. AgentChat provides higher-level conversational agents and team patterns. Extensions connect these components to model providers, tools, and execution environments. Studio is a prototyping interface built on this ecosystem.

An agent combines instructions, a model client, conversation state, and permitted tools. A team coordinates agents. These are application abstractions, not separate trained models by default.

The older 0.2 API and the later AgentChat API are different. Copying a class name from one and a configuration dictionary from the other can produce code that looks plausible but cannot run.

Begin with one agent

For an existing AgentChat project, verify its installed versions and read matching documentation. The integration below follows the documented AssistantAgent and OpenAIChatCompletionClient interface. It requires Python 3.10 or later, compatible autogen-agentchat and autogen-ext[openai] packages, a provider key in OPENAI_API_KEY, and a supported model name in AUTOGEN_MODEL.

This is a complete integration program, but it has not been executed against a paid model service as part of this lesson. It performs a model call and may incur provider charges.

import asyncio
import os
from autogen_agentchat.agents import AssistantAgent
from autogen_ext.models.openai import OpenAIChatCompletionClient

async def main():
    client = OpenAIChatCompletionClient(
        model=os.environ["AUTOGEN_MODEL"],
    )
    try:
        agent = AssistantAgent(
            "workshop_reader",
            model_client=client,
            system_message=(
                "Answer only from the supplied workshop record. "
                "Say when a requested detail is absent."
            ),
        )
        result = await agent.run(
            task="Record: pottery on Saturday; time unknown. When is it?"
        )
        print(result.messages[-1].content)
    finally:
        await client.close()

asyncio.run(main())

The expected behavior is to preserve the known day and the missing time. No exact generated wording is promised. If the answer invents a time, that is an evaluation failure to investigate, not a reason to label the fabricated answer as expected output.

Save the resolved package versions after a successful local smoke test. Do not combine an installation command that upgrades everything with a claim that the environment is reproducible.

Add tools and teams for a reason

A tool should contribute evidence or a clearly authorized action. Start with a read-only lookup returning structured records. Verify its arguments, identity scope, timeouts, and actual results outside the model.

If adding a team, define the coordinator's stopping condition and each worker's deliverable. Count total model calls and failed attempts. Several agents repeating the same source are not independent verification.

Agent state is not automatically an account boundary. Keep conversations and stored state associated with the correct authenticated user. Reusing a stateful agent instance across unrelated users can mix their context.

Reuse one stateful agent across two users

User A supplies a private preference. User B then receives the same in-memory agent instance and asks a related question. Even if the model client is shared safely, the agent's conversation state may contain A's input. Provider connection reuse and conversation reuse are different decisions.

Inventory stateful objects separately from reusable transport clients. Then port one read-only task and compare event ordering, termination, and restored history against the old implementation. A framework migration is a behavior change to evaluate, not merely an import replacement.

Plan a migration around behavior

Inventory your model clients, tools, team patterns, persistence, and streaming interface. Then identify the equivalent supported concepts using Microsoft's migration guide. Port a small read-only task first and compare the old and new systems on the same held-out cases.

Preserve evaluation fixtures and observable contracts rather than expecting a mechanical import rename to be sufficient. A migration can change event ordering, termination behavior, or state handling even when the final answer looks similar.

Practice an upgrade decision

A tutorial works only after installing an old package, but your application uses newer AgentChat imports. Should you downgrade the entire application?

Sources: the official AutoGen repository states its maintenance status and links to migration guidance; the AgentChat agents guide documents the integration pattern above.

Continue: Agent orchestration patterns, which helps you choose a workflow independently of the framework's name.