Skip to content
AgPy

AG2 Classic Diagrams

Diagrams of AG2 Classic (import autogen) agents, message flow, group chat, nested and sequential chats, tools, code execution and A2A serving.

This page covers AG2 Classic — the import autogen API from the AG2 community fork, published as autogen (and ag2 up to 0.14), checked against autogen 0.14.1. It is not Microsoft AutoGen 0.4+ (autogen_agentchat; see the AgentChat & Core page), and it is not the current AG2 1.x API (see the AG2 guide). Install with pip install "autogen[openai]".

  1. Core Architecture
  2. Agent Communication Patterns
  3. Multi-Agent Orchestration
  4. Nested Chats Architecture
  5. Sequential Chat Workflow
  6. Group Chat Speaker Selection
  7. Tool Integration Flow
  8. Code Execution Models
  9. State Management Architecture
  10. Serving over A2A

┌─────────────────────────────────────────────────────────────────┐
│ AG2 Classic │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Agent Communication Layer │ │
│ │ │ │
│ │ ConversableAgent ←────────────────→ ConversableAgent │ │
│ │ (Core base class for all agents) │ │
│ └─────────────────────────────────────────────────────────┘ │
│ ↓ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Specialised Agent Types │ │
│ ├─────────────────────────────────────────────────────────┤ │
│ │ │ │
│ │ AssistantAgent UserProxyAgent GroupChatMgr │ │
│ │ (LLM-based problem (Human proxy + (Multi-agent │ │
│ │ solving) code execution) orchestration)│ │
│ │ │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Message & Execution Layer │ │
│ ├─────────────────────────────────────────────────────────┤ │
│ │ │ │
│ │ ┌──────────────────┐ ┌──────────────────────────┐ │ │
│ │ │ LLM Providers │ │ Code Execution │ │ │
│ │ │ • OpenAI │ │ • Local execution │ │ │
│ │ │ • Anthropic │ │ • Docker execution │ │ │
│ │ │ • Google Gemini │ │ • Custom executors │ │ │
│ │ │ • Ollama │ │ • Jupyter notebooks │ │ │
│ │ └──────────────────┘ └──────────────────────────┘ │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ Integration & Protocol Layer │ │
│ ├─────────────────────────────────────────────────────────┤ │
│ │ │ │
│ │ Function Registry | A2A Protocol | RAG System │ │
│ │ (Tool calling) | (JSON-RPC) | (Documents) │ │
│ │ │ │
│ └─────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
ConversableAgent
△
┌────────────┼────────────┐
│ │ │
AssistantAgent UserProxyAgent GroupChatManager
- LLM-enabled - Code execution - Multi-agent
- Problem solving - Human-in-loop - Orchestration
- Message replies - External tools - Speaker selection

┌─────────────────────────────────────────┐
│ Two-Agent Conversation │
└─────────────────────────────────────────┘
Agent A
△
│ (1) Send message
│
↓
Agent B
△
│ (2) Process & reply
│
↓
Agent A
△
│ (3) Review reply
│
↓
Agent B
...
Termination:
- max_turns reached
- Termination condition met
- TERMINATE keyword found
┌─────────────────────────────────────┐
│ Agent A initiates_chat │
└─────────────────────────────────────┘
│
↓
┌─────────────────────────────┐
│ Message Sent to Agent B │
│ • Content │
│ • Role (assistant/user) │
│ • Name │
│ • Timestamp │
└─────────────────────────────┘
│
↓
┌─────────────────────────────┐
│ Agent B Processes Message │
│ 1. Extract content │
│ 2. Check termination │
│ 3. Generate reply │
└─────────────────────────────┘
│
↓
┌─────────────────────────────┐
│ Reply Sent to Agent A │
│ • Generated content │
│ • Role = "assistant" │
│ • Name of Agent B │
└─────────────────────────────┘
│
↓
┌─────────────────────────────┐
│ Conversation Summary │
│ Chat history, messages, │
│ summary text │
└─────────────────────────────┘

┌─────────────────────────────────────────────────────────┐
│ GroupChatManager │
│ (Central orchestration point) │
└─────────────────────────────────────────────────────────┘
△
│ Coordinates
┌─────┴─────────┬─────────┐
│ │ │
↓ ↓ ↓
┌────────┐ ┌────────┐ ┌────────┐
│Agent A │ │Agent B │ │Agent C │
│Specialist Specialist Specialist
│#1 │ │#2 │ │#3 │
└────────┘ └────────┘ └────────┘
Speaker Selection Loop:
1. Analyse chat context
2. Determine next speaker (auto/round-robin/manual)
3. Request message from selected agent
4. Broadcast to all agents
5. Check termination condition
6. Repeat
┌──────────────────────────────────────────────────┐
│ Speaker Selection Methods │
├──────────────────────────────────────────────────┤
│ │
│ AUTO (LLM-based) │
│ ┌─────────────────────────────────────┐ │
│ │ LLM decides best next speaker │ │
│ │ Based on conversation context │ │
│ │ Intelligent turn taking │ │
│ └─────────────────────────────────────┘ │
│ ↓ │
│ Next Speaker: Dynamically selected │
│ │
│ ROUND-ROBIN │
│ ┌─────────────────────────────────────┐ │
│ │ Agent A → Agent B → Agent C → A... │ │
│ │ Deterministic turn sequence │ │
│ │ Predictable execution │ │
│ └─────────────────────────────────────┘ │
│ ↓ │
│ Next Speaker: Sequential rotation │
│ │
│ RANDOM │
│ ┌─────────────────────────────────────┐ │
│ │ Randomly select next speaker │ │
│ │ Unpredictable dialogue flow │ │
│ │ Less control, more variation │ │
│ └─────────────────────────────────────┘ │
│ ↓ │
│ Next Speaker: Random selection │
│ │
│ MANUAL │
│ ┌─────────────────────────────────────┐ │
│ │ A human picks each next speaker │ │
│ └─────────────────────────────────────┘ │
│ ↓ │
│ Next Speaker: Human choice │
│ │
│ CALLABLE (your function) │
│ ┌─────────────────────────────────────┐ │
│ │ f(last_speaker, groupchat) returns │ │
│ │ an Agent, a method name or None │ │
│ └─────────────────────────────────────┘ │
│ ↓ │
│ Next Speaker: Custom logic result │
│ │
└──────────────────────────────────────────────────┘

┌─────────────────────────┐
│ Main Conversation │
│ Agent A ←→ Agent B │
└─────────────────────────┘
│
│ (Trigger condition met)
↓
┌─────────────────────────┐
│ Nested Chat Level 1 │
│ Agent B ←→ Reviewer │
└─────────────────────────┘
│
│ (Summary: "code quality ok")
↓
┌─────────────────────────┐
│ Nested Chat Level 2 │
│ Reviewer ←→ Improver │
└─────────────────────────┘
│
│ (Summary: "improvements applied")
↓
┌─────────────────────────┐
│ Resume Main Conversation│
│ (Incorporate results) │
└─────────────────────────┘
Message Generated
│
↓
┌──────────────────────────┐
│ Check Trigger Condition │
│ (Function: is_triggered) │
└──────────────────────────┘
│
├─ YES ──→ ┌─────────────────────────┐
│ │ Execute Nested Chat │
│ │ • Queue configured │
│ │ • Message prepared │
│ │ • Summary method set │
│ │ • Max turns limited │
│ └─────────────────────────┘
│ │
│ ↓
│ ┌─────────────────────────┐
│ │ Embed Results in Main │
│ │ Chat Context │
│ └─────────────────────────┘
│
└─ NO ──→ Continue Main Conversation

Stage 1: Research
┌─────────────────────────┐
│ Coordinator → Researcher │
│ "Research topic X" │
└─────────────────────────┘
│
↓ Summary: "Key findings..."
│
↓ Carryover: Use findings
Stage 2: Analysis
┌─────────────────────────┐
│ Coordinator → Analyst │
│ "Analyse findings" │
└─────────────────────────┘
│
↓ Summary: "Analysis results..."
│
↓ Carryover: Use analysis
Stage 3: Writing
┌─────────────────────────┐
│ Coordinator → Writer │
│ "Write report" │
└─────────────────────────┘
│
↓ Summary: "Report draft..."
│
↓ Carryover: Review draft
Stage 4: Editing
┌─────────────────────────┐
│ Coordinator → Editor │
│ "Edit report" │
└─────────────────────────┘
│
↓ Final output

┌─────────────────────┐
│ Current Turn Ended │
└─────────────────────┘
│
↓
┌─────────────────────┐
│ Check Termination │
│ Conditions │
└─────────────────────┘
YES│
┌──────┴──────┐
│ END │
└─────────────┘
NO│
┌──────┴──────────────────────┐
│ Build context string │
│ (Recent messages, names) │
└─────────────────────────────┘
│
↓
┌─────────────────────┐
│ Send to LLM with │
│ prompt: │
│ "Who should speak?" │
└─────────────────────┘
│
↓
┌─────────────────────┐
│ Parse LLM response │
│ Extract agent name │
└─────────────────────┘
│
↓
┌─────────────────────┐
│ Select agent │
│ Request message │
└─────────────────────┘
│
↓
┌─────────────────────┐
│ Continue loop │
└─────────────────────┘

┌─────────────────────────────────────────────────────────┐
│ Tool Integration Flow │
└─────────────────────────────────────────────────────────┘
1. DEFINITION
┌──────────────────────────┐
│ Define function │
│ with type hints │
│ and docstring │
└──────────────────────────┘
│
↓
2. REGISTRATION
┌──────────────────────────┐
│ register_function() │
│ • Function │
│ • Caller agent │
│ • Executor agent │
│ • Description │
└──────────────────────────┘
│
↓
3. DISCOVERY
┌──────────────────────────┐
│ LLM discovers tool │
│ through schema │
│ (Auto-generated) │
└──────────────────────────┘
│
↓
4. INVOCATION
┌──────────────────────────┐
│ LLM decides to call tool │
│ • Generates parameters │
│ • Formats call │
└──────────────────────────┘
│
↓
5. EXECUTION
┌──────────────────────────┐
│ Executor runs function │
│ • Input validation │
│ • Error handling │
│ • Return result │
└──────────────────────────┘
│
↓
6. FEEDBACK
┌──────────────────────────┐
│ Result sent to LLM │
│ • Success or error │
│ • Continue generation │
└──────────────────────────┘
┌───────────────────────────────────────────────┐
│ Tool Execution Architecture │
└───────────────────────────────────────────────┘
┌─────────────────────────────┐
│ Caller Agent (LLM-based) │
│ • Decides when to call │
│ • Generates parameters │
│ • Processes results │
└─────────────────────────────┘
↑ │
│ │ Request with params
│ ↓
│ ┌─────────────────────────┐
│ │ Executor Agent │
│ │ • Receives request │
│ │ • Executes function │
│ │ • Returns result │
│ └─────────────────────────┘
│ │
└────────┘ Result
Two possibilities:
A) Executor = same as caller (single agent with function)
B) Executor = different agent (specialised executor)

┌──────────────────────────────────────────────────────────┐
│ Code Execution Models │
├──────────────────────────────────────────────────────────┤
│ │
│ LOCAL EXECUTION │
│ ┌──────────────────────────────────────┐ │
│ │ Assistant generates code │ │
│ │ │ │ │
│ │ ↓ │ │
│ │ Local command-line executor │ │
│ │ • Direct file system access │ │
│ │ • Same Python environment │ │
│ │ • Fast execution │ │
│ │ • Security: Full system access │ │
│ │ │ │ │
│ │ ↓ │ │
│ │ Result returned to agent │ │
│ └──────────────────────────────────────┘ │
│ │
│ DOCKER EXECUTION (Recommended) │
│ ┌──────────────────────────────────────┐ │
│ │ Assistant generates code │ │
│ │ │ │ │
│ │ ↓ │ │
│ │ Docker command-line executor │ │
│ │ • Spawn container │ │
│ │ • Image: python:3.11-slim (etc.) │ │
│ │ • Isolated filesystem │ │
│ │ • Resource limits (memory, CPU) │ │
│ │ • Security: Sandboxed environment │ │
│ │ │ │ │
│ │ ↓ │ │
│ │ Container executes code │ │
│ │ │ │ │
│ │ ↓ │ │
│ │ Capture stdout/stderr │ │
│ │ │ │ │
│ │ ↓ │ │
│ │ Return output to agent │ │
│ │ │ │ │
│ │ ↓ │ │
│ │ Container cleaned up │ │
│ └──────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────┐
│ State Management in AG2 Classic │
├─────────────────────────────────────────────┤
│ │
│ ┌──────────────────────────────────────┐ │
│ │ ContextVariables() │ │
│ │ (Shared state dictionary) │ │
│ ├──────────────────────────────────────┤ │
│ │ │ │
│ │ context.set("key", value) │ │
│ │ context.get("key") │ │
│ │ context.update(dict) │ │
│ │ │ │
│ └──────────────────────────────────────┘ │
│ △ △ △ △ △ △ │
│ │ │ │ │ │ │ │
│ ┌──────┘ │ │ │ │ └──────┐ │
│ │ │ │ │ │ │ │
│ ↓ ↓ ↓ ↓ ↓ ↓ │
│ Agent1 Agent2 Agent3 ... AgentN │
│ (Reads/ (Reads/ (Reads/ (Reads/ │
│ Writes) Writes) Writes) Writes) │
│ │
└─────────────────────────────────────────────┘
Scope: Multi-agent conversations, group chats
Lifetime: Duration of agents and conversations
Access: Thread-safe dictionary operations

autogen.a2a.A2aAgentServer(agent, url=...).build() returns a Starlette app; A2aRemoteAgent is the client side. See the production guide.

Client process Server process (uvicorn)
┌────────────────────────────┐ ┌──────────────────────────────┐
│ user (ConversableAgent) │ │ A2aAgentServer(...).build() │
│ a_initiate_chat(remote) │ │ │
│ │ │ GET /.well-known/agent-card.json │
│ ↓ │ ────────────→ │ agent card (name, skills) │
│ A2aRemoteAgent(url=...) │ │ │
│ │ JSON-RPC POST / │
│ │ ────────────→ │ AutogenAgentExecutor │
│ │ ←──────────── │ → ConversableAgent reply │
│ reply added to the chat │ task events │ │
└────────────────────────────┘ └──────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│ Content Creation System (Recipe #4) │
│ Sequential Pipeline │
└─────────────────────────────────────────────────────────────┘
Phase 1: Ideation
┌──────────────────┐
│ Idea Generator │ ──→ Generate 3 blog post angles
│ │ [Ideas exchanged between agents]
└──────────────────┘
│
↓ Summary: Selected angle
│
Phase 2: Research
┌──────────────────┐
│ Researcher │ ──→ Gather facts, statistics, insights
│ │ [Deep research phase]
└──────────────────┘
│
↓ Summary: Research findings
│
Phase 3: Writing
┌──────────────────┐
│ Writer │ ──→ Create 800-word blog post
│ │ [Incorporate research findings]
└──────────────────┘
│
↓ Summary: First draft
│
Phase 4: Editing
┌──────────────────┐
│ Editor │ ──→ Polish and refine
│ │ [Grammar, clarity, engagement]
└──────────────────┘
│
↓
Final Blog Post
Each phase's summary is carried over into the next phase's message.

ComponentRoleExamples
AgentsCommunication endpointsConversableAgent, AssistantAgent
OrchestratorsMulti-agent coordinationGroupChat, GroupChatManager, group-chat patterns
ExecutionRunning generated codeLocalCommandLineCodeExecutor, DockerCommandLineCodeExecutor
LLM LayerIntelligenceOpenAI, Anthropic, Gemini, Ollama
ToolsExtended capabilitiesFunctions, APIs, external services
StateShared contextContextVariables, chat history
ServingExposing agentsA2aAgentServer, async chats