Interface IAgentRuntime

Namespace

Microsoft.AutoGen.Contracts

Assembly

Microsoft.AutoGen.Contracts.dll

Defines the runtime environment for agents, managing message sending, subscriptions, agent resolution, and state persistence.

public interface IAgentRuntime : ISaveState

Inherited Members

ISaveState.DefaultSaveStateAsync()

ISaveState.SaveStateAsync()

ISaveState.LoadStateAsync(JsonElement)

Methods

AddSubscriptionAsync(ISubscriptionDefinition)

Adds a new subscription for the runtime to handle when processing published messages.

ValueTask AddSubscriptionAsync(ISubscriptionDefinition subscription)

Parameters

subscription ISubscriptionDefinition

The subscription to add.

Returns

ValueTask

A task representing the asynchronous operation.

GetAgentAsync(AgentId, bool)

Retrieves an agent by its unique identifier.

ValueTask<AgentId> GetAgentAsync(AgentId agentId, bool lazy = true)

Parameters

agentId AgentId

The unique identifier of the agent.

lazy bool

If true, the agent is fetched lazily.

Returns

ValueTask<AgentId>

A task representing the asynchronous operation, returning the agent's ID.

GetAgentAsync(AgentType, string, bool)

Retrieves an agent by its type.

ValueTask<AgentId> GetAgentAsync(AgentType agentType, string key = "default", bool lazy = true)

Parameters

agentType AgentType

The type of the agent.

key string

An optional key to specify variations of the agent. Defaults to "default".

lazy bool

If true, the agent is fetched lazily.

Returns

ValueTask<AgentId>

A task representing the asynchronous operation, returning the agent's ID.

GetAgentAsync(string, string, bool)

Retrieves an agent by its string representation.

ValueTask<AgentId> GetAgentAsync(string agent, string key = "default", bool lazy = true)

Parameters

agent string

The string representation of the agent.

key string

An optional key to specify variations of the agent. Defaults to "default".

lazy bool

If true, the agent is fetched lazily.

Returns

ValueTask<AgentId>

A task representing the asynchronous operation, returning the agent's ID.

GetAgentMetadataAsync(AgentId)

Retrieves metadata for an agent.

ValueTask<AgentMetadata> GetAgentMetadataAsync(AgentId agentId)

Parameters

agentId AgentId

The ID of the agent.

Returns

ValueTask<AgentMetadata>

A task representing the asynchronous operation, returning the agent's metadata.

LoadAgentStateAsync(AgentId, JsonElement)

Loads the saved state into an agent.

ValueTask LoadAgentStateAsync(AgentId agentId, JsonElement state)

Parameters

agentId AgentId

The ID of the agent whose state is being restored.

state JsonElement

The state dictionary to restore.

Returns

ValueTask

A task representing the asynchronous operation.

PublishMessageAsync(object, TopicId, AgentId?, string?, CancellationToken)

Publishes a message to all agents subscribed to the given topic. No responses are expected from publishing.

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

Parameters

message object

The message to publish.

topic TopicId

The topic to publish the message to.

sender AgentId?

The agent sending the message. Defaults to null.

messageId string

A unique message ID. If null, a new one will be generated.

cancellationToken CancellationToken

A token to cancel the operation if needed.

Returns

ValueTask

A task representing the asynchronous operation.

Exceptions

UndeliverableException

Thrown if the message cannot be delivered.

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

Registers an agent factory with the runtime, associating it with a specific agent type. The type must be unique.

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

Parameters

type AgentType

The agent type to associate with the factory.

factoryFunc Func<AgentId, IAgentRuntime, ValueTask<IHostableAgent>>

A function that asynchronously creates the agent instance.

Returns

ValueTask<AgentType>

A task representing the asynchronous operation, returning the registered AgentType.

RemoveSubscriptionAsync(string)

Removes a subscription from the runtime.

ValueTask RemoveSubscriptionAsync(string subscriptionId)

Parameters

subscriptionId string

The unique identifier of the subscription to remove.

Returns

ValueTask

A task representing the asynchronous operation.

Exceptions

KeyNotFoundException

Thrown if the subscription does not exist.

SaveAgentStateAsync(AgentId)

Saves the state of an agent. The result must be JSON serializable.

ValueTask<JsonElement> SaveAgentStateAsync(AgentId agentId)

Parameters

agentId AgentId

The ID of the agent whose state is being saved.

Returns

ValueTask<JsonElement>

A task representing the asynchronous operation, returning a dictionary of the saved state.

SendMessageAsync(object, AgentId, AgentId?, string?, CancellationToken)

Sends a message to an agent and gets a response. This method should be used to communicate directly with an agent.

ValueTask<object?> SendMessageAsync(object message, AgentId recepient, AgentId? sender = null, string? messageId = null, CancellationToken cancellationToken = default)

Parameters

message object

The message to send.

recepient AgentId

The agent to send the message to.

sender AgentId?

The agent sending the message. Should be null if sent from an external source.

messageId string

A unique identifier for the message. If null, a new ID will be generated.

cancellationToken CancellationToken

A token to cancel the operation if needed.

Returns

ValueTask<object>

A task representing the asynchronous operation, returning the response from the agent.

Exceptions

CantHandleException

Thrown if the recipient cannot handle the message.

UndeliverableException

Thrown if the message cannot be delivered.

TryGetAgentProxyAsync(AgentId)

Attempts to retrieve an AgentProxy for the specified agent.

ValueTask<AgentProxy> TryGetAgentProxyAsync(AgentId agentId)

Parameters

agentId AgentId

The ID of the agent.

Returns

ValueTask<AgentProxy>

A task representing the asynchronous operation, returning an AgentProxy if successful.