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.mdindex 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 filediff --git a/dotnet/src/Microsoft.AutoGen/RuntimeGateway.Grpc/Abstractions/IConnection.cs b/dotnet/src/Microsoft.AutoGen/RuntimeGateway.Grpc/Abstractions/IConnection.csdeleted file mode 100644index 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.csindex 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.csindex 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.csindex 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.csindex 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, IConnectionprivate 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.csindex 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.csindex 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 TypeSubscriptionSurrogatepublic 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