How microsoft/autogen works
Purpose and entry points
AutoGen is a maintenance-mode, multi-language framework for building autonomous or human-assisted multi-agent AI applications. The primary product is a Python package ecosystem; .NET provides both earlier chat-oriented libraries and a lower-level distributed agent runtime. Main user entry points are Python imports from python/packages/autogen-core/src/autogen_core/__init__.py, python/packages/autogen-agentchat/src/autogen_agentchat/__init__.py, and python/packages/autogen-ext/src/autogen_ext/__init__.py; Studio exposes a CLI and web server through python/packages/autogen-studio/autogenstudio/cli.py and python/packages/autogen-studio/autogenstudio/web/app.py.
Python Core: event-driven agent runtime
autogen-core defines the low-level contracts for agent identity, lifecycle, messages, topics, subscriptions, serialization, cancellation, and component configuration. Applications register agents and subscriptions with an in-process runtime, then send direct messages or publish topic messages; the runtime resolves recipients and invokes handlers. Key paths: python/packages/autogen-core/src/autogen_core/_agent_runtime.py, python/packages/autogen-core/src/autogen_core/_single_threaded_agent_runtime.py, python/packages/autogen-core/src/autogen_core/_routed_agent.py.
Core also owns model-client/tool abstractions and context/memory boundaries rather than a provider implementation. ModelContext controls conversation history/token scope; tools/workbenches expose callable capabilities to agents. Paths: python/packages/autogen-core/src/autogen_core/models/_model_client.py, python/packages/autogen-core/src/autogen_core/tools/_workbench.py, python/packages/autogen-core/src/autogen_core/model_context/_chat_completion_context.py.
AgentChat: opinionated application layer
autogen-agentchat builds user-facing conversational agents and teams atop Core. AssistantAgent drives model inference, tool calls, streaming, and task execution; user/code-executor/society-of-mind agents provide specialized interaction roles. Messages, task results, handoffs, termination conditions, and persisted state are AgentChat-level control data. Paths: python/packages/autogen-agentchat/src/autogen_agentchat/agents/_assistant_agent.py, python/packages/autogen-agentchat/src/autogen_agentchat/messages.py, python/packages/autogen-agentchat/src/autogen_agentchat/base/_team.py.
Teams coordinate turns and stop conditions. Group-chat implementations support round-robin, selector, swarm, sequential routing, graph-directed flow, and Magentic-One orchestration. A task enters a team, agent containers route messages/turns, and the team emits streamed events until termination. Paths: python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_base_group_chat.py, python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_graph/_digraph_group_chat.py, python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_magentic_one/_magentic_one_orchestrator.py.
Extensions and external boundaries
autogen-ext supplies implementations behind Core interfaces: model clients for OpenAI/Azure, Anthropic, Ollama, llama.cpp, Semantic Kernel, and replay/cache; it isolates provider-specific message transformations and credentials. Paths: python/packages/autogen-ext/src/autogen_ext/models/openai/_openai_client.py, python/packages/autogen-ext/src/autogen_ext/models/anthropic/_anthropic_client.py, python/packages/autogen-ext/src/autogen_ext/models/azure/_azure_ai_client.py.
Extensions also bridge agents to unsafe or external capabilities: Docker/Jupyter/Azure code execution, browser automation via Playwright, MCP servers over stdio/SSE/HTTP, HTTP tools, Redis/Chroma/Mem0 memory, and Azure AI Search/GraphRAG. These are explicit trust and deployment boundaries. Paths: python/packages/autogen-ext/src/autogen_ext/tools/mcp/_workbench.py, python/packages/autogen-ext/src/autogen_ext/code_executors/docker/_docker_code_executor.py, python/packages/autogen-ext/src/autogen_ext/runtimes/grpc/_worker_runtime.py.
Distributed and cross-language runtime
The shared worker protocol defines CloudEvent- and gRPC-based cross-process communication. Python worker hosts expose Core agents to a gateway; .NET implements corresponding contracts, local runtime, gRPC router, and an Orleans-backed registry/message gateway. Paths: protos/agent_worker.proto, dotnet/src/Microsoft.AutoGen/Core.Grpc/GrpcAgentRuntime.cs, dotnet/src/Microsoft.AutoGen/RuntimeGateway.Grpc/Services/Grpc/GrpcGatewayService.cs.
The .NET runtime’s central flow is IAgentRuntime → agent proxy/identity → subscriptions and handler dispatch, with in-process and gRPC implementations. Paths: dotnet/src/Microsoft.AutoGen/Contracts/IAgentRuntime.cs, dotnet/src/Microsoft.AutoGen/Core/InProcessRuntime.cs, dotnet/src/Microsoft.AutoGen/Contracts/TopicId.cs.
.NET AgentChat and provider stack
A separate .NET library family offers chat agents, messages, middleware, group chats, and orchestrators, with adapters for OpenAI, Azure AI Inference, Anthropic, Gemini, Mistral, Ollama, and Semantic Kernel. It is organized around pluggable agent/provider implementations rather than the distributed Core runtime. Paths: dotnet/src/AutoGen.Core/Agent/IAgent.cs, dotnet/src/AutoGen.Core/GroupChat/GroupChat.cs, dotnet/src/AutoGen.OpenAI/Agent/OpenAIChatAgent.cs.
Developer products and infrastructure
AutoGen Studio is a prototype-oriented no-code application: a Gatsby/TypeScript frontend calls a Python backend that persists components, teams, sessions, runs, evaluations, and gallery data, with REST/WebSocket and MCP integration. Paths: python/packages/autogen-studio/autogenstudio/teammanager/teammanager.py, python/packages/autogen-studio/autogenstudio/web/routes/runs.py, python/packages/autogen-studio/frontend/src/components/views/teambuilder/builder/builder.tsx.
AGBench is the evaluation CLI for benchmark templates, containerized scenario execution, log processing, and tabulation. Paths: python/packages/agbench/src/agbench/cli.py, python/packages/agbench/src/agbench/run_cmd.py, python/packages/agbench/src/agbench/res/Dockerfile. CI spans GitHub Actions and Azure Pipelines; local development supports Docker/devcontainers.
Main entry points: _single_threaded_agent_runtime.py Single-threaded runtime · _assistant_agent.py Assistant agent · _base_group_chat.py Teams & group chats · _model_client.py Model, context & tools
Components 21
Python packages
- Core public API · Agent contracts, identity, lifecycle, serialization, and cancellation.
python/packages/autogen-core/src/autogen_core/__init__.py - Single-threaded runtime · Routes direct and topic messages to registered agent handlers.
python/packages/autogen-core/src/autogen_core/_single_threaded_agent_runtime.py - Routed agents
python/packages/autogen-core/src/autogen_core/_routed_agent.py - Model, context & tools · Provider-neutral model client, history scope, and callable workbench contracts.
python/packages/autogen-core/src/autogen_core/models/_model_client.py - AgentChat API · User-facing messages, task control, state, and specialized agents.
python/packages/autogen-agentchat/src/autogen_agentchat/messages.py - Assistant agent · Drives inference, tool calls, streaming, and task execution.
python/packages/autogen-agentchat/src/autogen_agentchat/agents/_assistant_agent.py - Teams & group chats · Coordinates turns, routing, streamed events, and termination.
python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_base_group_chat.py - Graph & Magentic-One flows
python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_graph/_digraph_group_chat.py - Provider model clients · OpenAI, Azure, Anthropic, local, replay, and other provider adapters.
python/packages/autogen-ext/src/autogen_ext/models/openai/_openai_client.py - External capability bridges · MCP, code execution, browser, HTTP, memory, and search integrations.
python/packages/autogen-ext/src/autogen_ext/tools/mcp/_workbench.py
Distributed runtime
- Python gRPC worker · Hosts Core agents for cross-process execution.
python/packages/autogen-ext/src/autogen_ext/runtimes/grpc/_worker_runtime.py - Agent worker protocol · Shared cross-process worker communication contract.
protos/agent_worker.proto - Runtime gateway · Routes worker traffic through the distributed gateway.
dotnet/src/Microsoft.AutoGen/RuntimeGateway.Grpc/Services/Grpc/GrpcGatewayService.cs
.NET libraries
- .NET runtime contracts · IAgentRuntime, identities, topics, subscriptions, and dispatch contracts.
dotnet/src/Microsoft.AutoGen/Contracts/IAgentRuntime.cs - .NET in-process runtime · Local proxy, subscription, and handler dispatch implementation.
dotnet/src/Microsoft.AutoGen/Core/InProcessRuntime.cs - .NET gRPC runtime
dotnet/src/Microsoft.AutoGen/Core.Grpc/GrpcAgentRuntime.cs - .NET AgentChat · Separate pluggable chat-agent and group-chat family.
dotnet/src/AutoGen.Core/Agent/IAgent.cs - .NET provider adapters
dotnet/src/AutoGen.OpenAI/Agent/OpenAIChatAgent.cs
Developer products
- AutoGen Studio backend · Persists components, teams, sessions, runs, evaluations, and gallery data.
python/packages/autogen-studio/autogenstudio/cli.py - Studio frontend · No-code team-building interface.
python/packages/autogen-studio/frontend/src/components/views/teambuilder/builder/builder.tsx - AGBench · Runs containerized benchmark scenarios and processes results.
python/packages/agbench/src/agbench/cli.py
Connections 24
- Core public API → Single-threaded runtime: defines runtime contract
- Single-threaded runtime → Routed agents: invokes handlers
- Single-threaded runtime → Model, context & tools: hosts agent dependencies
- AgentChat API → Core public API: builds on
- Assistant agent → AgentChat API: implements
- Assistant agent → Model, context & tools: uses models and tools
- Teams & group chats → AgentChat API: coordinates agents
- Teams & group chats → Assistant agent: routes turns to
- Graph & Magentic-One flows → Teams & group chats: specializes
- Provider model clients → Model, context & tools: implements model clients
- External capability bridges → Model, context & tools: implements tools and memory
- Python gRPC worker → Single-threaded runtime: hosts
- Python gRPC worker → Agent worker protocol: speaks
- .NET in-process runtime → .NET runtime contracts: implements
- .NET gRPC runtime → .NET runtime contracts: implements
- .NET gRPC runtime → Agent worker protocol: speaks
- Runtime gateway → Agent worker protocol: routes
- Runtime gateway → Python gRPC worker: connects workers
- Runtime gateway → .NET gRPC runtime: connects runtime
- .NET AgentChat → .NET provider adapters: uses providers
- Studio frontend → AutoGen Studio backend: REST, WebSocket, MCP
- AutoGen Studio backend → Teams & group chats: configures and runs
- AutoGen Studio backend → External capability bridges: integrates MCP
- AGBench → Assistant agent: evaluates agent scenarios