Skip to content

A programming framework for agentic AI

add dotnet exceptions and IAgent xml docs

Griffin Bassman271accbc0e89
diff --git a/dotnet/src/Microsoft.AutoGen/Contracts/PythonEquiv/AgentExceptions.cs b/dotnet/src/Microsoft.AutoGen/Contracts/PythonEquiv/AgentExceptions.cs
new file mode 100644
index 000000000..5f17ddf6c
--- /dev/null
+++ b/dotnet/src/Microsoft.AutoGen/Contracts/PythonEquiv/AgentExceptions.cs
@@ -0,0 +1,35 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// AgentExceptions.cs
+
+namespace Microsoft.AutoGen.Contracts.Python;
+
+public class CantHandleException : Exception
+{
+ public CantHandleException() : base("The handler cannot process the given message.") { }
+ public CantHandleException(string message) : base(message) { }
+ public CantHandleException(string message, Exception innerException) : base(message, innerException) { }
+}
+
+/// <summary>
+/// Exception thrown when a message cannot be delivered.
+/// </summary>
+public class UndeliverableException : Exception
+{
+ public UndeliverableException() : base("The message cannot be delivered.") { }
+ public UndeliverableException(string message) : base(message) { }
+ public UndeliverableException(string message, Exception innerException) : base(message, innerException) { }
+}
+
+public class MessageDroppedException : Exception
+{
+ public MessageDroppedException() : base("The message was dropped.") { }
+ public MessageDroppedException(string message) : base(message) { }
+ public MessageDroppedException(string message, Exception innerException) : base(message, innerException) { }
+}
+
+public class NotAccessibleError : Exception
+{
+ public NotAccessibleError() : base("The requested value is not accessible.") { }
+ public NotAccessibleError(string message) : base(message) { }
+ public NotAccessibleError(string message, Exception innerException) : base(message, innerException) { }
+}
diff --git a/dotnet/src/Microsoft.AutoGen/Contracts/PythonEquiv/IAgent.cs b/dotnet/src/Microsoft.AutoGen/Contracts/PythonEquiv/IAgent.cs
index f6a12a751..e3ecfe7d0 100644
--- a/dotnet/src/Microsoft.AutoGen/Contracts/PythonEquiv/IAgent.cs
+++ b/dotnet/src/Microsoft.AutoGen/Contracts/PythonEquiv/IAgent.cs
@@ -3,16 +3,44 @@
namespace Microsoft.AutoGen.Contracts.Python;
+/// <summary>
+/// Represents an agent within the runtime that can process messages, maintain state, and be closed when no longer needed.
+/// </summary>
public interface IAgent : ISaveState<IAgent>
{
+ /// <summary>
+ /// Gets the unique identifier of the agent.
+ /// </summary>
public AgentId Id { get; }
+
+ /// <summary>
+ /// Gets metadata associated with the agent.
+ /// </summary>
public AgentMetadata Metadata { get; }
+ /// <summary>
+ /// Handles an incoming message for the agent.
+ /// This should only be called by the runtime, not by other agents.
+ /// </summary>
+ /// <param name="message">The received message. The type should match one of the expected subscription types.</param>
+ /// <param name="messageContext">The context of the message, providing additional metadata.</param>
+ /// <returns>
+ /// A task representing the asynchronous operation, returning a response to the message.
+ /// The response can be <c>null</c> if no reply is necessary.
+ /// </returns>
+ /// <exception cref="OperationCanceledException">Thrown if the message was cancelled.</exception>
+ /// <exception cref="CantHandleException">Thrown if the agent cannot handle the message.</exception>
public ValueTask<object?> OnMessageAsync(object message, MessageContext messageContext); // TODO: How do we express this properly in .NET?
}
-
+/// <summary>
+/// Represents an agent that can be explicitly hosted and closed when the runtime shuts down.
+/// </summary>
public interface IHostableAgent : IAgent
{
+ /// <summary>
+ /// Called when the runtime is closing.
+ /// </summary>
+ /// <returns>A task representing the asynchronous operation.</returns>
public ValueTask CloseAsync() => ValueTask.CompletedTask;
}
diff --git a/dotnet/src/Microsoft.AutoGen/Contracts/PythonEquiv/IAgentRuntime.cs b/dotnet/src/Microsoft.AutoGen/Contracts/PythonEquiv/IAgentRuntime.cs
index 60dbb746d..3630f42ca 100644
--- a/dotnet/src/Microsoft.AutoGen/Contracts/PythonEquiv/IAgentRuntime.cs
+++ b/dotnet/src/Microsoft.AutoGen/Contracts/PythonEquiv/IAgentRuntime.cs
@@ -5,6 +5,9 @@ using StateDict = System.Collections.Generic.IDictionary<string, object>;
namespace Microsoft.AutoGen.Contracts.Python;
+/// <summary>
+/// Defines the runtime environment for agents, managing message sending, subscriptions, agent resolution, and state persistence.
+/// </summary>
public interface IAgentRuntime : ISaveState<IAgentRuntime>
{
public ValueTask<object?> SendMessageAsync(object message, AgentId recepient, AgentId? sender = null, string? messageId = null, CancellationToken? cancellationToken = default);