From cb62407fb8efdfb47dd3ad28066cb449aed9a09e Mon Sep 17 00:00:00 2001 From: westey <164392973+westey-m@users.noreply.github.com> Date: Thu, 2 Oct 2025 15:18:22 +0100 Subject: [PATCH] .NET: Improve some core types xml docs (#1115) * Improve some core types xml docs * Consistent period usage --- .../AgentRunOptions.cs | 8 +++++ .../AgentRunResponse.cs | 5 +++ .../AgentRunResponseUpdate.cs | 3 ++ .../AgentThread.cs | 36 ++++++++++++++++++- 4 files changed, 51 insertions(+), 1 deletion(-) diff --git a/dotnet/src/Microsoft.Agents.AI.Abstractions/AgentRunOptions.cs b/dotnet/src/Microsoft.Agents.AI.Abstractions/AgentRunOptions.cs index aa7e4ce1d5..e845d055d5 100644 --- a/dotnet/src/Microsoft.Agents.AI.Abstractions/AgentRunOptions.cs +++ b/dotnet/src/Microsoft.Agents.AI.Abstractions/AgentRunOptions.cs @@ -8,6 +8,14 @@ namespace Microsoft.Agents.AI; /// /// Provides optional parameters and configuration settings for controlling agent run behavior. /// +/// +/// +/// This class currently has no options, but may be extended in the future to include additional configuration settings. +/// +/// +/// Implementations of may provide subclasses of with additional options specific to that agent type. +/// +/// public class AgentRunOptions { /// diff --git a/dotnet/src/Microsoft.Agents.AI.Abstractions/AgentRunResponse.cs b/dotnet/src/Microsoft.Agents.AI.Abstractions/AgentRunResponse.cs index 5cf3687046..b5714b5fc8 100644 --- a/dotnet/src/Microsoft.Agents.AI.Abstractions/AgentRunResponse.cs +++ b/dotnet/src/Microsoft.Agents.AI.Abstractions/AgentRunResponse.cs @@ -23,11 +23,16 @@ namespace Microsoft.Agents.AI; /// Represents the response to an run request, containing messages and metadata about the interaction. /// /// +/// /// provides one or more response messages and metadata about the response. /// A typical response will contain a single message, however a response may contain multiple messages /// in a variety of scenarios. For example, if the agent internally invokes functions or tools, performs /// RAG retrievals or has other complex logic, a single run by the agent may produce many messages showing /// the intermediate progress that the agent made towards producing the agent result. +/// +/// +/// To get the text result of the response, use the property or simply call on the . +/// /// public class AgentRunResponse { diff --git a/dotnet/src/Microsoft.Agents.AI.Abstractions/AgentRunResponseUpdate.cs b/dotnet/src/Microsoft.Agents.AI.Abstractions/AgentRunResponseUpdate.cs index f9f7b674dd..347ca8de5d 100644 --- a/dotnet/src/Microsoft.Agents.AI.Abstractions/AgentRunResponseUpdate.cs +++ b/dotnet/src/Microsoft.Agents.AI.Abstractions/AgentRunResponseUpdate.cs @@ -21,6 +21,9 @@ namespace Microsoft.Agents.AI; /// and in streaming output. /// /// +/// To get the text result of this response chunk, use the property or simply call on the . +/// +/// /// The relationship between and is /// codified in the and /// , which enable bidirectional conversions diff --git a/dotnet/src/Microsoft.Agents.AI.Abstractions/AgentThread.cs b/dotnet/src/Microsoft.Agents.AI.Abstractions/AgentThread.cs index 74a9383d24..fb5863a5c9 100644 --- a/dotnet/src/Microsoft.Agents.AI.Abstractions/AgentThread.cs +++ b/dotnet/src/Microsoft.Agents.AI.Abstractions/AgentThread.cs @@ -12,8 +12,42 @@ namespace Microsoft.Agents.AI; /// /// Base abstraction for all agent threads. -/// A thread represents a specific conversation with an agent. /// +/// +/// +/// An contains the state of a specific conversation with an agent which may include: +/// +/// Conversation history or a reference to externally stored conversation history. +/// Memories or a reference to externally stored memories. +/// Any other state that the agent needs to persist across runs for a conversation. +/// +/// +/// +/// An may also have behaviors attached to it that may include: +/// +/// Customized storage of state. +/// Data extraction from and injection into a conversation. +/// Chat history reduction, e.g. where messages needs to be summarized or truncated to reduce the size. +/// +/// An is always constructed by an so that the +/// can attach any necessary behaviors to the . See the +/// and methods for more information. +/// +/// +/// Because of these behaviors, an may not be reusable across different agents, since each agent +/// may add different behaviors to the it creates. +/// +/// +/// To support conversations that may need to survive application restarts or separate service requests, an can be serialized +/// and deserialized, so that it can be saved in a persistent store. +/// The provides the method to serialize the thread to a +/// and the method +/// can be used to deserialize the thread. +/// +/// +/// +/// +/// public abstract class AgentThread { ///