AutoGen Fundamentals

Master the core concepts that power Microsoft's multi-agent AI framework

From single agents to collaborative teams - understand the building blocks of intelligent automation

What You'll Learn

AutoGen's three-layer architecture
Agents, Messages, and Teams concepts
Tool integration and workbenches
Model clients and context management

Multi-agent communication patterns
Human-in-the-loop workflows
When to use AgentChat vs Core
Best practices and design patterns

AutoGen Architecture Overview

AutoGen Studio

Purpose: Visual, no-code interface for prototyping agent teams

Best For:

Beginners to multi-agent systems
Rapid prototyping
Non-technical users
Concept validation

pip install -U autogenstudio
autogenstudio ui --port 8080

AgentChat

Purpose: High-level framework for conversational multi-agent applications

Best For:

Python developers
Conversational AI apps
Quick development
Preset agent types

pip install -U "autogen-agentchat"

AutoGen Core

Purpose: Event-driven foundation for scalable multi-agent systems

Best For:

Advanced developers
Distributed systems
Custom workflows
Enterprise applications

pip install "autogen-core"

Core Building Blocks

1. Agents - The Foundation

Agents are autonomous entities that can process messages, use tools, and make decisions.

Key Properties:

name: Unique identifier for the agent
description: Text description of the agent's purpose
run(): Method to execute tasks
run_stream(): Method for streaming responses

Common Agent Types:

AssistantAgent

AI-powered agent with LLM capabilities

Key Features:

Powered by language models (GPT-4, Claude, etc.)
Can use tools and function calls
Generates responses autonomously
Supports system message configuration
Built-in reasoning and planning capabilities

Best For:

Content generation and analysis
Code writing and debugging
Research and information processing
Complex problem-solving tasks

UserProxyAgent

Human interface and execution agent

Key Features:

Represents human users in conversations
Executes code and system commands
Can request human input when needed
Handles file operations and local tasks
No LLM - acts as execution proxy

Best For:

Code execution and testing
File system operations
Human-in-the-loop workflows
System integration tasks

Key Difference:

AssistantAgent thinks and generates content using AI, while UserProxyAgent executes actions and represents human users. They work together: AssistantAgent plans what to do, UserProxyAgent executes the plan.

                            Example 1: Single AssistantAgent
                            from autogen_agentchat.agents import AssistantAgent
from autogen_ext.models.openai import OpenAIChatCompletionClient
from autogen_agentchat.messages import TextMessage

# Create an AI assistant
assistant = AssistantAgent(
    name="assistant",
    model_client=OpenAIChatCompletionClient(
        model="gpt-4o"
    ),
    system_message="You are a helpful coding assistant."
)

# Use the assistant directly
task = TextMessage(content="Write a Python function to calculate fibonacci numbers")
result = await assistant.run(task=task)
print(result.messages[-1].content)
                        

                            Example 2: AssistantAgent + UserProxyAgent Collaboration
                            from autogen_agentchat.agents import AssistantAgent, UserProxyAgent
from autogen_ext.models.openai import OpenAIChatCompletionClient
from autogen_agentchat.teams import RoundRobinGroupChat
from autogen_agentchat.messages import TextMessage

# Create AI assistant (thinks and plans)
assistant = AssistantAgent(
    name="coder",
    model_client=OpenAIChatCompletionClient(model="gpt-4o"),
    system_message="You are an expert Python developer. Write code and explain your approach."
)

# Create user proxy (executes and validates)
user_proxy = UserProxyAgent(
    name="executor",
    human_input_mode="NEVER",  # Automatic execution
    code_execution_config={
        "executor": "python"  # Can execute Python code
    }
)

# Create a team for collaboration
team = RoundRobinGroupChat([assistant, user_proxy])

# Run a task that requires both thinking and execution
task = TextMessage(content="Create and test a function that finds prime numbers up to 100")
result = await team.run(task=task)

# The assistant writes code, user_proxy executes it and provides feedback
                        

2. Messages - Communication Protocol

Messages are the communication medium between agents, users, and systems.

Message Types:

TextMessage: Simple text content
MultiModalMessage: Text + images/files
ToolCallRequestEvent: Tool invocation request

ToolCallExecutionEvent: Tool execution result
StructuredMessage: Structured JSON output
TaskResult: Final result container

Key Insight: Messages maintain conversation history and context, enabling agents to build on previous interactions.

                            Message Creation:
                            from autogen_agentchat.messages import TextMessage

message = TextMessage(
    content="Hello, agent!",
    source="user"
)

result = await agent.run(task=message)
                        

3. Teams - Agent Coordination

Teams orchestrate multiple agents to work together on complex tasks.

Team Patterns:

RoundRobinGroupChat

Agents take turns in a fixed order

Predictable

SelectorGroupChat

One agent selects who speaks next

Flexible

Advanced Patterns:

Swarm: Decentralized agent coordination
GraphFlow: Directed workflow graphs
Magentic-One: Specialized multi-agent system

                            Team Creation:
                            from autogen_agentchat.teams import RoundRobinGroupChat

team = RoundRobinGroupChat([
    coder_agent,
    reviewer_agent,
    writer_agent
])

result = await team.run(
    task="Build a calculator app"
)
                        

4. Tools & Workbenches - Extended Capabilities

Tools extend agent capabilities beyond text generation to interact with external systems.

Tool Types:

Function Tools: Python functions as tools
HTTP Tools: Web API interactions
Code Execution: Run and test code

File Operations: Read/write files
MCP Tools: Model Context Protocol
Agent Tools: Use other agents as tools

Important: Tools execute within the agent's context and can be called in parallel for efficiency.

                            Tool Definition:
                            async def web_search(query: str) -> str:
    """Search the web for information"""
    # Implementation here
    return results

agent = AssistantAgent(
    name="researcher",
    model_client=model_client,
    tools=[web_search],
    system_message="Use tools to solve tasks."
)
                        

AgentChat vs Core: When to Use What?

Aspect	AgentChat	AutoGen Core
Learning Curve	Beginner Friendly	Advanced
Use Case	Conversational AI, prototypes, educational projects	Production systems, distributed agents, custom workflows
Agent Types	Preset agents (AssistantAgent, UserProxyAgent, etc.)	Fully custom agents with event-driven architecture
Communication	Direct method calls and message passing	Topic-subscription messaging patterns
Deployment	Single process/machine	Distributed across multiple machines
Customization	Configuration-based with some extensibility	Complete control over agent behavior
Development Speed	Fast - Quick prototyping	Moderate - More setup required

Your Learning Path

Start with AgentChat

Create Your First Agent

Start with AssistantAgent and simple tasks

Add Tools

Integrate web search, code execution, or file operations

Build Teams

Create multi-agent workflows with RoundRobinGroupChat

Human Integration

Add human-in-the-loop for oversight and control

Advance to Core

Understand Events

Learn the event-driven programming model

Custom Agents

Build agents with specialized behaviors

Distributed Systems

Scale across multiple machines and environments

Production Deployment

Add monitoring, logging, and observability

Best Practices & Tips

Do's

Start simple with single agents before building teams
Use descriptive agent names and system messages
Implement proper error handling and logging
Test individual agents before team integration
Use structured output for predictable responses
Implement human oversight for critical decisions

Don'ts

Don't create overly complex teams initially
Avoid circular dependencies between agents
Don't ignore token costs in multi-agent conversations
Avoid parallel tool calls with stateful tools
Don't hardcode API keys in your source code
Avoid infinite loops in agent conversations

Previous: Environment Setup

Congratulations! You've mastered the fundamentals!

Next: Agents & Models