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 autogenAPI from the AG2 community fork, published asautogen(andag2up to 0.14), checked againstautogen0.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 withpip install "autogen[openai]".
Table of Contents
Section titled “Table of Contents”- Core Architecture
- Agent Communication Patterns
- Multi-Agent Orchestration
- Nested Chats Architecture
- Sequential Chat Workflow
- Group Chat Speaker Selection
- Tool Integration Flow
- Code Execution Models
- State Management Architecture
- Serving over A2A
Core Architecture
Section titled “Core Architecture”AG2 Classic components
Section titled “AG2 Classic components”┌─────────────────────────────────────────────────────────────────┐│ 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) │ ││ │ │ ││ └─────────────────────────────────────────────────────────┘ ││ │└─────────────────────────────────────────────────────────────────┘Agent Hierarchy
Section titled “Agent Hierarchy” ConversableAgent △ ┌────────────┼────────────┐ │ │ │ AssistantAgent UserProxyAgent GroupChatManager
- LLM-enabled - Code execution - Multi-agent - Problem solving - Human-in-loop - Orchestration - Message replies - External tools - Speaker selectionAgent Communication Patterns
Section titled “Agent Communication Patterns”Two-Agent Conversation Flow
Section titled “Two-Agent Conversation Flow”┌─────────────────────────────────────────┐│ 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 foundAgent Message Flow
Section titled “Agent Message Flow” ┌─────────────────────────────────────┐ │ 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 │ └─────────────────────────────┘Multi-Agent Orchestration
Section titled “Multi-Agent Orchestration”Group Chat Architecture
Section titled “Group Chat Architecture”┌─────────────────────────────────────────────────────────┐│ GroupChatManager ││ (Central orchestration point) │└─────────────────────────────────────────────────────────┘ △ │ Coordinates ┌─────┴─────────┬─────────┐ │ │ │ ↓ ↓ ↓ ┌────────┐ ┌────────┐ ┌────────┐ │Agent A │ │Agent B │ │Agent C │ │Specialist Specialist Specialist │#1 │ │#2 │ │#3 │ └────────┘ └────────┘ └────────┘
Speaker Selection Loop:1. Analyse chat context2. Determine next speaker (auto/round-robin/manual)3. Request message from selected agent4. Broadcast to all agents5. Check termination condition6. RepeatSpeaker Selection Strategies
Section titled “Speaker Selection Strategies”┌──────────────────────────────────────────────────┐│ 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 ││ │└──────────────────────────────────────────────────┘Nested Chats Architecture
Section titled “Nested Chats Architecture”Hierarchical Chat Triggering
Section titled “Hierarchical Chat Triggering” ┌─────────────────────────┐ │ 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) │ └─────────────────────────┘Nested Chat Trigger Conditions
Section titled “Nested Chat Trigger Conditions”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 ConversationSequential Chat Workflow
Section titled “Sequential Chat Workflow”Multi-Stage Pipeline
Section titled “Multi-Stage Pipeline”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 outputGroup Chat Speaker Selection
Section titled “Group Chat Speaker Selection”Auto Selection Decision Tree
Section titled “Auto Selection Decision Tree” ┌─────────────────────┐ │ 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
Section titled “Tool Integration Flow”Function Registration and Execution
Section titled “Function Registration and Execution”┌─────────────────────────────────────────────────────────┐│ 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 Modes
Section titled “Tool Execution Modes”┌───────────────────────────────────────────────┐│ 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
Section titled “Code Execution Models”Local vs Docker Execution
Section titled “Local vs Docker Execution”┌──────────────────────────────────────────────────────────┐│ 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 Architecture
Section titled “State Management Architecture”Context Variables and Persistence
Section titled “Context Variables and Persistence”┌─────────────────────────────────────────────┐│ 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 chatsLifetime: Duration of agents and conversationsAccess: Thread-safe dictionary operationsServing over A2A
Section titled “Serving over A2A”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 │ │└────────────────────────────┘ └──────────────────────────────┘Complex Workflow Integration
Section titled “Complex Workflow Integration”End-to-End Content Creation System
Section titled “End-to-End Content Creation System”┌─────────────────────────────────────────────────────────────┐│ 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.Summary: Architecture at a Glance
Section titled “Summary: Architecture at a Glance”| Component | Role | Examples |
|---|---|---|
| Agents | Communication endpoints | ConversableAgent, AssistantAgent |
| Orchestrators | Multi-agent coordination | GroupChat, GroupChatManager, group-chat patterns |
| Execution | Running generated code | LocalCommandLineCodeExecutor, DockerCommandLineCodeExecutor |
| LLM Layer | Intelligence | OpenAI, Anthropic, Gemini, Ollama |
| Tools | Extended capabilities | Functions, APIs, external services |
| State | Shared context | ContextVariables, chat history |
| Serving | Exposing agents | A2aAgentServer, async chats |