AutoGen quickstart: connect to Azure OpenAI using autogen-ext[azure] and run a basic AssistantAgent — show the code

Most teams hit the same wall the first time they try to wire AutoGen to Azure OpenAI: the SDKs and keys are set up, but the agent runtime can’t actually talk to the Azure endpoint. The good news is that with autogen-ext[azure] and a minimal AgentChat script, you can get a basic AssistantAgent running in a few minutes.

Quick Answer: Use autogen-agentchat with the Azure-specific client in autogen-ext[azure] (AzureOpenAIChatCompletionClient) to connect an AssistantAgent to your Azure OpenAI deployment. Configure your Azure endpoint, API key (or AAD auth), and deployment name via environment variables, then run a short async script that calls agent.run(task=...) and prints the response.

Why This Matters

If you’re in a regulated or enterprise environment, your LLM traffic almost always goes through Azure OpenAI rather than public OpenAI endpoints. Connecting AutoGen AgentChat to Azure OpenAI with autogen-ext[azure] lets you:

• keep data within your organization’s Azure boundary,
• reuse existing Azure governance and networking controls, and
• build agentic workflows (single- and multi-agent) on top of the same models you’ve already approved.

Once your first AssistantAgent is talking to Azure OpenAI, you can scale up to multi-agent teams, GraphFlow graphs, and distributed runtimes without reworking your model plumbing.

Key Benefits:

• Azure-native model routing: Use AzureOpenAIChatCompletionClient to target specific deployments and API versions that match your production Azure OpenAI setup.
• Separation of concerns: Keep AutoGen runtime and agent logic intact while swapping model providers through autogen-ext clients—no hard-coded SDK usage in your business logic.
• Production-aligned from day one: Start with the same Azure OpenAI configuration (VNet, AAD, limited keys) you’ll need in production, so your quickstart doesn’t become throwaway code.

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 on top of AutoGen Core.	Gives you clean abstractions like AssistantAgent and Teams without requiring you to manage the low-level event-driven runtime on day one.
AzureOpenAIChatCompletionClient	A model client in autogen-ext[azure] that wraps Azure OpenAI chat completions for use by AutoGen agents.	Handles Azure-specific details (endpoint, deployment name, API version, auth) so your agents can call Azure OpenAI like any other chat model.
AssistantAgent	A general-purpose LLM-backed agent (autogen_agentchat.agents.AssistantAgent) that turns a chat completion model into a conversational assistant.	The fastest way to verify your Azure OpenAI connection and confirm that AgentChat + autogen-ext[azure] are wired correctly.

How It Works (Step-by-Step)

At a high level, the flow looks like this:

1. Install the right AutoGen packages and Azure extension.
2. Configure Azure OpenAI credentials and deployment information.
3. Create an AzureOpenAIChatCompletionClient and inject it into an AssistantAgent.
4. Run a simple task and inspect the output.

1. Installation

You need Python 3.10 or later.

Install AgentChat and the Azure extensions:

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

This gives you:

• autogen-agentchat — high-level agents and teams.
• autogen-ext[azure] — Azure-specific model clients and tooling, including AzureOpenAIChatCompletionClient.

2. Configure Azure OpenAI

AutoGen doesn’t manage your Azure credentials; it expects you to configure them via environment or your own secrets mechanism.

The minimal configuration for API key–based auth usually looks like:

# Bash / zsh
export AZURE_OPENAI_ENDPOINT="https://<your-resource-name>.openai.azure.com"
export AZURE_OPENAI_API_KEY="<your-azure-openai-key>"
export AZURE_OPENAI_DEPLOYMENT_NAME="<your-chat-deployment-name>"
export AZURE_OPENAI_API_VERSION="2024-02-15-preview"  # Example; use your approved version

Typical values:

• AZURE_OPENAI_ENDPOINT: your Azure OpenAI resource endpoint.
• AZURE_OPENAI_API_KEY: a key scoped to that resource.
• AZURE_OPENAI_DEPLOYMENT_NAME: the deployment name for your chat model (e.g., gpt-4o, gpt-4o-mini).
• AZURE_OPENAI_API_VERSION: API version you’ve standardized on.

Note: Azure AD–based auth is also supported via autogen-ext[azure], but for a quickstart, API key auth is less configuration and easier to validate.

3. Minimal AssistantAgent using Azure OpenAI

Below is a minimal, runnable script that:

• creates an AzureOpenAIChatCompletionClient,
• wires it into an AssistantAgent, and
• runs a single task against your Azure OpenAI deployment.

import asyncio
import os

from autogen_agentchat.agents import AssistantAgent
from autogen_ext.models.azure import AzureOpenAIChatCompletionClient


async def main() -> None:
    # Read configuration from environment variables
    endpoint = os.environ["AZURE_OPENAI_ENDPOINT"]
    api_key = os.environ["AZURE_OPENAI_API_KEY"]
    deployment_name = os.environ["AZURE_OPENAI_DEPLOYMENT_NAME"]
    api_version = os.environ.get("AZURE_OPENAI_API_VERSION", "2024-02-15-preview")

    # Create Azure OpenAI chat completion client
    model_client = AzureOpenAIChatCompletionClient(
        azure_endpoint=endpoint,
        api_key=api_key,
        model=deployment_name,     # this is your Azure deployment name
        api_version=api_version,
    )

    # Create a basic AssistantAgent that uses this Azure model
    assistant = AssistantAgent(
        name="azure_assistant",
        model_client=model_client,
        system_message="You are a helpful assistant running on Azure OpenAI.",
    )

    # Run a simple task
    result = await assistant.run(
        task="In one short paragraph, explain what AutoGen is and how it helps build AI agents."
    )

    print("=== Assistant Output ===")
    print(result)

    # Clean up model client resources if needed
    await model_client.close()

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

Run it:

python azure_assistant_quickstart.py

If your credentials and deployment are correct, you should see a short paragraph from the assistant in your terminal.

4. Adding a console UI (optional, but helpful)

When I’m validating connectivity and behavior, I like to drop in the AgentChat console UI for quick manual probing:

import asyncio
import os

from autogen_agentchat.agents import AssistantAgent
from autogen_agentchat.ui import Console
from autogen_ext.models.azure import AzureOpenAIChatCompletionClient


async def main() -> None:
    endpoint = os.environ["AZURE_OPENAI_ENDPOINT"]
    api_key = os.environ["AZURE_OPENAI_API_KEY"]
    deployment_name = os.environ["AZURE_OPENAI_DEPLOYMENT_NAME"]
    api_version = os.environ.get("AZURE_OPENAI_API_VERSION", "2024-02-15-preview")

    model_client = AzureOpenAIChatCompletionClient(
        azure_endpoint=endpoint,
        api_key=api_key,
        model=deployment_name,
        api_version=api_version,
    )

    assistant = AssistantAgent(
        name="azure_assistant",
        model_client=model_client,
        system_message="You are a concise, technically accurate assistant.",
    )

    # Interactive console chat
    console = Console(assistant)
    await console.run()

    await model_client.close()


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

This gives you a REPL-style loop where you can type prompts and inspect the responses coming from your Azure deployment.

Common Mistakes to Avoid

• Using the base OpenAI client instead of the Azure client:
  Don’t use OpenAIChatCompletionClient when you’re targeting Azure; use AzureOpenAIChatCompletionClient from autogen-ext[azure]. The Azure endpoint shape, deployment naming, and API versions are different and need the dedicated client.

• Mixing model and deployment names:
  Azure often names deployments differently from the underlying model (e.g., deployment prod-gpt4o serving gpt-4o). In AzureOpenAIChatCompletionClient, the model parameter should be the deployment name, not the raw model ID. If you pass the model ID, you’ll get confusing “deployment not found” errors from Azure.

Real-World Example

In our internal “agent platform” setup, we started by wiring a simple AssistantAgent to Azure OpenAI exactly like the quickstart script above. Once that was stable, we:

• standardized a small set of environment-variable conventions for endpoint, API key, and deployment names,
• wrapped the AzureOpenAIChatCompletionClient construction in a small helper that every agent uses, and
• moved from single-agent scripts to Team patterns (e.g., RoundRobinGroupChat) and eventually to an event-driven Core runtime with topics and subscriptions.

Because all of the Azure-specific logic lived inside the model_client constructor, we could reuse the same AssistantAgent definitions across local SingleThreadedAgentRuntime and our distributed runtime topology (host servicer + workers + gateways) without changing the agent code.

Pro Tip: Before you build multi-agent workflows, put your Azure connection under a simple health check: a standalone script that creates an AzureOpenAIChatCompletionClient, sends a trivial prompt ("Say 'healthy'"), and exits non-zero on failure. Wire that into CI so you fail fast when keys, endpoints, or API versions drift.

Summary

Connecting AutoGen to Azure OpenAI is mostly about choosing the right extension (autogen-ext[azure]) and using the dedicated AzureOpenAIChatCompletionClient with correct deployment and endpoint settings. Once that’s in place, an AssistantAgent in AgentChat is a thin layer on top that lets you validate the connection and start experimenting with conversational logic.

From there, you can scale up:

• keep the same Azure client but drop the agent into Teams or GraphFlow,
• run on SingleThreadedAgentRuntime locally or a distributed runtime in production, and
• add message filtering or topic-based routing as your conversational workflows grow.

Next Step

Get Started