Skip to content

A programming framework for agentic AI

improving doc comments (#5550)

Ryan Sweet2a90731c441f
diff --git a/docs/dotnet/core/installation.md b/docs/dotnet/core/installation.md
index a2c980544..0c2ce8c6e 100644
--- a/docs/dotnet/core/installation.md
+++ b/docs/dotnet/core/installation.md
@@ -20,3 +20,29 @@ Or, add via `<PackageReference>`
<PackageReference Include="Microsoft.AutoGen.Contracts" Version="0.4.0-dev.1" />
<PackageReference Include="Microsoft.AutoGen.Core" Version="0.4.0-dev.1" />
```
+
+# 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
+```
\ No newline at end of file
diff --git a/dotnet/src/Microsoft.AutoGen/RuntimeGateway.Grpc/Abstractions/IConnection.cs b/dotnet/src/Microsoft.AutoGen/RuntimeGateway.Grpc/Abstractions/IConnection.cs
deleted file mode 100644
index a5044ff69..000000000
--- a/dotnet/src/Microsoft.AutoGen/RuntimeGateway.Grpc/Abstractions/IConnection.cs
+++ /dev/null
@@ -1,7 +0,0 @@
-// Copyright (c) Microsoft Corporation. All rights reserved.
-// IConnection.cs
-
-namespace Microsoft.AutoGen.RuntimeGateway.Grpc.Abstractions;
-public interface IConnection
-{
-}
diff --git a/dotnet/src/Microsoft.AutoGen/RuntimeGateway.Grpc/Abstractions/IGateway.cs b/dotnet/src/Microsoft.AutoGen/RuntimeGateway.Grpc/Abstractions/IGateway.cs
index b8aeae041..bd5b721dd 100644
--- a/dotnet/src/Microsoft.AutoGen/RuntimeGateway.Grpc/Abstractions/IGateway.cs
+++ b/dotnet/src/Microsoft.AutoGen/RuntimeGateway.Grpc/Abstractions/IGateway.cs
@@ -5,11 +5,45 @@ using Microsoft.AutoGen.Protobuf;
namespace Microsoft.AutoGen.RuntimeGateway.Grpc.Abstractions;
+/// <summary>
+/// Defines the gateway interface for handling RPC requests and subscriptions.
+/// Note that all of the request types are generated from the proto file.
+/// </summary>
public interface IGateway : IGrainObserver
{
+ /// <summary>
+ /// Invokes a request asynchronously.
+ /// </summary>
+ /// <param name="request">The RPC request.</param>
+ /// <returns>A task that represents the asynchronous operation. The task result contains the RPC response.</returns>
ValueTask<RpcResponse> InvokeRequestAsync(RpcRequest request);
+
+ /// <summary>
+ /// Registers an agent type asynchronously.
+ /// </summary>
+ /// <param name="request">The register agent type request.</param>
+ /// <param name="context">The server call context.</param>
+ /// <returns>A task that represents the asynchronous operation. The task result contains the register agent type response.</returns>
ValueTask<RegisterAgentTypeResponse> RegisterAgentTypeAsync(RegisterAgentTypeRequest request, ServerCallContext context);
+
+ /// <summary>
+ /// Subscribes to a topic asynchronously.
+ /// </summary>
+ /// <param name="request">The add subscription request.</param>
+ /// <returns>A task that represents the asynchronous operation. The task result contains the add subscription response.</returns>
ValueTask<AddSubscriptionResponse> SubscribeAsync(AddSubscriptionRequest request);
+
+ /// <summary>
+ /// Unsubscribes from a topic asynchronously.
+ /// </summary>
+ /// <param name="request">The remove subscription request.</param>
+ /// <returns>A task that represents the asynchronous operation. The task result contains the remove subscription response.</returns>
ValueTask<RemoveSubscriptionResponse> UnsubscribeAsync(RemoveSubscriptionRequest request);
+
+ /// <summary>
+ /// Gets the subscriptions asynchronously.
+ /// </summary>
+ /// <param name="request">The get subscriptions request.</param>
+ /// <returns>A task that represents the asynchronous operation. The task result contains the list of subscriptions.</returns>
ValueTask<List<Subscription>> GetSubscriptionsAsync(GetSubscriptionsRequest request);
}
diff --git a/dotnet/src/Microsoft.AutoGen/RuntimeGateway.Grpc/Abstractions/IGatewayRegistry.cs b/dotnet/src/Microsoft.AutoGen/RuntimeGateway.Grpc/Abstractions/IGatewayRegistry.cs
index 3d47696da..88ef86055 100644
--- a/dotnet/src/Microsoft.AutoGen/RuntimeGateway.Grpc/Abstractions/IGatewayRegistry.cs
+++ b/dotnet/src/Microsoft.AutoGen/RuntimeGateway.Grpc/Abstractions/IGatewayRegistry.cs
@@ -5,7 +5,7 @@ using Microsoft.AutoGen.Protobuf;
namespace Microsoft.AutoGen.RuntimeGateway.Grpc.Abstractions;
/// <summary>
-/// Interface for managing agent registration, placement, and subscriptions.
+/// Keeps track of which agents are registered with which gateways.
/// </summary>
public interface IGatewayRegistry : IRegistry
{
@@ -27,6 +27,7 @@ public interface IGatewayRegistry : IRegistry
/// Registers a new agent type with the specified worker.
/// </summary>
/// <param name="request">The request containing agent type details.</param>
+ /// <param name="clientId">The client ID of the worker.</param>
/// <param name="worker">The worker to register the agent type with.</param>
/// <returns>A task representing the asynchronous operation.</returns>
ValueTask RegisterAgentTypeAsync(RegisterAgentTypeRequest request, string clientId, IGateway worker);
diff --git a/dotnet/src/Microsoft.AutoGen/RuntimeGateway.Grpc/Abstractions/IRegistry.cs b/dotnet/src/Microsoft.AutoGen/RuntimeGateway.Grpc/Abstractions/IRegistry.cs
index 215ace6e5..f8b0a0a8e 100644
--- a/dotnet/src/Microsoft.AutoGen/RuntimeGateway.Grpc/Abstractions/IRegistry.cs
+++ b/dotnet/src/Microsoft.AutoGen/RuntimeGateway.Grpc/Abstractions/IRegistry.cs
@@ -5,7 +5,6 @@ namespace Microsoft.AutoGen.RuntimeGateway.Grpc.Abstractions;
public interface IRegistry
{
-
/// <summary>
/// Gets a list of agents subscribed to and handling the specified topic and event type.
/// </summary>
@@ -28,11 +27,12 @@ public interface IRegistry
/// <param name="request">The unsubscription request.</param>
/// <returns>A task representing the asynchronous operation.</returns>
/// <remarks>removing CancellationToken from here as it is not compatible with Orleans Serialization</remarks>
- ValueTask UnsubscribeAsync(RemoveSubscriptionRequest request); // TODO: This should have its own request type.
+ ValueTask UnsubscribeAsync(RemoveSubscriptionRequest request); // TODO: This should have its own request type.
/// <summary>
/// Gets the subscriptions for a specified agent type.
/// </summary>
+ /// <param name="request">The get subscriptions request.</param>
/// <returns>A task representing the asynchronous operation, with the subscriptions as the result.</returns>
ValueTask<List<Subscription>> GetSubscriptionsAsync(GetSubscriptionsRequest request);
}
diff --git a/dotnet/src/Microsoft.AutoGen/RuntimeGateway.Grpc/Services/Grpc/GrpcWorkerConnection.cs b/dotnet/src/Microsoft.AutoGen/RuntimeGateway.Grpc/Services/Grpc/GrpcWorkerConnection.cs
index 0cdfc9a28..a88430484 100644
--- a/dotnet/src/Microsoft.AutoGen/RuntimeGateway.Grpc/Services/Grpc/GrpcWorkerConnection.cs
+++ b/dotnet/src/Microsoft.AutoGen/RuntimeGateway.Grpc/Services/Grpc/GrpcWorkerConnection.cs
@@ -3,11 +3,10 @@
using System.Threading.Channels;
using Grpc.Core;
using Microsoft.AutoGen.Protobuf;
-using Microsoft.AutoGen.RuntimeGateway.Grpc.Abstractions;
namespace Microsoft.AutoGen.RuntimeGateway.Grpc;
-public sealed class GrpcWorkerConnection : IAsyncDisposable, IConnection
+public sealed class GrpcWorkerConnection : IAsyncDisposable
{
private static long s_nextConnectionId;
private Task _readTask = Task.CompletedTask;
@@ -57,6 +56,7 @@ public sealed class GrpcWorkerConnection : IAsyncDisposable, IConnection
private readonly Channel<Message> _outboundMessages;
+ /// <inheritdoc/>
public void AddSupportedType(string type)
{
lock (_lock)
@@ -65,6 +65,7 @@ public sealed class GrpcWorkerConnection : IAsyncDisposable, IConnection
}
}
+ /// <inheritdoc/>
public HashSet<string> GetSupportedTypes()
{
lock (_lock)
@@ -73,10 +74,13 @@ public sealed class GrpcWorkerConnection : IAsyncDisposable, IConnection
}
}
+ /// <inheritdoc/>
public async Task SendMessage(Message message)
{
await _outboundMessages.Writer.WriteAsync(message).ConfigureAwait(false);
}
+
+ /// <inheritdoc/>
public async Task RunReadPump()
{
await Task.CompletedTask.ConfigureAwait(ConfigureAwaitOptions.ForceYielding);
@@ -98,6 +102,7 @@ public sealed class GrpcWorkerConnection : IAsyncDisposable, IConnection
}
}
+ /// <inheritdoc/>
public async Task RunWritePump()
{
await Task.CompletedTask.ConfigureAwait(ConfigureAwaitOptions.ForceYielding);
@@ -117,11 +122,13 @@ public sealed class GrpcWorkerConnection : IAsyncDisposable, IConnection
}
}
+ /// <inheritdoc/>
public async ValueTask DisposeAsync()
{
_shutdownCancellationToken.Cancel();
await Completion.ConfigureAwait(ConfigureAwaitOptions.SuppressThrowing);
}
+ /// <inheritdoc/>
public override string ToString() => $"Connection-{_connectionId}";
}
diff --git a/dotnet/src/Microsoft.AutoGen/RuntimeGateway.Grpc/Services/Orleans/RegistryGrain.cs b/dotnet/src/Microsoft.AutoGen/RuntimeGateway.Grpc/Services/Orleans/RegistryGrain.cs
index 522c20614..48451c838 100644
--- a/dotnet/src/Microsoft.AutoGen/RuntimeGateway.Grpc/Services/Orleans/RegistryGrain.cs
+++ b/dotnet/src/Microsoft.AutoGen/RuntimeGateway.Grpc/Services/Orleans/RegistryGrain.cs
@@ -277,6 +277,7 @@ internal sealed class RegistryGrain([PersistentState("state", "AgentRegistryStor
}
return new(subscriptions);
}
+
private sealed class WorkerState
{
public HashSet<string> SupportedTypes { get; set; } = [];
diff --git a/dotnet/src/Microsoft.AutoGen/RuntimeGateway.Grpc/Services/Orleans/Surrogates/TypeSubscriptionSurrogate.cs b/dotnet/src/Microsoft.AutoGen/RuntimeGateway.Grpc/Services/Orleans/Surrogates/TypeSubscriptionSurrogate.cs
index 958c1c4d6..984bf78de 100644
--- a/dotnet/src/Microsoft.AutoGen/RuntimeGateway.Grpc/Services/Orleans/Surrogates/TypeSubscriptionSurrogate.cs
+++ b/dotnet/src/Microsoft.AutoGen/RuntimeGateway.Grpc/Services/Orleans/Surrogates/TypeSubscriptionSurrogate.cs
@@ -17,6 +17,11 @@ public struct TypeSubscriptionSurrogate
public sealed class TypeSubscriptionSurrogateConverter :
IConverter<TypeSubscription, TypeSubscriptionSurrogate>
{
+ /// <summary>
+ /// Converts from the surrogate to the original type.
+ /// </summary>
+ /// <param name="surrogate">The surrogate to convert from.</param>
+ /// <returns>The original type.</returns>
public TypeSubscription ConvertFromSurrogate(
in TypeSubscriptionSurrogate surrogate) =>
new TypeSubscription
@@ -25,6 +30,11 @@ public sealed class TypeSubscriptionSurrogateConverter :
AgentType = surrogate.AgentType
};
+ /// <summary>
+ /// Converts from the original type to the surrogate.
+ /// </summary>
+ /// <param name="value">The original type to convert from.</param>
+ /// <returns>The surrogate type.</returns>
public TypeSubscriptionSurrogate ConvertToSurrogate(
in TypeSubscription value) =>
new TypeSubscriptionSurrogate