# microsoft/autogen architecture

> Architecture diagram of the GitHub repository microsoft/autogen, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/microsoft/autogen
- Repository: https://github.com/microsoft/autogen
- Video tour (about a minute): https://gitdiagram.com/microsoft/autogen/video

## Overview

#### 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: [`python/packages/autogen-core/src/autogen_core/_single_threaded_agent_runtime.py`](https://github.com/microsoft/autogen/blob/main/python/packages/autogen-core/src/autogen_core/_single_threaded_agent_runtime.py) (Single-threaded runtime), [`python/packages/autogen-agentchat/src/autogen_agentchat/agents/_assistant_agent.py`](https://github.com/microsoft/autogen/blob/main/python/packages/autogen-agentchat/src/autogen_agentchat/agents/_assistant_agent.py) (Assistant agent), [`python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_base_group_chat.py`](https://github.com/microsoft/autogen/blob/main/python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_base_group_chat.py) (Teams & group chats), [`python/packages/autogen-core/src/autogen_core/models/_model_client.py`](https://github.com/microsoft/autogen/blob/main/python/packages/autogen-core/src/autogen_core/models/_model_client.py) (Model, context & tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_python["Python packages"]
  node_py_core_api["Core public API<br/>Python package<br/>[__init__.py]"]
  node_py_runtime{{"Single-threaded runtime<br/>agent runtime"}}
  node_py_routed_agent["Routed agents<br/>handler dispatch<br/>[_routed_agent.py]"]
  node_py_model_tools["Model, context &amp; tools<br/>Core abstractions<br/>[_model_client.py]"]
  node_agentchat["AgentChat API<br/>conversation layer<br/>[messages.py]"]
  node_assistant["Assistant agent<br/>agent implementation"]
  node_teams{{"Teams &amp; group chats<br/>orchestration"}}
  node_graph_team["Graph &amp; Magentic-One flows<br/>team strategies"]
  node_extensions["Provider model clients<br/>extension implementations<br/>[_openai_client.py]"]
  node_external_caps{{"External capability bridges<br/>trust boundary<br/>[_workbench.py]"}}
end

subgraph group_distributed["Distributed runtime"]
  node_py_worker{{"Python gRPC worker<br/>distributed worker<br/>[_worker_runtime.py]"}}
  node_worker_protocol["Agent worker protocol<br/>gRPC / CloudEvent contract<br/>[agent_worker.proto]"]
  node_gateway{{"Runtime gateway<br/>gRPC gateway"}}
end

subgraph group_dotnet[".NET libraries"]
  node_dotnet_contracts[".NET runtime contracts<br/>runtime interfaces<br/>[IAgentRuntime.cs]"]
  node_dotnet_runtime{{".NET in-process runtime<br/>agent runtime"}}
  node_dotnet_grpc{{".NET gRPC runtime<br/>distributed runtime"}}
  node_net_agentchat[".NET AgentChat<br/>chat agent library<br/>[IAgent.cs]"]
  node_net_providers[".NET provider adapters<br/>provider implementation<br/>[OpenAIChatAgent.cs]"]
end

subgraph group_products["Developer products"]
  node_studio["AutoGen Studio backend<br/>CLI and web server<br/>[cli.py]"]
  node_studio_ui["Studio frontend<br/>Gatsby / TypeScript UI<br/>[builder.tsx]"]
  node_agbench["AGBench<br/>evaluation CLI<br/>[cli.py]"]
end

node_py_core_api -->|"defines runtime contract"| node_py_runtime
node_py_runtime -->|"invokes handlers"| node_py_routed_agent
node_py_runtime -->|"hosts agent dependencies"| node_py_model_tools
node_agentchat -->|"builds on"| node_py_core_api
node_assistant -->|"implements"| node_agentchat
node_assistant -->|"uses models and tools"| node_py_model_tools
node_teams -->|"coordinates agents"| node_agentchat
node_teams -->|"routes turns to"| node_assistant
node_graph_team -->|"specializes"| node_teams
node_extensions -->|"implements model clients"| node_py_model_tools
node_external_caps -->|"implements tools and memory"| node_py_model_tools
node_py_worker -->|"hosts"| node_py_runtime
node_py_worker -->|"speaks"| node_worker_protocol
node_dotnet_runtime -->|"implements"| node_dotnet_contracts
node_dotnet_grpc -->|"implements"| node_dotnet_contracts
node_dotnet_grpc -->|"speaks"| node_worker_protocol
node_gateway -->|"routes"| node_worker_protocol
node_gateway -->|"connects workers"| node_py_worker
node_gateway -->|"connects runtime"| node_dotnet_grpc
node_net_agentchat -->|"uses providers"| node_net_providers
node_studio_ui -->|"REST, WebSocket, MCP"| node_studio
node_studio -->|"configures and runs"| node_teams
node_studio -->|"integrates MCP"| node_external_caps
node_agbench -->|"evaluates agent scenarios"| node_assistant

click node_py_core_api "https://github.com/microsoft/autogen/blob/main/python/packages/autogen-core/src/autogen_core/__init__.py"
click node_py_runtime "https://github.com/microsoft/autogen/blob/main/python/packages/autogen-core/src/autogen_core/_single_threaded_agent_runtime.py"
click node_py_routed_agent "https://github.com/microsoft/autogen/blob/main/python/packages/autogen-core/src/autogen_core/_routed_agent.py"
click node_py_model_tools "https://github.com/microsoft/autogen/blob/main/python/packages/autogen-core/src/autogen_core/models/_model_client.py"
click node_agentchat "https://github.com/microsoft/autogen/blob/main/python/packages/autogen-agentchat/src/autogen_agentchat/messages.py"
click node_assistant "https://github.com/microsoft/autogen/blob/main/python/packages/autogen-agentchat/src/autogen_agentchat/agents/_assistant_agent.py"
click node_teams "https://github.com/microsoft/autogen/blob/main/python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_base_group_chat.py"
click node_graph_team "https://github.com/microsoft/autogen/blob/main/python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_graph/_digraph_group_chat.py"
click node_extensions "https://github.com/microsoft/autogen/blob/main/python/packages/autogen-ext/src/autogen_ext/models/openai/_openai_client.py"
click node_external_caps "https://github.com/microsoft/autogen/blob/main/python/packages/autogen-ext/src/autogen_ext/tools/mcp/_workbench.py"
click node_py_worker "https://github.com/microsoft/autogen/blob/main/python/packages/autogen-ext/src/autogen_ext/runtimes/grpc/_worker_runtime.py"
click node_worker_protocol "https://github.com/microsoft/autogen/blob/main/protos/agent_worker.proto"
click node_dotnet_contracts "https://github.com/microsoft/autogen/blob/main/dotnet/src/Microsoft.AutoGen/Contracts/IAgentRuntime.cs"
click node_dotnet_runtime "https://github.com/microsoft/autogen/blob/main/dotnet/src/Microsoft.AutoGen/Core/InProcessRuntime.cs"
click node_dotnet_grpc "https://github.com/microsoft/autogen/blob/main/dotnet/src/Microsoft.AutoGen/Core.Grpc/GrpcAgentRuntime.cs"
click node_gateway "https://github.com/microsoft/autogen/blob/main/dotnet/src/Microsoft.AutoGen/RuntimeGateway.Grpc/Services/Grpc/GrpcGatewayService.cs"
click node_net_agentchat "https://github.com/microsoft/autogen/blob/main/dotnet/src/AutoGen.Core/Agent/IAgent.cs"
click node_net_providers "https://github.com/microsoft/autogen/blob/main/dotnet/src/AutoGen.OpenAI/Agent/OpenAIChatAgent.cs"
click node_studio "https://github.com/microsoft/autogen/blob/main/python/packages/autogen-studio/autogenstudio/cli.py"
click node_studio_ui "https://github.com/microsoft/autogen/blob/main/python/packages/autogen-studio/frontend/src/components/views/teambuilder/builder/builder.tsx"
click node_agbench "https://github.com/microsoft/autogen/blob/main/python/packages/agbench/src/agbench/cli.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_py_core_api,node_py_runtime,node_py_routed_agent,node_py_model_tools,node_agentchat,node_assistant,node_teams,node_graph_team,node_extensions,node_external_caps toneBlue
class node_py_worker,node_worker_protocol,node_gateway toneAmber
class node_dotnet_contracts,node_dotnet_runtime,node_dotnet_grpc,node_net_agentchat,node_net_providers toneMint
class node_studio,node_studio_ui,node_agbench toneRose
```

## Components

### Python packages

- [Core public API](https://github.com/microsoft/autogen/blob/main/python/packages/autogen-core/src/autogen_core/__init__.py): Python package · Agent contracts, identity, lifecycle, serialization, and cancellation. · `python/packages/autogen-core/src/autogen_core/__init__.py`
- [Single-threaded runtime](https://github.com/microsoft/autogen/blob/main/python/packages/autogen-core/src/autogen_core/_single_threaded_agent_runtime.py): agent runtime · Routes direct and topic messages to registered agent handlers. · `python/packages/autogen-core/src/autogen_core/_single_threaded_agent_runtime.py`
- [Routed agents](https://github.com/microsoft/autogen/blob/main/python/packages/autogen-core/src/autogen_core/_routed_agent.py): handler dispatch · `python/packages/autogen-core/src/autogen_core/_routed_agent.py`
- [Model, context & tools](https://github.com/microsoft/autogen/blob/main/python/packages/autogen-core/src/autogen_core/models/_model_client.py): Core abstractions · Provider-neutral model client, history scope, and callable workbench contracts. · `python/packages/autogen-core/src/autogen_core/models/_model_client.py`
- [AgentChat API](https://github.com/microsoft/autogen/blob/main/python/packages/autogen-agentchat/src/autogen_agentchat/messages.py): conversation layer · User-facing messages, task control, state, and specialized agents. · `python/packages/autogen-agentchat/src/autogen_agentchat/messages.py`
- [Assistant agent](https://github.com/microsoft/autogen/blob/main/python/packages/autogen-agentchat/src/autogen_agentchat/agents/_assistant_agent.py): agent implementation · Drives inference, tool calls, streaming, and task execution. · `python/packages/autogen-agentchat/src/autogen_agentchat/agents/_assistant_agent.py`
- [Teams & group chats](https://github.com/microsoft/autogen/blob/main/python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_base_group_chat.py): orchestration · 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](https://github.com/microsoft/autogen/blob/main/python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_graph/_digraph_group_chat.py): team strategies · `python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_graph/_digraph_group_chat.py`
- [Provider model clients](https://github.com/microsoft/autogen/blob/main/python/packages/autogen-ext/src/autogen_ext/models/openai/_openai_client.py): extension implementations · OpenAI, Azure, Anthropic, local, replay, and other provider adapters. · `python/packages/autogen-ext/src/autogen_ext/models/openai/_openai_client.py`
- [External capability bridges](https://github.com/microsoft/autogen/blob/main/python/packages/autogen-ext/src/autogen_ext/tools/mcp/_workbench.py): trust boundary · 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](https://github.com/microsoft/autogen/blob/main/python/packages/autogen-ext/src/autogen_ext/runtimes/grpc/_worker_runtime.py): distributed worker · Hosts Core agents for cross-process execution. · `python/packages/autogen-ext/src/autogen_ext/runtimes/grpc/_worker_runtime.py`
- [Agent worker protocol](https://github.com/microsoft/autogen/blob/main/protos/agent_worker.proto): gRPC / CloudEvent contract · Shared cross-process worker communication contract. · `protos/agent_worker.proto`
- [Runtime gateway](https://github.com/microsoft/autogen/blob/main/dotnet/src/Microsoft.AutoGen/RuntimeGateway.Grpc/Services/Grpc/GrpcGatewayService.cs): gRPC gateway · Routes worker traffic through the distributed gateway. · `dotnet/src/Microsoft.AutoGen/RuntimeGateway.Grpc/Services/Grpc/GrpcGatewayService.cs`

### .NET libraries

- [.NET runtime contracts](https://github.com/microsoft/autogen/blob/main/dotnet/src/Microsoft.AutoGen/Contracts/IAgentRuntime.cs): runtime interfaces · IAgentRuntime, identities, topics, subscriptions, and dispatch contracts. · `dotnet/src/Microsoft.AutoGen/Contracts/IAgentRuntime.cs`
- [.NET in-process runtime](https://github.com/microsoft/autogen/blob/main/dotnet/src/Microsoft.AutoGen/Core/InProcessRuntime.cs): agent runtime · Local proxy, subscription, and handler dispatch implementation. · `dotnet/src/Microsoft.AutoGen/Core/InProcessRuntime.cs`
- [.NET gRPC runtime](https://github.com/microsoft/autogen/blob/main/dotnet/src/Microsoft.AutoGen/Core.Grpc/GrpcAgentRuntime.cs): distributed runtime · `dotnet/src/Microsoft.AutoGen/Core.Grpc/GrpcAgentRuntime.cs`
- [.NET AgentChat](https://github.com/microsoft/autogen/blob/main/dotnet/src/AutoGen.Core/Agent/IAgent.cs): chat agent library · Separate pluggable chat-agent and group-chat family. · `dotnet/src/AutoGen.Core/Agent/IAgent.cs`
- [.NET provider adapters](https://github.com/microsoft/autogen/blob/main/dotnet/src/AutoGen.OpenAI/Agent/OpenAIChatAgent.cs): provider implementation · `dotnet/src/AutoGen.OpenAI/Agent/OpenAIChatAgent.cs`

### Developer products

- [AutoGen Studio backend](https://github.com/microsoft/autogen/blob/main/python/packages/autogen-studio/autogenstudio/cli.py): CLI and web server · Persists components, teams, sessions, runs, evaluations, and gallery data. · `python/packages/autogen-studio/autogenstudio/cli.py`
- [Studio frontend](https://github.com/microsoft/autogen/blob/main/python/packages/autogen-studio/frontend/src/components/views/teambuilder/builder/builder.tsx): Gatsby / TypeScript UI · No-code team-building interface. · `python/packages/autogen-studio/frontend/src/components/views/teambuilder/builder/builder.tsx`
- [AGBench](https://github.com/microsoft/autogen/blob/main/python/packages/agbench/src/agbench/cli.py): evaluation CLI · Runs containerized benchmark scenarios and processes results. · `python/packages/agbench/src/agbench/cli.py`

## Connections

- 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
