How do I get started with AutoGen AgentChat in Python (exact pip install + minimal working example)?

Most Python developers approach AutoGen AgentChat after outgrowing single openai.ChatCompletion calls and realizing they need something more structured for multi-step or multi-agent workflows. The good news is that getting started is mostly about a clean install and one minimal script that proves your setup is correct end‑to‑end.

Quick Answer: Install AgentChat and the OpenAI extension with: pip install -U "autogen-agentchat" "autogen-ext[openai]" (Python 3.10+), set your OPENAI_API_KEY, and run a minimal AssistantAgent script using OpenAIChatCompletionClient. That gives you a working single-agent chat you can later evolve into multi-agent workflows.

Why This Matters

If you skip the “exact pip install + minimal working example” step, you end up debugging environment issues and model clients in the middle of designing your agents. Locking in a known-good baseline lets you focus on agent behavior, message routing, and eventually multi-agent patterns rather than plumbing.

Key Benefits:

• Fast validation: A minimal AssistantAgent script tells you your Python version, packages, and OpenAI credentials are wired correctly.
• Clear upgrade path: Starting with AgentChat (built on Core) means you can later move to richer patterns—Teams, GraphFlow, or custom runtimes—without redesigning from scratch.
• Runtime-oriented thinking: You learn early that model calls run inside a runtime (SingleThreadedAgentRuntime in Core, or AgentChat’s defaults), which is where most real-world failures actually surface.

Core Concepts & Key Points

Concept	Definition	Why it's important
AgentChat	A high-level Python API (autogen-agentchat) for building conversational single- and multi-agent applications, built on top of autogen-core.	Recommended starting point: you get sane defaults and don’t have to design an event-driven runtime on day one.
AssistantAgent	A generic LLM-backed agent in AgentChat that can hold a conversation and respond to prompts using a configured model client.	It’s the minimal building block for a working example; almost every workflow uses it or something derived from it.
OpenAIChatCompletionClient	A model client from autogen-ext that connects AssistantAgent to OpenAI Chat Completions (or compatible APIs).	Decouples agent logic from the model provider so you can swap or configure models without rewriting agent code.

How It Works (Step-by-Step)

At a minimum, “getting started” means:

1. Creating an isolated Python environment with Python 3.10+.
2. Installing autogen-agentchat plus autogen-ext[openai].
3. Setting an OPENAI_API_KEY.
4. Running a small async script that instantiates an AssistantAgent and sends a message.

From there you can decide whether to stay in single-agent land for a while or move to multi-agent Teams and eventually Core runtimes.

1. Check Python Version and Create a Virtual Environment

AgentChat requires Python 3.10 or later.

python3 --version

If you’re below 3.10, install a newer Python before proceeding.

You can use venv or conda; I’ll show both.

Option A – venv (Linux/Mac):

python3 -m venv .venv
source .venv/bin/activate

Option A – venv (Windows PowerShell):

python -m venv .venv
.\.venv\Scripts\Activate.ps1

Option B – conda:

conda create -n autogen python=3.12
conda activate autogen

Note: A virtual environment isn’t strictly required, but in a regulated enterprise I treat it as mandatory to keep dependencies isolated and reproducible.

2. Install AutoGen AgentChat and the OpenAI Extension

Run this in your activated environment:

pip install -U "autogen-agentchat" "autogen-ext[openai]"

• autogen-agentchat gives you the high-level agent APIs.
• autogen-ext[openai] installs the OpenAI model client integration used in the minimal example.

Note: Upgrading (-U) avoids getting stuck on an older 0.2.x version if you already experimented with AutoGen before. For fresh installs it’s harmless; for existing ones it aligns you with the current 0.4-style stack.

3. Configure Your OpenAI Credentials

AgentChat’s OpenAI client expects an API key in the environment.

On Linux/Mac:

export OPENAI_API_KEY="sk-..."

On Windows PowerShell:

$env:OPENAI_API_KEY="sk-..."

If you’re using Azure OpenAI, you’d typically use autogen-ext[azure] and configure endpoint + key instead; for a first minimal example, plain OpenAI is simpler.

Note: Costs come from your OpenAI usage, not from AutoGen itself. AutoGen is a framework you install via pip.

4. Minimal Working Example: A Single AssistantAgent

Now that the plumbing is in place, the goal is a minimal script that:

• Builds an AssistantAgent using OpenAIChatCompletionClient.
• Sends a message.
• Prints the agent’s reply.

Create a file called minimal_agentchat_example.py:

import asyncio

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


async def main() -> None:
    # 1. Create the model client.
    #    Adjust model="gpt-4o-mini" (or another model) as needed.
    model_client = OpenAIChatCompletionClient(
        model="gpt-4o-mini"
    )

    # 2. Create an AssistantAgent backed by that model client.
    assistant = AssistantAgent(
        name="assistant",
        model_client=model_client,
    )

    # 3. Send a simple user message and await the response.
    user_message = "In one paragraph, explain what AutoGen AgentChat does."
    print(f"User: {user_message}\n")

    # AgentChat uses async; most calls are awaitable.
    response = await assistant.on_message(user_message)

    # 4. Print out the assistant's response text.
    #    'response' is typically a Message-like object; we'll use its 'content' attribute.
    print("Assistant:")
    print(response.content)


if __name__ == "__main__":
    asyncio.run(main())

Run it:

python minimal_agentchat_example.py

If everything is wired correctly you should see:

• Your user prompt printed.
• A short paragraph response from the agent describing AgentChat.

Note: If you see authentication errors, re-check OPENAI_API_KEY. If you see model errors, ensure the model you specified exists in your OpenAI account.

Common Mistakes to Avoid

• Skipping the virtual environment:
  This often leads to conflicting dependency versions (especially if you have older AutoGen or OpenAI libraries already installed). Always isolate with venv or conda so you can cleanly upgrade or pin versions.

• Using the wrong Python version or stale AutoGen release:
  AgentChat requires Python 3.10 or later, and the 0.4 stack differs from 0.2.x. If your import paths or behavior don’t match current docs, verify with python -V and pip show autogen-agentchat that you’re on a current release.

• Hard-wiring model logic instead of using model clients:
  Don’t embed direct openai.ChatCompletion.create calls inside your agents. Use OpenAIChatCompletionClient from autogen-ext so you can change configuration (model, base URL, timeouts) without reworking agent code.

Real-World Example

In our internal platform, we evolved a minimal AssistantAgent like the one above into a multi-agent “triage + specialist” workflow:

• A triage_assistant (also an AssistantAgent) receives the initial user request and classifies it.
• Based on classification, we forward the request to a policy_assistant or a tech_assistant (both AgentChat agents behind the scenes).
• We later migrated that logic onto autogen-core runtimes and used topics/subscriptions for routing, but we deliberately started with the barebones single AssistantAgent script first.

That first script caught all the usual issues—wrong Python version on a dev box, missing environment variables in CI, and a misconfigured OpenAI project—before we layered on any complexity. Without that baseline, debugging across three agents and a distributed runtime would have been painful.

Pro Tip: Commit your minimal AssistantAgent script to the repo and wire it into CI as a smoke test. If a dependency or environment change breaks your ability to complete a single prompt/response, you’ll catch it before it impacts more complex agent workflows.

Summary

Getting started with AutoGen AgentChat in Python is mostly about a disciplined first run:

• Use Python 3.10+ in an isolated environment.
• Install the exact packages:
  pip install -U "autogen-agentchat" "autogen-ext[openai]"
• Set OPENAI_API_KEY.
• Run a minimal AssistantAgent example that makes one model call via OpenAIChatCompletionClient.

Once that works, you have a verified foundation to explore AgentChat Teams, integrate tools, or move down-stack into autogen-core runtimes and message routing patterns without wondering if your basic setup is broken.

Next Step

Get Started