Skip to main content
The Microsoft.AutoGen.Core namespace provides the foundational components for building distributed, event-driven multi-agent systems in .NET.

Agent Classes

Abstract base class for all agents in the AutoGen system.
using Microsoft.AutoGen.Core;
using Microsoft.AutoGen.Contracts;

public class MyAgent : BaseAgent
{
    public MyAgent(
        AgentId id,
        IAgentRuntime runtime,
        string description,
        ILogger<BaseAgent>? logger = null)
        : base(id, runtime, description, logger)
    {
    }
}
id
AgentId
required
Unique identifier for the agent instance
runtime
IAgentRuntime
required
Runtime environment for message passing
description
string
required
Description of the agent’s capabilities
logger
ILogger<BaseAgent>?
Optional logger instance

Properties

Id
AgentId
Gets the unique identifier of the agent
Metadata
AgentMetadata
Gets metadata associated with the agent
Runtime
IAgentRuntime
Gets the runtime environment

Methods

OnMessageAsync
ValueTask<object?>
Handles an incoming message
public async ValueTask<object?> OnMessageAsync(
    object message,
    MessageContext messageContext)
{
    // Handle message
    return response;
}
message
object
required
The received message
messageContext
MessageContext
required
Context information about the message
SendMessageAsync
ValueTask<object?>
Send a message to another agent
var response = await SendMessageAsync(
    message: "Hello",
    recipient: new AgentId("worker", "default"),
    cancellationToken: cancellationToken
);
PublishMessageAsync
ValueTask
Publish a message to a topic
await PublishMessageAsync(
    message: new { Event = "Started" },
    topic: new TopicId("events", "system")
);
CloseAsync
ValueTask
Called when the agent is being closed
Single-process agent runtime for local execution.
using Microsoft.AutoGen.Core;

var runtime = new InProcessRuntime();

// Register agent factory
await runtime.RegisterAgentFactoryAsync(
    type: new AgentType("worker"),
    factoryFunc: async (id, rt) => new WorkerAgent(id, rt)
);

// Send message
var response = await runtime.SendMessageAsync(
    message: "Task",
    recipient: new AgentId("worker", "instance1")
);
RegisterAgentFactoryAsync
ValueTask<AgentType>
Register an agent factory function
SendMessageAsync
ValueTask<object?>
Send a message to an agent
PublishMessageAsync
ValueTask
Publish a message to a topic

Contracts & Interfaces

Core interface for all agents.
public interface IAgent : ISaveState
{
    AgentId Id { get; }
    AgentMetadata Metadata { get; }
    ValueTask<object?> OnMessageAsync(object message, MessageContext messageContext);
}
Id
AgentId
Gets the unique identifier of the agent
Metadata
AgentMetadata
Gets metadata about the agent
OnMessageAsync
ValueTask<object?>
Handles incoming messages
Interface for agents that can be hosted in a runtime.
public interface IHostableAgent : IAgent
{
    ValueTask CloseAsync();
}
CloseAsync
ValueTask
Called when the runtime is closing
Defines the runtime environment for agents.
public interface IAgentRuntime : ISaveState
{
    ValueTask<object?> SendMessageAsync(
        object message,
        AgentId recipient,
        AgentId? sender = null,
        string? messageId = null,
        CancellationToken cancellationToken = default);

    ValueTask PublishMessageAsync(
        object message,
        TopicId topic,
        AgentId? sender = null,
        string? messageId = null,
        CancellationToken cancellationToken = default);

    ValueTask<AgentType> RegisterAgentFactoryAsync(
        AgentType type,
        Func<AgentId, IAgentRuntime, ValueTask<IHostableAgent>> factoryFunc);

    ValueTask AddSubscriptionAsync(ISubscriptionDefinition subscription);

    ValueTask RemoveSubscriptionAsync(string subscriptionId);
}

Methods

SendMessageAsync
ValueTask<object?>
Send a message to a specific agent and await response
message
object
required
The message to send
recipient
AgentId
required
Target agent identifier
sender
AgentId?
Sender agent (null for external)
messageId
string?
Unique message identifier
cancellationToken
CancellationToken
Cancellation token
PublishMessageAsync
ValueTask
Publish a message to all topic subscribers
message
object
required
The message payload
topic
TopicId
required
Topic to publish to
RegisterAgentFactoryAsync
ValueTask<AgentType>
Register an agent factory for dynamic creation
type
AgentType
required
Unique agent type
factoryFunc
Func<AgentId, IAgentRuntime, ValueTask<IHostableAgent>>
required
Factory function
Interface for handling messages of a specific type.
using Microsoft.AutoGen.Contracts;

public class WorkerAgent : BaseAgent, IHandle<TaskMessage>
{
    public async ValueTask<object?> HandleAsync(
        TaskMessage message,
        MessageContext context)
    {
        // Process task
        return new ResultMessage { Result = "Completed" };
    }
}
T
type parameter
Message type to handle

Identity & Types

Unique identifier for an agent instance.
using Microsoft.AutoGen.Contracts;

// Create agent ID
var agentId = new AgentId(type: "worker", key: "instance_1");

// From string
var parsed = AgentId.FromStr("worker/instance_1");

// Convert to string
string str = agentId.ToString(); // "worker/instance_1"
Type
string
required
Agent type name (alphanumeric and underscores)
Key
string
required
Instance key (ASCII 32-126 characters)

Methods

FromStr
static AgentId
Parse from “type/key” format
ToString
string
Convert to “type/key” format
Agent type definition.
using Microsoft.AutoGen.Contracts;

var workerType = new AgentType("worker");
Name
string
required
Type name identifier
Topic identifier for pub/sub messaging.
using Microsoft.AutoGen.Contracts;

var topic = new TopicId(type: "events", source: "system");
Type
string
required
Topic type
Source
string
required
Topic source namespace
Metadata about an agent.
public struct AgentMetadata
{
    public string Type { get; set; }
    public string Key { get; set; }
    public string Description { get; set; }
}
Proxy for remote agent communication.
var proxy = await runtime.TryGetAgentProxyAsync(agentId);
var result = await proxy.SendAsync("Hello");

Messaging

Context information for message handling.
public class MessageContext
{
    public AgentId? Sender { get; }
    public TopicId? TopicId { get; }
    public string MessageId { get; }
}
Sender
AgentId?
Identifier of the message sender
TopicId
TopicId?
Topic the message was published to
MessageId
string
Unique message identifier

Subscriptions

Subscribe to messages by exact type match.
using Microsoft.AutoGen.Core;

var subscription = new TypeSubscription(
    topicType: "tasks",
    agentType: "worker"
);

await runtime.AddSubscriptionAsync(subscription);
TopicType
string
required
Topic type to subscribe to
AgentType
string
required
Agent type that will receive messages
Subscribe to messages matching a type prefix.
var subscription = new TypePrefixSubscription(
    topicTypePrefix: "task.",
    agentType: "worker"
);
Attribute for declarative subscriptions.
[TypeSubscription("tasks")]
public class WorkerAgent : BaseAgent, IHandle<TaskMessage>
{
    // ...
}

State Management

Interface for agent state persistence.
public interface ISaveState
{
    ValueTask<JsonElement> SaveStateAsync();
    ValueTask LoadStateAsync(JsonElement state);
}
SaveStateAsync
ValueTask<JsonElement>
Save the agent’s state to JSON
LoadStateAsync
ValueTask
Load state from JSON

Application Host

Application host for agent systems.
using Microsoft.AutoGen.Core;

var app = await AgentsApp.CreateAsync();

// Register agents
await app.RegisterAgentAsync<WorkerAgent>("worker");

// Start the application
await app.StartAsync();
CreateAsync
static Task<AgentsApp>
Create a new agents application
RegisterAgentAsync
Task
Register an agent type
StartAsync
Task
Start the application
StopAsync
Task
Stop the application

Exceptions

Thrown when an agent cannot handle a message.
throw new CantHandleException("Unsupported message type");
Thrown when a message cannot be delivered.
throw new UndeliverableException("Agent not found");

Utilities

Utilities for agent reflection and discovery.
using Microsoft.AutoGen.Core;

var handlers = ReflectionHelper.GetMessageHandlers(agentType);
Invokes message handlers dynamically.
var invoker = new HandlerInvoker(methodInfo, target);
var result = await invoker.InvokeAsync(message, context);

Telemetry

OpenTelemetry integration.
using System.Diagnostics;

public static readonly ActivitySource s_source =
    new("Microsoft.AutoGen.Core.Agent");

using var activity = s_source.StartActivity("HandleMessage");

See Also

Build docs developers (and LLMs) love