autogen Documentation

A programming framework for agentic AI

57,850 stars Python Python 1 file · ~9,971 tokens #agentic#agentic-agi#agents#ai#autogen#autogen-ecosystem#chatgpt#framework
RAW Doc

Docker & Self-Hosted Deployment Verified OCI

Deploy autogen on any server, homelab, or cloud container platform.

1-Click Terminal Command
bash (docker run) 
docker run -d --name autogen --restart always microsoft/autogen:latest

1. Project Overview & Quickstart (microsoft/autogen)

File: README.md

AutoGen [](https://github.com/microsoft/agent-framework)

AutoGen is a framework for creating multi-agent AI applications that can act autonomously or work alongside humans.

[!CAUTION]
⚠️ Maintenance Mode

AutoGen is now in maintenance mode. It will not receive new features or enhancements and is community managed going forward.

New users should start with Microsoft Agent Framework. Existing users are encouraged to migrate using the AutoGen → Microsoft Agent Framework migration guide.

Microsoft Agent Framework (MAF) is the enterprise‑ready successor to AutoGen. Microsoft Agent FrameworkAF in now available as a production-ready release: stable APIs, and a commitment to long-term support. Whether you're building a single assistant or orchestrating a fleet of specialized agents, Microsoft Agent Framework 1.0 gives you enterprise-grade multi-agent orchestration, multi-provider model support, and cross-runtime interoperability via A2A and MCP.

Installation

AutoGen requires Python 3.10 or later.

bash
# Install AgentChat and OpenAI client from Extensions
pip install -U "autogen-agentchat" "autogen-ext[openai]"

The current stable version can be found in the releases. If you are upgrading from AutoGen v0.2, please refer to the Migration Guide for detailed instructions on how to update your code and configurations.

bash
# Install AutoGen Studio for no-code GUI
pip install -U "autogenstudio"

Quickstart

The following samples call OpenAI API, so you first need to create an account and export your key as export OPENAI_API_KEY="sk-...".

Hello World

Create an assistant agent using OpenAI's GPT-4o model. See other supported models.

python
import asyncio
from autogen_agentchat.agents import AssistantAgent
from autogen_ext.models.openai import OpenAIChatCompletionClient

async def main() -> None:
    model_client = OpenAIChatCompletionClient(model="gpt-4.1")
    agent = AssistantAgent("assistant", model_client=model_client)
    print(await agent.run(task="Say 'Hello World!'"))
    await model_client.close()

asyncio.run(main())

MCP Server

Create a web browsing assistant agent that uses the Playwright MCP server.

python
# First run `npm install @playwright/mcp@latest` to install the MCP server.
import asyncio
from autogen_agentchat.agents import AssistantAgent
from autogen_agentchat.ui import Console
from autogen_ext.models.openai import OpenAIChatCompletionClient
from autogen_ext.tools.mcp import McpWorkbench, StdioServerParams


async def main() -> None:
    model_client = OpenAIChatCompletionClient(model="gpt-4.1")
    server_params = StdioServerParams(
        command="npx",
        args=[
            "@playwright/mcp@latest",
            "--headless",
        ],
    )
    async with McpWorkbench(server_params) as mcp:
        agent = AssistantAgent(
            "web_browsing_assistant",
            model_client=model_client,
            workbench=mcp, # For multiple MCP servers, put them in a list.
            model_client_stream=True,
            max_tool_iterations=10,
        )
        await Console(agent.run_stream(task="Find out how many contributors for the microsoft/autogen repository"))


asyncio.run(main())

Warning: Only connect to trusted MCP servers as they may execute commands
in your local environment or expose sensitive information.

Multi-Agent Orchestration

You can use AgentTool to create a basic multi-agent orchestration setup.

python
import asyncio

from autogen_agentchat.agents import AssistantAgent
from autogen_agentchat.tools import AgentTool
from autogen_agentchat.ui import Console
from autogen_ext.models.openai import OpenAIChatCompletionClient


async def main() -> None:
    model_client = OpenAIChatCompletionClient(model="gpt-4.1")

    math_agent = AssistantAgent(
        "math_expert",
        model_client=model_client,
        system_message="You are a math expert.",
        description="A math expert assistant.",
        model_client_stream=True,
    )
    math_agent_tool = AgentTool(math_agent, return_value_as_last_message=True)

    chemistry_agent = AssistantAgent(
        "chemistry_expert",
        model_client=model_client,
        system_message="You are a chemistry expert.",
        description="A chemistry expert assistant.",
        model_client_stream=True,
    )
    chemistry_agent_tool = AgentTool(chemistry_agent, return_value_as_last_message=True)

    agent = AssistantAgent(
        "assistant",
        system_message="You are a general assistant. Use expert tools when needed.",
        model_client=model_client,
        model_client_stream=True,
        tools=[math_agent_tool, chemistry_agent_tool],
        max_tool_iterations=10,
    )
    await Console(agent.run_stream(task="What is the integral of x^2?"))
    await Console(agent.run_stream(task="What is the molecular weight of water?"))


asyncio.run(main())

For more advanced multi-agent orchestrations and workflows, read
AgentChat documentation.

AutoGen Studio

Use AutoGen Studio to prototype and run multi-agent workflows without writing code.

Caution: AutoGen Studio is meant to help you rapidly prototype multi-agent workflows and
demonstrate an example of end user interfaces built with AutoGen. It is not meant to be a
production-ready app. Developers are encouraged to use the AutoGen framework to build their own
applications, implementing authentication, security and other features required for deployed
applications. See the security note for more details.

bash
# Run AutoGen Studio on http://localhost:8080
autogenstudio ui --port 8080 --appdir ./my-app

Why AutoGen?

Pioneered in Microsoft Research, AutoGen opened the door to experimental multi-agent orchestration patterns that inspired the community. While AutoGen is now in maintenance mode, existing users can continue to use the framework with the architecture described below. For new projects, we recommend Microsoft Agent Framework, which builds on the lessons learned from AutoGen with enterprise-grade support.

The autogen framework uses a layered and extensible design. Layers have clearly divided responsibilities and build on top of layers below. This design enables you to use the framework at different levels of abstraction, from high-level APIs to low-level components.

  • Core API implements message passing, event-driven agents, and local and distributed runtime for flexibility and power. It also support cross-language support for .NET and Python.
  • AgentChat API implements a simpler but opinionated API for rapid prototyping. This API is built on top of the Core API and is closest to what users of v0.2 are familiar with and supports common multi-agent patterns such as two-agent chat or group chats.
  • Extensions API enables first- and third-party extensions continuously expanding framework capabilities. It support specific implementation of LLM clients (e.g., OpenAI, AzureOpenAI), and capabilities such as code execution.

The ecosystem also supports two essential developer tools:

  • AutoGen Studio provides a no-code GUI for building multi-agent applications.
  • AutoGen Bench provides a benchmarking suite for evaluating agent performance.

You can use the AutoGen framework and developer tools to create applications for your domain. For example, Magentic-One is a state-of-the-art multi-agent team built using AgentChat API and Extensions API that can handle a variety of tasks that require web browsing, code execution, and file handling.

For community support, visit our Discord server or GitHub Discussions. Note that AutoGen is now community-managed and responses may be limited.

Where to go next?

Starting a new project? Head to Microsoft Agent Framework for the latest multi-agent capabilities with long-term support.

Existing AutoGen user? Use the migration guide to transition, or refer to the resources below for current AutoGen documentation.

Interested in contributing? See CONTRIBUTING.md for guidelines. As AutoGen is in maintenance mode, contributions are limited to bug fixes, security patches, and documentation improvements. For feature development, consider contributing to Microsoft Agent Framework.

Have questions? Check out our Frequently Asked Questions (FAQ) for answers to common queries. Community support is available through GitHub Discussions and the Discord server, though response times may vary as AutoGen is now community-managed. For actively supported tooling, see Microsoft Agent Framework.

Microsoft and any contributors grant you a license to the Microsoft documentation and other content
in this repository under the Creative Commons Attribution 4.0 International Public License,
see the LICENSE file, and grant you a license to any code in the repository under the MIT License, see the
LICENSE-CODE file.

Microsoft, Windows, Microsoft Azure, and/or other Microsoft products and services referenced in the documentation
may be either trademarks or registered trademarks of Microsoft in the United States and/or other countries.
The licenses for this project do not grant you rights to use any Microsoft names, logos, or trademarks.
Microsoft's general trademark guidelines can be found at http://go.microsoft.com/fwlink/?LinkID=254653.

Privacy information can be found at https://go.microsoft.com/fwlink/?LinkId=521839

Microsoft and any contributors reserve all other rights, whether under their respective copyrights, patents,
or trademarks, whether by implication, estoppel, or otherwise.

↑ Back to Top ↑

File: docs/dotnet/core/differences-from-python.md

Differences from Python

Publishing to a topic that an agent is also subscribed to

[!NOTE]
TLDR; Default behavior is identical.

When an agent publishes a message to a topic to which it also listens, the message will not be received by the agent that sent it. This is also the behavior in the Python runtime. However to support previous usage, in @Microsoft.AutoGen.Core.InProcessRuntime, you can set the @Microsoft.AutoGen.Core.InProcessRuntime.DeliverToSelf property to true in the TopicSubscription attribute to allow an agent to receive messages it sends.

File: docs/dotnet/core/index.md

AutoGen Core

AutoGen Core for .NET follows the same concepts and conventions of its Python counterpart. In fact, in order to understand the concepts in the .NET version, we recommend reading the Python documentation first. Unless otherwise stated, the concepts in the Python version map to .NET.

Any important differences between the language versions are documented in the Differences from Python section. For things that only affect a given language, such as dependency injection or host builder patterns, these will not be specified in the differences document.

Getting Started

You can obtain the SDK as a nuget package or by cloning the repository. The SDK is available on NuGet.
Minimally you will need the following:

bash
dotnet add package Microsoft.AutoGen.Contracts
dotnet add package Microsoft.AutoGen.Core

See Installation for more detailed notes on installing all the related packages.

You can quickly get started by looking at the samples in the samples directory of the repository.

Creating an Agent

To create an agent, you can inherit from BaseAgent and implement event handlers for the events you care about. Here is a minimal example demonstrating how to inherit from BaseAgent and implement an event handler:

csharp
public class MyAgent : BaseAgent, IHandle<MyMessage>
{
    // ...
    public async ValueTask HandleAsync(MyMessage item, MessageContext context)
    {
        // ...logic here...
    }
}

By overriding BaseAgent, you gain access to the runtime and logging utilities, and by implementing IHandle, you can easily define event-handling methods for your custom messages.

Running an Agent in an Application

To run your agent in an application, you can use the AgentsAppBuilder class. Here is an example of how to run an agent 'HelloAgent' in an application:

csharp
AgentsAppBuilder appBuilder = new AgentsAppBuilder()
    .UseInProcessRuntime(deliverToSelf: true)
    .AddAgent<HelloAgent>("HelloAgent");

var app = await appBuilder.BuildAsync();

// start the app by publishing a message to the runtime
await app.PublishMessageAsync(new NewMessageReceived
{
    Message = "Hello from .NET"
}, new TopicId("HelloTopic"));

// Wait for shutdown
await app.WaitForShutdownAsync();

.NET SDK Runtimes

The .NET SDK includes both an InMemory Single Process Runtime and a Remote, Distributed Runtime meant for running your agents in the cloud. The Distributed Runtime supports running agents in python and in .NET, allowing those agents to talk to one another. The distributed runtime uses Microsoft Orleans to provide resilience, persistence, and integration with messaging services such as Azure Event Hubs. The xlang functionality requires that your agent's Messages are serializable as CloudEvents. The messages are exchanged as CloudEvents over Grpc, and the runtime takes care of ensuring that the messages are delivered to the correct agents.

To use the Distributed Runtime, you will need to add the following package to your project:

bash
dotnet add package Microsoft.AutoGen.Core.Grpc

This is the package that runs in the application with your agent(s) and connects to the distributed system.

To Run the backend/server side you need:

bash
dotnet add package Microsoft.AutoGen.RuntimeGateway
dotnet add package Microsoft.AutoGen.AgentHost

You can run the backend on its own:

bash
dotnet run --project Microsoft.AutoGen.AgentHost

or you can include it inside your own application:

csharp
using Microsoft.AutoGen.RuntimeGateway;
using Microsoft.AutoGen.AgentHost;
var autogenBackend = await Microsoft.AutoGen.RuntimeGateway.Grpc.Host.StartAsync(local: false, useGrpc: true).ConfigureAwait(false);

You can also install the runtime as a dotnet tool:

text
dotnet pack --no-build --configuration Release --output './output/release' -bl\n
dotnet tool install --add-source ./output/release Microsoft.AutoGen.AgentHost
# run the tool
# dotnet agenthost 
# or just...  
agenthost

Running Multiple Agents and the Runtime in separate processes with .NET Aspire

The Hello.AppHost project illustrates how to orchestrate a distributed system with multiple agents and the runtime in separate processes using .NET Aspire. It also points to a python agent that illustrates how to run agents in different languages in the same distributed system.

csharp
// Copyright (c) Microsoft Corporation. All rights reserved.
// Program.cs

using Microsoft.Extensions.Hosting;

var builder = DistributedApplication.CreateBuilder(args);
var backend = builder.AddProject("backend").WithExternalHttpEndpoints();
var client = builder.AddProject("HelloAgentsDotNET")
    .WithReference(backend)
    .WithEnvironment("AGENT_HOST", backend.GetEndpoint("https"))
    .WithEnvironment("STAY_ALIVE_ON_GOODBYE", "true")
    .WaitFor(backend);
// xlang is over http for now - in prod use TLS between containers
builder.AddPythonApp("HelloAgentsPython", "../../../../python/samples/core_xlang_hello_python_agent", "hello_python_agent.py", "../../.venv")
    .WithReference(backend)
    .WithEnvironment("AGENT_HOST", backend.GetEndpoint("http"))
    .WithEnvironment("STAY_ALIVE_ON_GOODBYE", "true")
    .WithEnvironment("GRPC_DNS_RESOLVER", "native")
    .WithOtlpExporter()
    .WaitFor(client);
using var app = builder.Build();
await app.StartAsync();
var url = backend.GetEndpoint("http").Url;
Console.WriteLine("Backend URL: " + url);
await app.WaitForShutdownAsync();

You can find more examples of how to use Aspire and XLang agents in the Microsoft.AutoGen.Integration.Tests.AppHost directory.

Configuring Logging

The SDK uses the Microsoft.Extensions.Logging framework for logging. Here is an example appsettings.json file with some useful defaults:

json
{
  "Logging": {
    "LogLevel": {
      "Default": "Warning",
      "Microsoft.Hosting.Lifetime": "Information",
      "Microsoft.AspNetCore": "Information",
      "Microsoft": "Information",
      "Microsoft.Orleans": "Warning",
      "Orleans.Runtime": "Error",
      "Grpc": "Information"
    }
  },
  "AllowedHosts": "*",
  "Kestrel": {
    "EndpointDefaults": {
      "Protocols": "Http2"
    }
  }
}

Defining Message Types in Protocol Buffers

A convenient way to define common event or message types to be used in both python and .NET agents is to define your events. This is covered here: Using Protocol Buffers to Define Message Types.

File: docs/dotnet/core/installation.md

Installation

Install via .NET cli

sh
dotnet add package Microsoft.AutoGen.Contracts --version 0.4.0-dev.1
dotnet add package Microsoft.AutoGen.Core --version 0.4.0-dev.1

Or, install via Package Manager

pwsh
PM> NuGet\Install-Package Microsoft.AutoGen.Contracts -Version 0.4.0-dev.1
PM> NuGet\Install-Package Microsoft.AutoGen.Core -Version 0.4.0-dev.1

Or, add via ``

xml

Additional Packages

The Core and Contracts packages will give you what you need for writing and running agents using the Core API within a single process.

  • Microsoft.AutoGen.AgentChat - An implementation of the AgentChat package for building chat-centric agent orchestration on top of the Core SDK
  • Microsoft.AutoGen.Agents - a package that has a small number of default agents you can use.
  • Microsoft.AutoGen.Extensions - Extensions to support closely related projects including Aspire, Microsoft.Extensions.AI, and Semantic Kernel
sh
dotnet add package Microsoft.AutoGen.AgentChat --version 0.4.0-dev-1
dotnet add package Microsoft.AutoGen.Agents --version 0.4.0-dev-1
dotnet add package Microsoft.AutoGen.Extensions --version 0.4.0-dev-1

To enable running a system with agents in different processes that allows for x-language communication between python and .NET agents, there are additional packages:

  • Microsoft.AutoGen.Core.Grpc - the .NET client runtime for agents in a distributed system. It has the same API as Microsoft.AutoGen.Core.
  • Microsoft.AutoGen.RuntimeGatewway.Grpc - the .NET server side of the distributed system that allows you to run multiple gateways to manage fleets of agents and enables x-language interoperability.
  • Microsoft.AutoGen.AgentHost - A .NET Aspire project that hosts the Grpc Service
sh
dotnet add package Microsoft.AutoGen.Core.Grpc --version 0.4.0-dev-1
dotnet add package Microsoft.AutoGen.RuntimeGateway.Grpc --version 0.4.0-dev-1
dotnet add package Microsoft.AutoGen.AgentHost --version 0.4.0-dev-1

File: docs/dotnet/core/protobuf-message-types.md

Using Protocol Buffers to Define Message Types

For a message to be sent using a runtime other than the @Microsoft.AutoGen.Core.InProcessRuntime, it must be defined as a Protocol Buffers message. This is because the message is serialized and deserialized using Protocol Buffers. This requirement may be relaxed in future by allowing for converters, custom serialization, or other mechanisms.

How to include Protocol Buffers in a .NET project

The .proto file which defines the message types must be included in the project, which will automatically generate the C# classes for the messages.

  1. Include Grpc.Tools package in your .csproj file:
xml
  1. Create an include a .proto file in the project:
xml
  1. define your messages as specified in the Protocol Buffers Language Guide
proto
syntax = "proto3";

package HelloAgents;

option csharp_namespace = "MyAgentsProtocol";

message TextMessage {
    string Source = 1;
    string Content = 2;
}
  1. Code against the generated class for handling, sending and publishing messages:
csharp
using Microsoft.AutoGen.Contracts;
using Microsoft.AutoGen.Core;
using MyAgentsProtocol;

[TypeSubscription("default")]
public class Checker(
    AgentId id,
    IAgentRuntime runtime,
    ) :
        BaseAgent(id, runtime, "MyAgent", null),
        IHandle<TextMessage>
{
    public async ValueTask HandleAsync(TextMessage item, MessageContext messageContext)
    {
        Console.WriteLine($"Received message from {item.Source}: {item.Content}");
    }
}

File: docs/dotnet/core/tutorial.md

Tutorial

[!TIP]
If you'd prefer to just see the code the entire sample is available as a project here.

In this tutorial we are going to define two agents, Modifier and Checker, that will count down from 10 to 1. The Modifier agent will modify the count and the Checker agent will check the count and stop the application when the count reaches 1.

Defining the message types

The first thing we need to do is to define the messages that will be passed between the agents, we're simply going to define them as classes.

We're going to use CountMessage to pass the current count and CountUpdate to pass the updated count.

[!code-csharp]
[!code-csharp]

By separating out the message types into strongly typed classes, we can build a workflow where agents react to certain types and produce certain types.

Creating the agents

Inherit from `BaseAgent`

In AutoGen an agent is a class that can receive and send messages. The agent defines its own logic of what to do with the messages it receives. To define an agent, create a class that inherits from @Microsoft.AutoGen.Core.BaseAgent, like so:

csharp
using Microsoft.AutoGen.Contracts;
using Microsoft.AutoGen.Core;

public class Modifier(
    AgentId id,
    IAgentRuntime runtime,
    ) :
        BaseAgent(id, runtime, "MyAgent", null),
{
}

We will see how to pass arguments to an agent when it is constructed, but for now you just need to know that @Microsoft.AutoGen.Contracts.AgentId and @Microsoft.AutoGen.Core.IAgentRuntime will always be passed to the constructor, and those should be forwarded to the base class constructor. The other two arguments are a description of the agent and an optional logger.

Learn more about what an Agent ID is here.

Create a handler

Now, we want Modifier to receive CountMessage and produce CountUpdate after it modifies the count. To do this, we need to implement the IHandle<CountMessage> interface:

csharp
public class Modifier(
    // ...
    ) :
        BaseAgent(...),
        IHandle<CountMessage>
{

    public async ValueTask HandleAsync(CountMessage item, MessageContext messageContext)
    {
        // ...
    }
}

Add a subscription

We've defined a function that will be called when a CountMessage is delivered to this agent, but there is still one step before the message will actually be delivered to the agent. The agent must subscribe to the topic to the message is published to. We can do this by adding the TypeSubscription attribute to the class:

csharp
[TypeSubscription("default")]
public class Modifier(
    // ...

Learn more about topics and subscriptions here.

Publish a message

Now that we have a handler for CountMessage, and we have the subscription in place we can publish a result out of the handler.

csharp
public async ValueTask HandleAsync(CountMessage item, MessageContext messageContext)
{
    int newValue = item.Content - 1;
    Console.WriteLine($"\nModifier:\nModified {item.Content} to {newValue}");

    CountUpdate updateMessage = new CountUpdate { NewCount = newValue };
    await this.PublishMessageAsync(updateMessage, topic: new TopicId("default"));
}

You'll notice that when we publish the message, we specify the topic to publish to. We're using a topic called default in this case, which is the same topic which we subscribed to. We could have used a different topic, but in this case we're keeping it simple.

Passing arguments to the agent

Let's extend our agent to make what we do to the count configurable. We'll do this by passing a function to the agent that will be used to modify the count.

csharp
using ModifyF = System.Func;

// ...

[TypeSubscription("default")]
public class Modifier(
    AgentId id,
    IAgentRuntime runtime,
    ModifyF modifyFunc // <-- Add this
    ) :
        BaseAgent(...),
        IHandle<CountMessage>
{

    public async ValueTask HandleAsync(CountMessage item, MessageContext messageContext)
    {
        int newValue = modifyFunc(item.Content); // <-- use it here

        // ...
    }
}

Final Modifier implementation

Here is the final implementation of the Modifier agent:

[!code-csharp]

Checker

We'll also define a Checker agent that will check the count and stop the application when the count reaches 1. Additionally, we'll use dependency injection to get a reference to the IHostApplicationLifetime service, which we can use to stop the application.

[!code-csharp]

Putting it all together

Now that we have our agents defined, we can put them together in a simple application that will count down from 10 to 1.

After includes, the first thing to do is to define the two functions for modifying and checking for completion.

[!code-csharp]

Then, we create a builder and do the following things:

  • Specify that we are using the in process runtime
  • Register our functions as services
  • Register the agent classes we defined earlier
  • Finally, build and start our app

[!code-csharp]

The app is now running, but we need to kick off the process with a message. We do this by publishing a CountMessage with an initial value of 10.
Importantly we publish this to the "default" topic which is what our agents are subscribed to. Finally, we wait for the application to stop.

[!code-csharp]

That's it! You should see the count down from 10 to 1 in the console.

Here's the full code for the Program class:

[!code-csharp]

Things to try

Here are some ideas to try with this sample:

  • Change the initial count
  • Create a new modifier function that counts up instead. (Don't forget to change the checker too!)
  • Create an agent that outputs to the console instead of the modifier or checker agent doing it themselves (hint: use a new message type)

File: docs/dotnet/index.md

_disableAffix: true

text
<h1>AutoGen .NET</h1>

A *.NET* framework for building AI agents and applications






  
    <h5 class="card-title">Core</h5>






text
An event-driven programming framework for building scalable multi-agent AI systems.
  • Deterministic and dynamic agentic workflows for business processes
  • Research on multi-agent collaboration
  • Distributed agents for multi-language applications
  • integration with event-driven, cloud native applications

Start here if you are building workflows or distributed agent systems

bash
dotnet add package Microsoft.AutoGen.Contracts
dotnet add package Microsoft.AutoGen.Core

# optionally - for distributed agent systems:
dotnet add package Microsoft.AutoGen.RuntimeGateway.Grpc
dotnet add package Microsoft.AutoGen.AgentHost

# other optional packages
dotnet add package Microsoft.AutoGen.Agents
dotnet add package Microsoft.AutoGen.Extensions.Aspire
dotnet add package Microsoft.AutoGen.Extensions.MEAI
dotnet add package Microsoft.AutoGen.Extensions.SemanticKernel
text
[Get started](core/index.md)
  




  
    <h5 class="card-title">AgentChat</h5>
    A programming framework for building conversational single and multi-agent applications. Built on Core.
    [Coming soon](#)

File: docs/dotnet/README.md

How to build and run the website

Prerequisites

  • dotnet 8.0 or later

Build

Firstly, go to autogen/dotnet folder and run the following command to build the website:

bash
dotnet tool restore
dotnet tool run docfx ../docs/dotnet/docfx.json --serve

After the command is executed, you can open your browser and navigate to http://localhost:8080 to view the website.

File: docs/design/01 - Programming Model.md

Programming Model

Understanding your workflow and mapping it to agents is the key to building an agent system in AutoGen.

The programming model is basically publish-subscribe. Agents subscribe to events they care about and also can publish events that other agents may care about. Agents may also have additonal assets such as Memory, prompts, data sources, and skills (external APIs).

Events Delivered as CloudEvents

Each event in the system is defined using the CloudEvents Specification. This allows for a common event format that can be used across different systems and languages. In CloudEvents, each event has "Context Attributes" that must include:

  1. id - A unique id (eg. a UUID).
  2. source - A URI or URN indicating the event's origin.
  3. type - The namespace of the event - prefixed with a reverse-DNS name.
    • The prefixed domain dictates the organization which defines the semantics of this event type: e.g (com.github.pull_request.opened or com.example.object.deleted.v2), and optionally fields describing the data schema/content-type or extensions.

Event Handlers

Each agent has a set of event handlers, that are bound to a specific match against a CloudEvents type. Event Handlers could match against an exact type or match for a pattern of events of a particular level in the type heirarchy (eg: com.Microsoft.AutoGen.Agents.System.* for all Events in the System namespace) Each event handler is a function that can change state, call models, access memory, call external tools, emit other events, and flow data to/from other systems. Each event handler can be a simple function or a more complex function that uses a state machine or other control logic.

Orchestrating Agents

It is possible to build a functional and scalable agent system that only reacts to external events. In many cases, however, you will want to orchestrate the agents to achieve a specific goal or follow a pre-determined workflow. In this case, you will need to build an orchestrator agent that manages the flow of events between agents.

Built-in Event Types

The AutoGen system comes with a set of built-in event types that are used to manage the system. These include:

  • System Events - Events that are used to manage the system itself. These include events for starting and stopping the Agents, sending messages to all agents, and other system-level events.
  • Insert other types here

Agent Contracts

You may want to leverage more prescriptive agent behavior contracts, and AutoGen also includes base agents that implement different approaches to agent behavior, including layering request/response patterns on top of the event-driven model. For an example of this see the ChatAgents in the Python examples. In this case your agent will have a known set of events which it must implement and specific behaviors expected of those events.

File: docs/design/02 - Topics.md

Topics

This document describes the semantics and components of publishing messages and subscribing to topics.

Overview

Topics are used as the primitive to manage which agents receive a given published message. Agents subscribe to topics. There is an application defined mapping from topic to agent instance.

These concepts intentionally map to the CloudEvents specification. This allows for easy integration with existing systems and tools.

Non-goals

This document does not specify RPC/direct messaging

Identifiers

A topic is identified by two components (called a TopicId):

  • type - represents the type of event that occurs, this is static and defined in code
    • SHOULD use reverse domain name notation to avoid naming conflicts. For example: com.example.my-topic.
    • Allowed values MUST match the regex: ^[\w\-\.\:\=]+\Z
    • Notably, this is the same as agent type with the addition of = and : characters
  • source - represents where the event originated from, this is dynamic and based on the message itself
    • SHOULD be a URI

Agent instances are identified by two components (called an AgentId):

  • type - represents the type of agent, this is static and defined in code
    • Allowed values MUST match the regex: ^[\w\-\.]+\Z
  • key - represents the instance of the agent type for the key
    • SHOULD be a URI

For example: GraphicDesigner:1234

Subscriptions

Subscriptions define which agents receive messages published to a topic. Subscriptions are dynamic and can be added or removed at any time.

A subscription defines two things:

  • Matcher func of type TopicId -> bool, telling us "does this subscription match this topic"
  • Mapper func of type TopicId -> AgentId, telling us "given this subscription matches this topic, which agent does it map to"

These functions MUST be be free of side effects such that the evaluation can be cached.

Agent instance creation

If a message is received on a topic that maps to an agent that does not yet exist the runtime will instantiate an agent to fullfil the request.

Message types

Agents are able to handle certain types of messages. This is an internal detail of an agent's implementation. All agents in a channel will receive all messages, but will ignore messages that it cannot handle.

[!NOTE]
This might be revisited based on scaling and performance considerations.

Well known topic types

Agents should subscribe via a prefix subscription to the {AgentType}: topic as a direct message channel for the agent type.

For this subscription source should map directly to agent key.

This subscription will therefore receive all events for the following well known topics:

  • {AgentType}: - General purpose direct messages. These should be routed to the appropriate message handler.
  • {AgentType}:rpc_request={RequesterAgentType} - RPC request messages. These should be routed to the appropriate RPC handler, and RequesterAgentType used to publish the response
  • {AgentType}:rpc_response={RequestId} - RPC response messages. These should be routed back to the response future of the caller.
  • {AgentType}:error={RequestId} - Error message that corresponds to the given request.

2. Official Technical Reference & Guides (microsoft/microsoft.github.io)

[microsoft.github.io](https://microsoft.github.io)

Many open source projects released by Microsoft products, services and teams also have
deployments powered by GitHub Pages on this domain.

To discover Microsoft-released open source projects, learn about Microsoft's open source
approach and other information, check us out online at opensource.microsoft.com.

If we can help answer questions about the open source program at Microsoft, you can
contact opensource at microsoft com - although we are not able to provide support
for projects through this mechanism.

Microsoft GitHub resources

Microsoft open source resources

Resources for Microsoft employees

How to identify an official Microsoft organization on GitHub

  • Official Microsoft GitHub orgs have a professional avatar and include a web address at Microsoft.com or an associated official domain
  • Official Microsoft orgs are Verified on GitHub - look for the domain verification indicator on GitHub

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#agentic Browse agentic catalog → #agentic-agi Browse agentic-agi catalog → #agents Browse agents catalog → #ai Browse ai catalog → #autogen Browse autogen catalog → #autogen-ecosystem Browse autogen-ecosystem catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →