# 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.

```text
┌─────────────────────────────────────────────────────┐
│                  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

| Component | Path | Role |
|---|---|---|
| `autogen-core` | `python/packages/autogen-core/` | Core runtime: agents, messaging, subscriptions, tools, model interfaces |
| `autogen-agentchat` | `python/packages/autogen-agentchat/` | High-level conversational agents and team patterns |
| `autogen-ext` | `python/packages/autogen-ext/` | Extensions: model clients, code executors, MCP tools, memory, runtimes |
| `autogen-studio` | `python/packages/autogen-studio/` | Web UI for visual agent team building (FastAPI + Gatsby/React) |
| `agbench` | `python/packages/agbench/` | Agent benchmarking tool (GAIA, HumanEval) |
| `magentic-one-cli` | `python/packages/magentic-one-cli/` | CLI for the Magentic-One multi-agent web task system |
| `pyautogen` | `python/packages/pyautogen/` | Legacy compatibility shim for v0.2 API |
| `component-schema-gen` | `python/packages/component-schema-gen/` | JSON Schema generator for AutoGen components |
| `Microsoft.AutoGen.Core` | `dotnet/src/Microsoft.AutoGen/Core/` | .NET core runtime: `AgentsApp`, `BaseAgent`, subscriptions |
| `Microsoft.AutoGen.Contracts` | `dotnet/src/Microsoft.AutoGen/Contracts/` | .NET shared interfaces and message types |
| `AutoGen.OpenAI` | `dotnet/src/AutoGen.OpenAI/` | .NET OpenAI model client with middleware pipeline |
| `AutoGen.Anthropic` | `dotnet/src/AutoGen.Anthropic/` | .NET Anthropic model client |
| `AutoGen.Gemini` | `dotnet/src/AutoGen.Gemini/` | .NET Gemini model client |
| `AutoGen.Mistral` | `dotnet/src/AutoGen.Mistral/` | .NET Mistral model client |
| `AutoGen.SemanticKernel` | `dotnet/src/AutoGen.SemanticKernel/` | .NET Semantic Kernel integration |
| `AutoGen.AzureAIInference` | `dotnet/src/AutoGen.AzureAIInference/` | .NET Azure AI Inference client |
| `AutoGen.Ollama` | `dotnet/src/AutoGen.Ollama/` | .NET Ollama local model client |
| `AutoGen.LMStudio` | `dotnet/src/AutoGen.LMStudio/` | .NET LM Studio local server client |
| `AutoGen.Core` | `dotnet/src/AutoGen.Core/` | .NET legacy core (middleware, orchestrator, functions) |
| `AutoGen.SourceGenerator` | `dotnet/src/AutoGen.SourceGenerator/` | .NET source generator for type-safe function definitions |
| `AutoGen.WebAPI` | `dotnet/src/AutoGen.WebAPI/` | .NET OpenAI-compatible Web API wrapper |
| `AutoGen.DotnetInteractive` | `dotnet/src/AutoGen.DotnetInteractive/` | .NET Interactive code execution |
| `AgentHost` | `dotnet/src/Microsoft.AutoGen/AgentHost/` | .NET gRPC gateway service for distributed agents |
| `RuntimeGateway.Grpc` | `dotnet/src/Microsoft.AutoGen/RuntimeGateway.Grpc/` | gRPC runtime gateway with Orleans backend |
| `protos` | `protos/` | Shared Protobuf definitions for cross-language messaging |

### Technology Stack

| Layer | Technology |
|---|---|
| Python runtime | Python 3.10+, asyncio, Pydantic v2 |
| .NET runtime | .NET 8.0+, C# 12, Microsoft.Extensions.Hosting |
| Messaging | CloudEvents v1, Protocol Buffers, gRPC |
| Web UI (Studio) | FastAPI, Gatsby 5, React 18, Ant Design, Tailwind CSS, Monaco Editor |
| Frontend state | Zustand, React Flow (`@xyflow/react`) |
| Model SDKs | openai, anthropic, ollama, azure-ai-inference, google-generativeai, llama-cpp-python |
| Code execution | Docker, Jupyter, Azure Container Instances |
| Auth | GitHub OAuth, Microsoft MSAL, Firebase |
| Database (Studio) | SQLite (via DatabaseManager) |
| Build tools | uv, poe (poethepoet), ruff, pyright, mypy |
| .NET build | MSBuild, NuGet, .NET Aspire |
| Documentation | Sphinx, MyST parser, pydata-sphinx-theme |

### Data Flow: Agent Message Lifecycle

```text
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

| Requirement | Minimum | Recommended |
|---|---|---|
| Python | 3.10 | 3.12+ |
| OS | Windows 10, macOS 12, Ubuntu 20.04 | Latest LTS |
| Memory | 512 MB | 2+ GB (varies by model and concurrency) |
| Disk | 100 MB (packages) | 500 MB+ (with Docker images) |
| Docker | 20.10+ (for sandboxed code execution) | Docker Desktop latest |
| Network | Required for cloud model providers | Low-latency connection recommended |

### .NET SDK

| Requirement | Minimum | Recommended |
|---|---|---|
| .NET SDK | 8.0 | 8.0 latest |
| OS | Windows 10, macOS 12, Ubuntu 20.04 | Latest LTS |
| Docker | 20.10+ (for AgentHost gateway) | Docker Desktop latest |
| .NET Aspire | Optional (for distributed dev experience) | Latest |

### AutoGen Studio

| Requirement | Value |
|---|---|
| Python | 3.10+ |
| Default port | 8081 (UI), 8084 (serve), 8080 (lite) |
| Browser | Modern browser (Chrome, Firefox, Edge, Safari) |
| Database | SQLite (auto-created in `~/.autogenstudio`) |

---

## 3. Configuration Reference

### OpenAI `CreateArguments` — Complete Parameter Reference

| Parameter | Type | Default | Description |
|---|---|---|---|
| `model` | `str` | Required | Model identifier (e.g., `gpt-4o`, `gpt-4o-mini`) |
| `api_key` | `str` | From env | API key (falls back to `OPENAI_API_KEY`) |
| `temperature` | `float` | `None` | Sampling temperature (0.0–2.0) |
| `top_p` | `float` | `None` | Nucleus sampling probability |
| `max_tokens` | `int` | `None` | Maximum tokens to generate |
| `frequency_penalty` | `float` | `None` | Penalize frequent tokens (-2.0–2.0) |
| `presence_penalty` | `float` | `None` | Penalize present tokens (-2.0–2.0) |
| `stop` | `str` or `list[str]` | `None` | Stop sequences |
| `seed` | `int` | `None` | Deterministic sampling seed |
| `n` | `int` | `None` | Number of completions to generate |
| `user` | `str` | `None` | End-user identifier for abuse monitoring |
| `timeout` | `float` | `None` | Request timeout in seconds |
| `max_retries` | `int` | Provider default | Maximum retry attempts |
| `parallel_tool_calls` | `bool` | `None` | Allow parallel function calls |
| `reasoning_effort` | `str` | `None` | `minimal`, `low`, `medium`, `high` (o1/o3 models only) |
| `response_format` | `dict` | `None` | `text`, `json_object`, or `json_schema` with schema |
| `stream_options` | `dict` | `None` | `{"include_usage": true}` for streaming token usage |
| `add_name_prefixes` | `bool` | `False` | Prepend agent name to messages |
| `include_name_in_message` | `bool` | `True` | Include `name` field in user messages (set `False` for providers that reject it) |
| `default_headers` | `dict` | `None` | Custom HTTP headers for API requests |

### Azure OpenAI Additional Parameters

| Parameter | Type | Description |
|---|---|---|
| `azure_deployment` | `str` | Azure deployment name |
| `azure_endpoint` | `str` | Azure resource endpoint URL |
| `azure_ad_token_provider` | `callable` | Azure AD token provider function |

### Anthropic `CreateArguments`

| Parameter | Type | Default | Description |
|---|---|---|---|
| `model` | `str` | Required | Model identifier (e.g., `claude-3-5-sonnet-20241022`) |
| `api_key` | `str` | From env | API key (falls back to `ANTHROPIC_API_KEY`) |
| `max_tokens` | `int` | `None` | Maximum output tokens |
| `temperature` | `float` | `None` | Sampling temperature |
| `top_p` | `float` | `None` | Nucleus sampling |
| `top_k` | `int` | `None` | Top-k sampling |
| `stop_sequences` | `list[str]` | `None` | Stop sequences |
| `thinking` | `dict` | `None` | Extended thinking config: `{"type": "enabled", "budget_tokens": N}` |

**Anthropic Bedrock configuration:**

| Parameter | Type | Description |
|---|---|---|
| `aws_access_key` | `str` | AWS access key ID (env: `AWS_ACCESS_KEY_ID`) |
| `aws_secret_key` | `str` | AWS secret access key (env: `AWS_SECRET_ACCESS_KEY`) |
| `aws_region` | `str` | AWS region (env: `AWS_REGION`) |
| `aws_session_token` | `str` | AWS session token (env: `AWS_SESSION_TOKEN`) |

### Ollama `CreateArguments`

| Parameter | Type | Default | Description |
|---|---|---|---|
| `model` | `str` | Required | Model name (e.g., `llama3.1`) |
| `host` | `str` | `http://localhost:11434` | Ollama server address |

### Azure AI Inference

| Parameter | Type | Description |
|---|---|---|
| `endpoint` | `str` | Azure AI endpoint (env: `AZURE_AI_INFERENCE_ENDPOINT`) |
| `credential` | `str` | API key (env: `AZURE_AI_INFERENCE_API_KEY`) |

> [!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

| Field | Type | Required | Description |
|---|---|---|---|
| `vision` | `bool` | Yes | Image input support |
| `function_calling` | `bool` | Yes | Tool/function call support |
| `json_output` | `bool` | Yes | JSON mode support |
| `family` | `str` | Yes (v0.4.7+) | Model family constant |
| `structured_output` | `bool` | Warning if missing | Structured output schema support |
| `multiple_system_messages` | `bool` | No | Multi-system-message support |

### AutoGen Studio Environment Variables

| Variable | Default | Description |
|---|---|---|
| `AUTOGENSTUDIO_HOST` | `127.0.0.1` | Server bind address |
| `AUTOGENSTUDIO_PORT` | `8081` | Server port |
| `AUTOGENSTUDIO_API_DOCS` | `true` | Enable FastAPI docs |
| `AUTOGENSTUDIO_APPDIR` | `~/.autogenstudio` | Application data directory |
| `AUTOGENSTUDIO_DATABASE_URI` | `None` | Database connection URI |
| `AUTOGENSTUDIO_AUTH_CONFIG` | `None` | Auth configuration YAML path |
| `AUTOGENSTUDIO_UPGRADE_DATABASE` | `None` | Set to `1` to upgrade DB schema |
| `AUTOGENSTUDIO_TEAM_FILE` | `None` | Team JSON path (serve mode) |

### AutoGen Studio Authentication Configuration

AutoGen Studio supports four authentication providers via YAML configuration:

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

```yaml
# 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"
```

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

**Auth models:**

| Class | Fields |
|---|---|
| `GithubAuthConfig` | `client_id`, `client_secret`, `callback_url` |
| `MSALAuthConfig` | `client_id`, `client_secret`, `authority`, `callback_url` |
| `FirebaseAuthConfig` | `project_id`, `api_key` |
| `AuthConfig` | `type` (github/msal/firebase/none), provider-specific config |

---

## 4. Deployment & Scaling

### Python Deployment

**AutoGen Studio production deployment:**

```bash
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):**

```bash
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`):

```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:**

```yaml
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:

```dockerfile
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:

```bash
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

| Dimension | Approach |
|---|---|
| Concurrent users (Studio) | Increase `--workers` (uvicorn workers) |
| Agent throughput | Deploy multiple `GrpcWorkerAgentRuntime` processes behind the gateway |
| Model rate limits | Use `ChatCompletionCache` or implement client-side retry with backoff |
| Cross-language agents | Deploy .NET AgentHost as central gRPC gateway |
| Benchmark parallelism | Run multiple `autogenbench run` instances with different task files |

---

## 5. Operations

### AutoGen Studio API Endpoints

| Method | Path | Auth | Purpose |
|---|---|---|---|
| GET | `/auth/login-url` | None | Get OAuth login URL |
| GET | `/auth/callback` | None | OAuth callback handler |
| POST | `/auth/callback-handler` | None | Token exchange handler |
| GET | `/auth/me` | Token | Get current user info |
| GET | `/auth/type` | None | Get authentication type |
| GET | `/teams/` | Token | List teams |
| GET | `/teams/{team_id}` | Token | Get team details |
| POST | `/teams/` | Token | Create team |
| DELETE | `/teams/{team_id}` | Token | Delete team |
| GET | `/sessions/` | Token | List sessions |
| GET | `/sessions/{session_id}` | Token | Get session |
| POST | `/sessions/` | Token | Create session |
| PUT | `/sessions/{session_id}` | Token | Update session |
| DELETE | `/sessions/{session_id}` | Token | Delete session |
| GET | `/sessions/{session_id}/runs` | Token | List session runs |
| POST | `/runs/` | Token | Create a run |
| GET | `/runs/{run_id}` | Token | Get run details |
| GET | `/runs/{run_id}/messages` | Token | Get run messages |
| GET | `/gallery/` | Token | List gallery entries |
| GET | `/gallery/{gallery_id}` | Token | Get gallery entry |
| POST | `/gallery/` | Token | Create gallery entry |
| PUT | `/gallery/{gallery_id}` | Token | Update gallery entry |
| DELETE | `/gallery/{gallery_id}` | Token | Delete gallery entry |
| GET | `/settings/` | Token | Get settings |
| PUT | `/settings/` | Token | Update settings |
| POST | `/validation/` | Token | Validate component |
| POST | `/validation/test` | Token | Test component |
| POST | `/mcp/ws/connect` | Token | Create MCP WebSocket connection |
| GET | `/mcp/ws/status/{session_id}` | Token | Get MCP session status |

> [!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:

| RPC | Type | Description |
|---|---|---|
| `OpenChannel` | Bidirectional streaming | Main message channel (`Message` → `Message`) |
| `OpenControlChannel` | Bidirectional streaming | State management (`ControlMessage` → `ControlMessage`) |
| `RegisterAgent` | Unary | Register an agent type with the gateway |
| `AddSubscription` | Unary | Add a topic subscription |
| `RemoveSubscription` | Unary | Remove a topic subscription |
| `GetSubscriptions` | Unary | List all subscriptions |

**Protobuf message types:**

| Message | Fields | Purpose |
|---|---|---|
| `AgentId` | `type`, `key` | Unique agent identifier |
| `Payload` | `data_type`, `data_content_type`, `data` | Serialized message payload |
| `RpcRequest` | `request_id`, `source`, `target`, `method`, `payload`, `metadata` | Direct agent-to-agent RPC |
| `RpcResponse` | `request_id`, `payload`, `error`, `metadata` | RPC response |
| `Message` | oneof: `request`, `response`, `cloudEvent` | Envelope for all channel messages |
| `ControlMessage` | `rpc_id`, `destination`, `respond_to`, `rpcMessage` | State save/load operations |
| `SaveStateRequest/Response` | `agentId`, `state`, `error` | Agent state persistence |
| `LoadStateRequest/Response` | `agentId`, `state`, `error` | Agent state recovery |
| `TypeSubscription` | `topic_type`, `agent_type` | Exact topic match subscription |
| `TypePrefixSubscription` | `topic_type_prefix`, `agent_type` | Prefix-based topic subscription |

### 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

| Component | What to backup | Location |
|---|---|---|
| AutoGen Studio data | SQLite database | `~/.autogenstudio/` (or `AUTOGENSTUDIO_APPDIR`) |
| Team configurations | Team JSON files | Application-specific |
| Agent state (.NET) | State store | `SaveStateRequest` / `LoadStateRequest` via gRPC |

---

## 6. Performance

### Model Client Caching

Use `ChatCompletionCache` to avoid redundant API calls:

```python
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:

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

Usage tracking per request:

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

### Performance Tuning

| Setting | Impact | Recommendation |
|---|---|---|
| `max_tokens` | Limits output length | Set to expected max to reduce latency and cost |
| `temperature=0` | Deterministic output | Use for reproducible agent behavior |
| `reasoning_effort` | Controls o1/o3 thinking depth | Use `minimal` or `low` for routine tasks |
| `parallel_tool_calls=True` | Allows concurrent function calls | Enable for agents with multiple independent tools |
| `stream_options.include_usage=True` | Token usage in streaming | Enable for monitoring; slight overhead |
| Studio `--workers` | Concurrent request handling | Set to CPU count for production |

---

## 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:**

| Executor | Isolation | Use Case |
|---|---|---|
| `DockerCommandLineCodeExecutor` | Container sandbox | Production code execution |
| `AzureContainerCodeExecutor` | Cloud sandbox | Enterprise/cloud deployments |
| `DockerJupyterCodeExecutor` | Container + Jupyter | Interactive notebook execution |
| `LocalCommandLineCodeExecutor` | None | Local development only |

### 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:**

| Exception | HTTP Status | When |
|---|---|---|
| `AuthException` | 401 | Generic auth failure |
| `InvalidTokenException` | 401 | Token validation failed |
| `MissingTokenException` | 401 | No token provided |
| `ProviderAuthException` | 401 | Provider-specific failure |
| `ConfigurationException` | 500 | Auth system misconfigured |
| `ForbiddenException` | 403 | Insufficient permissions |

> [!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:

| Transport | Class | Security Considerations |
|---|---|---|
| Stdio | `StdioServerParams` | Runs server as subprocess; inherits host permissions |
| SSE | `SseServerParams` | HTTP-based; use TLS in production |
| Streamable HTTP | `StreamableHttpServerParams` | HTTP-based; use TLS in production |

---

## 8. Developer Internals

### Repository Structure

```text
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)

| Type | Purpose | Key Fields |
|---|---|---|
| `SystemMessage` | Developer instructions to the model | `content: str` |
| `UserMessage` | User input or agent-forwarded content | `content: str \| list[str \| Image]`, `source: str` |
| `AssistantMessage` | Model-generated response | `content: str \| list[FunctionCall]`, `thought: str \| None`, `source: str` |
| `FunctionExecutionResult` | Output from a tool call | `content: str`, `name: str`, `call_id: str`, `is_error: bool` |
| `FunctionExecutionResultMessage` | Collection of tool results | `content: list[FunctionExecutionResult]` |
| `CreateResult` | Full model response | `finish_reason`, `content`, `usage: RequestUsage`, `cached: bool`, `thought: str \| None` |
| `RequestUsage` | Token counts | `prompt_tokens: int`, `completion_tokens: int` |

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

#### CloudEvents Messaging

All inter-agent messages are wrapped in the [CloudEvents](https://cloudevents.io) specification:

```protobuf
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:

| Package | Middleware | Purpose |
|---|---|---|
| `AutoGen.Core` | `FunctionCallMiddleware`, `PrintMessageMiddleware` | Function handling, console output |
| `AutoGen.OpenAI` | `OpenAIChatRequestMessageConnector` | Message format conversion |
| `AutoGen.Anthropic` | `AnthropicClientAgent` middleware | Anthropic-specific message handling |
| `AutoGen.Gemini` | `GeminiChatAgent` middleware | Gemini message format conversion |
| `AutoGen.Mistral` | `MistralChatAgent` middleware | Mistral message handling |
| `AutoGen.SemanticKernel` | `SemanticKernelChatMessageContentConnector` | SK integration |
| `AutoGen.AzureAIInference` | `AzureAIInferenceChatRequestMessageConnector` | Azure AI format conversion |

### .NET Source Generator

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

```csharp
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:
```bash
git clone https://github.com/microsoft/autogen.git
cd autogen/python
uv sync
source .venv/bin/activate
```

2. Run quality checks:
```bash
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:
```bash
cd packages/autogen-core
poe test
```

4. Build documentation:
```bash
poe docs-build   # Build Sphinx docs
poe docs-serve   # Serve locally
```

5. Check markdown code blocks (CI tool):
```bash
python check_md_code_blocks.py docs/**/*.md
```

6. Create a new package (using the cookiecutter template):
```bash
cd python/templates/new-package
cookiecutter .
```

---

## 9. Integration Points

### Cross-Language Agent Communication

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

```text
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:

| Component | Purpose |
|---|---|
| `McpWorkbench` | Connects to MCP servers and exposes their tools to agents |
| `McpSessionHost` | Full MCP host with sampling, elicitation, and roots |
| `ChatCompletionClientSampler` | Routes MCP sampling requests to a `ChatCompletionClient` |
| `StdioElicitor` | Command-line elicitation handler |
| `StaticRootsProvider` | Provides file system roots to MCP servers |
| `StdioServerParams` | Stdio transport configuration |
| `SseServerParams` | SSE transport configuration |
| `StreamableHttpServerParams` | HTTP transport configuration |

### Memory Stores

| Store | Package | Backend |
|---|---|---|
| `ChromaDBMemory` | `autogen_ext.memory.chromadb` | ChromaDB vector store |
| `RedisMemory` | `autogen_ext.memory.redis` | Redis |
| `CanvasMemory` | `autogen_ext.memory.canvas` | Canvas |
| `Mem0Memory` | `autogen_ext.memory.mem0` | Mem0 |
| `Teachability` | `autogen_ext.experimental.task_centric_memory` | File-based learning |

### Web Framework Integration

AutoGen includes sample integrations with web frameworks:

| Framework | Sample | Pattern |
|---|---|---|
| FastAPI | `core_streaming_handoffs_fastapi` | OpenAI-compatible `/chat/completions` endpoint with streaming |
| FastAPI | `core_streaming_response_fastapi` | Single-agent streaming response |
| Streamlit | `agentchat_streamlit` | Chat UI with session state |
| Chainlit | `agentchat_chainlit`, `core_chainlit` | Chat UI with message callbacks |

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

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

### LM Studio Integration (.NET)

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

---

_Generated May 2026 from microsoft/autogen at 027ecf0. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._