Microsoft.AutoGen.Core

.NET Core API reference for building distributed multi-agent systems

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

Agent Classes

BaseAgent

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

InProcessRuntime

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

IAgent

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

IHostableAgent

Interface for agents that can be hosted in a runtime.

public interface IHostableAgent : IAgent
{
    ValueTask CloseAsync();
}

CloseAsync · ValueTask

Called when the runtime is closing

IAgentRuntime

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

IHandle<T>

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

AgentId

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

AgentType

Agent type definition.

using Microsoft.AutoGen.Contracts;

var workerType = new AgentType("worker");

Name · string · required

Type name identifier

TopicId

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

AgentMetadata

Metadata about an agent.

public struct AgentMetadata
{
    public string Type { get; set; }
    public string Key { get; set; }
    public string Description { get; set; }
}

AgentProxy

Proxy for remote agent communication.

var proxy = await runtime.TryGetAgentProxyAsync(agentId);
var result = await proxy.SendAsync("Hello");

Messaging

MessageContext

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

TypeSubscription

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

TypePrefixSubscription

Subscribe to messages matching a type prefix.

var subscription = new TypePrefixSubscription(
    topicTypePrefix: "task.",
    agentType: "worker"
);

TypeSubscriptionAttribute

Attribute for declarative subscriptions.

[TypeSubscription("tasks")]
public class WorkerAgent : BaseAgent, IHandle<TaskMessage>
{
    // ...
}

State Management

ISaveState

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

AgentsApp

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

CantHandleException

Thrown when an agent cannot handle a message.

throw new CantHandleException("Unsupported message type");

UndeliverableException

Thrown when a message cannot be delivered.

throw new UndeliverableException("Agent not found");

Utilities

ReflectionHelper

Utilities for agent reflection and discovery.

using Microsoft.AutoGen.Core;

var handlers = ReflectionHelper.GetMessageHandlers(agentType);

HandlerInvoker

Invokes message handlers dynamically.

var invoker = new HandlerInvoker(methodInfo, target);
var result = await invoker.InvokeAsync(message, context);

Telemetry

ActivitySource

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

• Microsoft.AutoGen.Agents - Pre-built agent implementations
• Microsoft.AutoGen.Extensions - Extensions and integrations