AutoGen Tutorial (Python): testing agents locally for advanced developers

This tutorial shows you how to run and test AutoGen agents locally in Python without depending on a remote orchestration layer. You need this when you want deterministic debugging, faster iteration, and a clean way to validate agent behavior before wiring it into a larger system.

What You'll Need

• •Python 3.10 or newer
• •autogen-agentchat
• •autogen-ext
• •python-dotenv
• •An OpenAI API key, or another model provider supported by AutoGen
• •A local terminal where you can run Python scripts

Install the packages:

pip install autogen-agentchat autogen-ext python-dotenv

Step-by-Step

1. •Create a small local project and store your API key in an environment file. This keeps your test setup reproducible and avoids hardcoding secrets into agent test scripts.

mkdir autogen-local-test
cd autogen-local-test
touch .env test_agents.py

Add this to .env:

OPENAI_API_KEY=your_key_here

2. •Build a minimal assistant agent and a user proxy that can run locally. For advanced testing, keep the model config explicit so you can swap models or providers without changing agent logic.

import os
import asyncio
from dotenv import load_dotenv

from autogen_agentchat.agents import AssistantAgent, UserProxyAgent

load_dotenv()

assistant = AssistantAgent(
    name="assistant",
    system_message="You are a precise assistant that answers in one short paragraph.",
    llm_config={
        "model": "gpt-4o-mini",
        "api_key": os.environ["OPENAI_API_KEY"],
    },
)

user = UserProxyAgent(
    name="user",
    human_input_mode="NEVER",
)

3. •Wire the agents into a local conversation loop and print the output. This is the fastest way to verify your agent instructions, tool behavior, and message formatting before moving into multi-agent workflows.

async def main():
    result = await user.initiate_chat(
        assistant,
        message="Explain what local agent testing gives us in one paragraph.",
    )
    print(result.chat_history[-1]["content"])

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

4. •Add an assertion-based smoke test so you can run it as part of your development workflow. This catches regressions early when prompts, tools, or model settings change.

async def smoke_test():
    result = await user.initiate_chat(
        assistant,
        message="Return exactly: LOCAL_TEST_OK",
    )

    last_message = result.chat_history[-1]["content"]
    assert "LOCAL_TEST_OK" in last_message, last_message
    print("Smoke test passed")

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

5. •If you want deterministic local validation, mock the model boundary instead of calling the live API every time. The pattern below uses a fake response path so you can test orchestration logic without burning tokens.

class FakeAssistant:
    async def respond(self, message: str) -> str:
        if "LOCAL_TEST_OK" in message:
            return "LOCAL_TEST_OK"
        return f"echo: {message}"

async def offline_test():
    fake = FakeAssistant()
    response = await fake.respond("Return exactly: LOCAL_TEST_OK")
    assert response == "LOCAL_TEST_OK"
    print(response)

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

Testing It

Run python test_agents.py and confirm the script prints a valid assistant response with no stack traces. Then change the prompt slightly and verify the output changes in the way you expect; this tells you your agent is actually responding to input rather than returning cached assumptions.

For deeper validation, turn the smoke test into a small suite of assertions around tone, schema shape, or required keywords. If your agent will call tools later, add tests for tool selection and error handling now so failures stay local instead of surfacing in production.

Next Steps

• •Add tool calling with FunctionTool and test tool execution paths locally.
• •Move from single-agent chat to GroupChat for multi-agent coordination tests.
• •Wrap these checks in pytest so every prompt or config change runs through CI before merge.

Keep learning

• •The complete AI Agents Roadmap — my full 8-step breakdown
• •Free: The AI Agent Starter Kit — PDF checklist + starter code
• •Work with me — I build AI for banks and insurance companies

By Cyprian Aarons, AI Consultant at Topiax.