AutoGen Administrator & Developer Guide

1. Architecture Overview

AutoGen is a multi-language framework for building event-driven multi-agent AI systems. It provides a layered architecture: a core runtime handles agent lifecycle, messaging, and subscriptions; a high-level AgentChat layer provides conversational patterns; and an extensions layer plugs in model providers, code executors, tools, and memory stores. The framework ships as separate Python and .NET SDKs that interoperate through gRPC and the CloudEvents messaging standard.

The system is designed around three principles: agents communicate exclusively through messages (no shared mutable state), runtimes can be in-process or distributed without changing agent code, and model backends are pluggable through a uniform ChatCompletionClient interface.

┌─────────────────────────────────────────────────────┐
│                  Applications                        │
│  AutoGen Studio │ AgBench │ Magentic-One │ Custom    │
├─────────────────────────────────────────────────────┤
│              AgentChat Layer (Teams)                 │
│  RoundRobinGroupChat │ SelectorGroupChat │ Graph     │
│  AssistantAgent │ UserProxyAgent │ Conditions         │
├─────────────────────────────────────────────────────┤
│              Core Runtime Layer                      │
│  RoutedAgent │ MessageHandler │ Subscriptions        │
│  InProcessRuntime │ GrpcWorkerAgentRuntime           │
│  TopicId │ AgentId │ CancellationToken               │
├─────────────────────────────────────────────────────┤
│              Extensions Layer                        │
│  Model Clients │ Code Executors │ Tools │ Memory     │
│  MCP Integration │ Auth │ Runtimes                   │
├─────────────────────────────────────────────────────┤
│              Messaging / Transport                   │
│  CloudEvents │ Protobuf │ gRPC │ In-Process Queue    │
└─────────────────────────────────────────────────────┘

Component Inventory

Technology Stack

Data Flow: Agent Message Lifecycle

1. User/System → publishes message to TopicId
2. Runtime → matches TopicId against Subscriptions
3. Runtime → routes message to subscribed Agent(s)
4. Agent → @message_handler processes the message
5. Agent → optionally calls ChatCompletionClient.create()
6. Model → returns CreateResult (content, usage, finish_reason)
7. Agent → optionally publishes response to another TopicId
8. Runtime → repeats steps 2-7 until termination condition met

Note

In distributed mode (gRPC), steps 2-3 cross process boundaries. The AgentRpc service handles OpenChannel (bidirectional streaming of Message payloads) and OpenControlChannel (state management). Agent registration, subscription management, and message routing happen through the gateway.

2. System Requirements

Python SDK

.NET SDK

AutoGen Studio

3. Configuration Reference

OpenAI CreateArguments — Complete Parameter Reference

Azure OpenAI Additional Parameters

Anthropic CreateArguments

Anthropic Bedrock configuration:

Ollama CreateArguments

Azure AI Inference

Important

API keys should never be hardcoded. Use environment variables or secret managers. All model client configuration classes accept SecretStr types from Pydantic for secure handling.

ModelInfo — Required Fields

AutoGen Studio Environment Variables

AutoGen Studio Authentication Configuration

AutoGen Studio supports four authentication providers via YAML configuration:

# GitHub OAuth
type: github
github:
  client_id: "your-github-client-id"
  client_secret: "your-github-secret"
  callback_url: "http://localhost:8081/api/auth/callback"

# Microsoft MSAL
type: msal
msal:
  client_id: "your-msal-client-id"
  client_secret: "your-msal-secret"
  authority: "https://login.microsoftonline.com/your-tenant-id"
  callback_url: "http://localhost:8081/api/auth/callback"

# Firebase
type: firebase
firebase:
  project_id: "your-firebase-project"
  api_key: "your-firebase-api-key"

Auth models:

4. Deployment & Scaling

Python Deployment

AutoGen Studio production deployment:

autogenstudio ui \
    --host 0.0.0.0 \
    --port 8081 \
    --workers 4 \
    --database-uri "sqlite:///path/to/production.db" \
    --auth-config /etc/autogenstudio/auth.yaml

AutoGen Studio API-only deployment (headless):

autogenstudio serve \
    --team /path/to/team.json \
    --host 0.0.0.0 \
    --port 8084 \
    --workers 2

.NET AgentHost Deployment (Distributed Runtime Gateway)

The .NET AgentHost serves as the gRPC gateway for distributed agent systems.

Dockerfile (from dotnet/src/Microsoft.AutoGen/AgentHost/Dockerfile):

FROM mcr.microsoft.com/dotnet/aspnet:8.0 AS base
WORKDIR /app
EXPOSE 5001

FROM mcr.microsoft.com/dotnet/sdk:8.0 AS build
WORKDIR /src
COPY . .
RUN dotnet publish -c Release -o /app/publish

FROM base AS final
WORKDIR /app
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "Microsoft.Autogen.AgentHost.dll"]

Docker Compose example:

services:
  agent-host:
    build:
      context: .
      dockerfile: dotnet/src/Microsoft.AutoGen/AgentHost/Dockerfile
    ports:
      - "5001:5001"

AgBench Deployment

AgBench uses Docker containers for isolated benchmark execution:

FROM mcr.microsoft.com/devcontainers/python:3.11
RUN apt-get update && apt-get install ffmpeg exiftool -y
RUN pip install autogen-core autogen-agentchat autogen-ext pyyaml

Note

Set AUTOGEN_REPO_BASE to the local repository path to enable Docker containers to use the correct agent versions.

.NET Aspire Hosting

For the .NET distributed dev experience, use the .AppHost projects:

cd dotnet/samples/Hello/Hello.AppHost
dotnet run

This starts the Aspire dashboard (typically at https://localhost:15887) with telemetry and logging for all agents.

Scaling Considerations

5. Operations

AutoGen Studio API Endpoints

Tip

AutoGen Studio CORS is configured for local development origins: localhost:8000, 127.0.0.1:8000, localhost:8001, localhost:8081. For production, update the CORS middleware in app.py.

gRPC Service Definition

The AgentRpc service (defined in protos/agent_worker.proto) provides the distributed runtime API:

Protobuf message types:

Monitoring and Health

AutoGen Studio health can be monitored via the FastAPI /docs endpoint (Swagger UI) when --docs is enabled. The .NET Aspire dashboard provides telemetry for distributed .NET agents.

Tip

For production monitoring of AutoGen Studio, check the loguru output. The application logs startup, manager initialization, and shutdown events via logger.info() / logger.error().

Backup Procedures

6. Performance

Model Client Caching

Use ChatCompletionCache to avoid redundant API calls:

from autogen_ext.models.cache import ChatCompletionCache
from autogen_ext.cache_store import DiskCacheStore, RedisCacheStore

# Disk cache
cache = ChatCompletionCache(
    client=model_client,
    cache_store=DiskCacheStore(cache_dir=".cache"),
)

# Redis cache (for shared caching across workers)
cache = ChatCompletionCache(
    client=model_client,
    cache_store=RedisCacheStore(redis_url="redis://localhost:6379"),
)

The cache is keyed on the full message sequence, tools, and create arguments. Both streaming and non-streaming calls are cached, and cached streaming results correctly replay as streams.

Token Counting

All ChatCompletionClient implementations provide token counting:

token_count = client.count_tokens(messages)
remaining = client.remaining_tokens(messages)

Usage tracking per request:

result = await client.create(messages)
print(f"Prompt: {result.usage.prompt_tokens}, Completion: {result.usage.completion_tokens}")

Performance Tuning

7. Security

Code Execution Security

Caution

The LocalCommandLineCodeExecutor executes LLM-generated code directly on the host machine without any sandboxing (issue #7462). This is a critical security risk in production.

Recommended code executors by security level:

Authentication Architecture (Studio)

AutoGen Studio implements a layered auth system:

1. AuthMiddleware — FastAPI middleware that intercepts every request, validates tokens, and injects the User object into request.state
2. WebSocketAuthMiddleware — Separate handler for WebSocket connections
3. AuthManager — Creates and validates JWT tokens
4. AuthProvider (abstract) — Pluggable provider interface with implementations for GitHub, MSAL, Firebase, and NoAuth
5. NoAuthProvider — Default provider that creates anonymous users (for local development)

Auth exceptions:

Warning

The default NoAuthProvider creates anonymous users with full access. Always configure a real auth provider before exposing AutoGen Studio to a network.

.NET Middleware Security

The .NET SDK uses a middleware pipeline for model interaction. Each provider (OpenAI, Anthropic, Gemini, Mistral, etc.) implements middleware that processes messages before and after model calls. This is the extension point for:

• Request/response logging
• Content filtering
• Token usage tracking
• Error handling and retry logic

API Key Management

• Python model clients accept API keys via constructor parameters or environment variables
• .NET model clients use constructor parameters
• AutoGen Studio stores temporary environment variables in ~/.autogenstudio/temp_env_vars.env
• gRPC channels should use TLS in production

Important

The temp_env_vars.env file is created by the AutoGen Studio CLI to share configuration with uvicorn workers. It may contain sensitive values. Ensure file permissions are restricted.

MCP Security

MCP server connections support three transport types:

8. Developer Internals

Repository Structure

microsoft/autogen/
├── protos/                              # Shared Protobuf definitions
│   ├── agent_worker.proto               # Agent RPC service, messages, subscriptions
│   └── cloudevent.proto                  # CloudEvent format definition
├── python/
│   ├── packages/
│   │   ├── autogen-core/src/autogen_core/
│   │   │   ├── models/                  # ChatCompletionClient, ModelFamily, message types
│   │   │   ├── tools/                   # BaseTool, ToolSchema
│   │   │   ├── utils/                   # JSON-to-Pydantic, load_json
│   │   │   ├── code_executor/           # Code executor interface
│   │   │   ├── memory/                  # Memory interface
│   │   │   ├── model_context/           # Model context management
│   │   │   ├── tool_agent/              # Tool-executing agent
│   │   │   └── _telemetry/              # OpenTelemetry integration
│   │   ├── autogen-agentchat/src/autogen_agentchat/
│   │   │   ├── agents/                  # AssistantAgent, UserProxyAgent
│   │   │   ├── teams/_group_chat/       # RoundRobinGroupChat, SelectorGroupChat
│   │   │   ├── conditions/             # Termination conditions
│   │   │   ├── tools/                  # Agent-level tool wrappers
│   │   │   ├── ui/                     # Console output formatter
│   │   │   ├── state/                  # State serialization
│   │   │   └── base/                   # Base classes
│   │   ├── autogen-ext/src/autogen_ext/
│   │   │   ├── models/                 # OpenAI, Anthropic, Azure, Ollama, Gemini, LLama, SK adapters
│   │   │   ├── code_executors/         # Docker, Jupyter, Azure, local
│   │   │   ├── tools/                  # MCP, HTTP, LangChain, GraphRAG, Azure, Semantic Kernel
│   │   │   ├── agents/                 # WebSurfer, FileSurfer, Magentic-One, Azure, OpenAI
│   │   │   ├── memory/                 # ChromaDB, Redis, Canvas, Mem0
│   │   │   ├── runtimes/grpc/          # GrpcWorkerAgentRuntime
│   │   │   ├── cache_store/            # Disk, Redis cache stores
│   │   │   ├── auth/                   # Azure auth provider
│   │   │   ├── teams/                  # Team extensions
│   │   │   ├── ui/                     # UI extensions
│   │   │   └── experimental/           # Task-centric memory
│   │   ├── autogen-studio/
│   │   │   ├── autogenstudio/
│   │   │   │   ├── web/                # FastAPI app, routes, auth, config
│   │   │   │   ├── database/           # SQLite DatabaseManager
│   │   │   │   ├── datamodel/          # Pydantic models
│   │   │   │   ├── teammanager/        # Team execution management
│   │   │   │   ├── gallery/            # Default component gallery
│   │   │   │   ├── validation/         # Component validation
│   │   │   │   ├── mcp/                # MCP client/callbacks
│   │   │   │   ├── eval/               # Evaluation utilities
│   │   │   │   ├── lite/               # Lightweight mode
│   │   │   │   └── cli.py              # Typer CLI
│   │   │   └── frontend/              # Gatsby/React SPA
│   │   ├── agbench/                    # Benchmark runner
│   │   ├── magentic-one-cli/           # Magentic-One CLI
│   │   ├── pyautogen/                  # Legacy compatibility
│   │   └── component-schema-gen/       # Schema generator
│   ├── samples/                        # Example applications
│   ├── docs/                           # Sphinx documentation
│   └── templates/                      # Cookiecutter package template
├── dotnet/
│   ├── src/
│   │   ├── Microsoft.AutoGen/
│   │   │   ├── Core/                   # AgentsApp, BaseAgent, runtime
│   │   │   ├── Contracts/              # IAgentRuntime, IHostableAgent interfaces
│   │   │   ├── Agents/                 # Agent implementations
│   │   │   ├── AgentHost/              # gRPC gateway Dockerfile
│   │   │   ├── AgentChat/              # .NET AgentChat layer
│   │   │   ├── RuntimeGateway.Grpc/    # Orleans-backed gRPC gateway
│   │   │   ├── Core.Grpc/             # gRPC runtime implementation
│   │   │   └── Extensions/            # Aspire, MEAI, SK integration
│   │   ├── AutoGen.Core/              # Legacy core (middleware, orchestrator)
│   │   ├── AutoGen.OpenAI/            # OpenAI middleware + agents
│   │   ├── AutoGen.Anthropic/         # Anthropic middleware + agents
│   │   ├── AutoGen.Gemini/            # Gemini middleware + agents
│   │   ├── AutoGen.Mistral/           # Mistral middleware
│   │   ├── AutoGen.SemanticKernel/    # SK middleware
│   │   ├── AutoGen.AzureAIInference/  # Azure AI middleware
│   │   ├── AutoGen.Ollama/            # Ollama agent + middleware
│   │   ├── AutoGen.LMStudio/          # LM Studio agent
│   │   ├── AutoGen.SourceGenerator/   # Source generator
│   │   ├── AutoGen.WebAPI/            # OpenAI-compatible API
│   │   ├── AutoGen.DotnetInteractive/ # Code execution
│   │   └── AutoGen/                   # Legacy API surface
│   ├── samples/                       # .NET examples
│   ├── test/                          # Test projects
│   └── website/                       # DocFX documentation site
└── docs/                              # Shared documentation

Architecture Deep Dive

Core Runtime (Python)

The autogen-core package defines the fundamental abstractions:

• RoutedAgent — Base class for all agents. Uses the @message_handler decorator to register typed message handlers. Each agent has an AgentId (type + key) and belongs to a runtime.
• IAgentRuntime — Interface for runtimes that host agents. Supports register_agent_factory, add_subscription, publish_message, send_message.
• InProcessRuntime — Single-process runtime with an in-memory message queue. Configurable DeliverToSelf flag.
• TopicId — Typed topic identifier (type + source). Agents subscribe to topics via TypeSubscription or TypePrefixSubscription.
• CancellationToken — Cooperative cancellation for async operations.
• ComponentBase — Mixin that enables load_component() / dump_component() for JSON serialization of configuration.

Core Runtime (.NET)

The .NET SDK mirrors the Python architecture:

• BaseAgent — Abstract base class for agents. Uses IHandle<T> interface for typed message handling.
• AgentsApp / AgentsAppBuilder — Application host with dependency injection, agent registration, and lifecycle management.
• InProcessRuntime — In-memory runtime with configurable DeliverToSelf.
• AgentRuntimeExtensions — Extension methods for RegisterAgentTypeAsync, RegisterImplicitAgentSubscriptionsAsync.
• TypeSubscriptionAttribute / TypePrefixSubscriptionAttribute — Declarative subscription binding via attributes.
• ReflectionHelper — Discovers BaseAgent subclasses for auto-registration via AddAgentsFromAssemblies().

AgentChat Layer

The autogen-agentchat package provides high-level team patterns:

• Teams run conversations according to a strategy:
  • RoundRobinGroupChat — Cycles through participants in order
  • SelectorGroupChat — Uses an LLM to select the next speaker from participant descriptions
  • Graph-based teams (in _graph/) — Allow custom conversation flow graphs
  • Magentic-One teams (in _magentic_one/) — Orchestrated multi-agent web task system
• Agents receive messages and produce responses:
  • AssistantAgent — LLM-backed agent with system message and optional tools
  • UserProxyAgent — Represents human input
• Conditions control conversation termination:
  • MaxMessageTermination, TextMentionTermination, StopMessageTermination

Message Types (Python Core)

LLMMessage is the union type: SystemMessage | UserMessage | AssistantMessage | FunctionExecutionResultMessage.

CloudEvents Messaging

All inter-agent messages are wrapped in the CloudEvents specification:

message CloudEvent {
    string id = 1;
    string source = 2;
    string spec_version = 3;
    string type = 4;
    map<string, CloudEventAttributeValue> attributes = 5;
    oneof data {
        bytes binary_data = 6;
        string text_data = 7;
        google.protobuf.Any proto_data = 8;
    }
}

This enables cross-language, cross-process messaging. Python agents serialize to CloudEvents via the gRPC runtime, and .NET agents deserialize them through the gateway.

.NET Middleware Architecture

The .NET SDK uses a middleware pipeline pattern for model interactions. Each provider package includes middleware classes that can intercept and transform messages:

.NET Source Generator

The AutoGen.SourceGenerator package provides compile-time code generation for type-safe function definitions:

public partial class MyFunctions
{
    /// <summary>Add two numbers.</summary>
    /// <param name="a">The first number.</param>
    /// <param name="b">The second number.</param>
    [Function]
    public Task<string> AddAsync(int a, int b)
    {
        return Task.FromResult($"{a} + {b} = {a + b}");
    }
}

The generator produces:

• A schema class (AddAsyncSchema) with properties matching parameters
• A wrapper method (AddAsyncWrapper) that deserializes JSON arguments
• A FunctionDefinition property (AddAsyncFunction) with name, description, and JSON Schema parameters

Requirements: GenerateDocumentationFile must be true in the project file, and the class must be partial and public.

AutoGen Studio Architecture

AutoGen Studio is a full-stack web application:

Backend (autogenstudio/web/):

• app.py — FastAPI application with lifespan management, CORS, auth middleware
• routes/ — API routes: teams, sessions, runs, gallery, settings, validation, MCP, WebSocket
• auth/ — Pluggable authentication (GitHub OAuth, MSAL, Firebase, NoAuth)
• deps.py — Dependency injection for DatabaseManager, ConnectionManager, TeamManager
• config.py — Settings management

Frontend (frontend/):

• Gatsby 5 + React 18 SPA
• Ant Design component library
• Monaco Editor for code editing
• React Flow (@xyflow/react) for visual team building
• Zustand for state management
• Tailwind CSS for styling

Data flow:

1. User creates a Team (JSON configuration of agents, models, conditions)
2. User creates a Session (conversation context)
3. User sends a task → backend creates a Run
4. TeamManager executes the team configuration
5. Messages stream back via WebSocket
6. Results persist in SQLite database

Experimental: Task-Centric Memory

The autogen_ext.experimental.task_centric_memory module provides:

• Apprentice — Agent that learns from task demonstrations and applies solutions to new tasks
• Teachability — Memory implementation that stores task-solution pairs
• ChatCompletionClientRecorder — Records and replays model interactions for testing
• Grader — Evaluates agent performance on tasks
• PageLogger — Hierarchical HTML logging system

Note

The task-centric memory module is in experimental/ and its API may change. It implements a learn-by-demonstration pattern where the Apprentice can be trained on tasks and then autonomously apply learned solutions.

Code Patterns and Conventions

Python:

• Async-first: all agent handlers and model calls are async
• Pydantic v2 for all data models and configuration
• Type hints enforced via pyright and mypy
• @message_handler decorator for typed message routing
• ComponentBase mixin for serializable configuration
• Package extras for optional dependencies (e.g., autogen-ext[openai])

Build system:

• uv for dependency management and virtual environments
• poethepoet (poe) for task running (poe fmt, poe lint, poe mypy, poe pyright)
• ruff for formatting and linting
• shared_tasks.toml defines common tasks across packages

.NET:

• C# 12 with primary constructors
• IHostableAgent + IHandle<T> for type-safe message handling
• Attribute-based subscriptions ([TypeSubscription], [TypePrefixSubscription])
• Middleware pipeline for model interaction extensibility
• AgentsAppBuilder fluent API for application construction
• NuGet packages with centralized version management (Directory.Packages.props)

Testing Strategy

Python testing:

• pytest with asyncio support
• Extensive mock-based model client tests (in autogen-ext/tests/models/)
• Tests cover: all model providers (OpenAI, Anthropic, Azure AI, Ollama, LLama.cpp, SK), caching, streaming, tool calling, structured output, cancellation, multimodal input, thinking mode
• ChatCompletionClientRecorder for deterministic test replay
• pyright and mypy for static type checking

.NET testing:

• xUnit test framework
• Integration tests with Aspire AppHost (Microsoft.AutoGen.Integration.Tests)
• Provider-specific tests (OpenAI, Anthropic, Gemini, Mistral, Ollama, SK, Azure AI)
• Source generator approval tests (snapshot testing)
• gRPC tests for distributed runtime

Contributing

1. Clone and setup:

git clone https://github.com/microsoft/autogen.git
cd autogen/python
uv sync
source .venv/bin/activate

2. Run quality checks:

poe fmt          # Format with ruff
poe lint         # Lint with ruff
poe mypy         # Type check with mypy
poe pyright      # Type check with pyright

3. Run tests for a specific package:

cd packages/autogen-core
poe test

4. Build documentation:

poe docs-build   # Build Sphinx docs
poe docs-serve   # Serve locally

5. Check markdown code blocks (CI tool):

python check_md_code_blocks.py docs/**/*.md

6. Create a new package (using the cookiecutter template):

cd python/templates/new-package
cookiecutter .

9. Integration Points

Cross-Language Agent Communication

Python and .NET agents communicate through the shared gRPC AgentRpc service:

Python Agent ←→ GrpcWorkerAgentRuntime ←→ gRPC Channel ←→ AgentHost (.NET) ←→ .NET Agent

Both sides use the same Protobuf definitions (protos/agent_worker.proto, protos/cloudevent.proto). The C# namespace is Microsoft.AutoGen.Protobuf / Microsoft.AutoGen.Contracts.

Semantic Kernel Integration

The AutoGen.SemanticKernel package (.NET) and autogen_ext.models.semantic_kernel (Python) provide bidirectional integration:

• Use Semantic Kernel plugins as AutoGen tools
• Use AutoGen agents within SK orchestrations
• The SemanticKernelChatCompletionAdapter wraps SK chat completion services as AutoGen ChatCompletionClient

MCP (Model Context Protocol) Integration

AutoGen's MCP integration (autogen_ext.tools.mcp) supports:

Memory Stores

Web Framework Integration

AutoGen includes sample integrations with web frameworks:

The FastAPI streaming sample implements a full OpenAI-compatible chat completions endpoint with agent handoffs:

@app.post("/chat/completions")
async def chat_completions_stream(request: Request):
    # Routes to agents, streams responses as SSE

LM Studio Integration (.NET)

var lmStudioConfig = new LMStudioConfig("localhost", 5000);
var agent = new LMStudioAgent(
    name: "agent",
    systemMessage: "You are a helpful assistant.",
    lmStudioConfig: lmStudioConfig
).RegisterPrintMessage();