.NET: Improve some core types xml docs (#1115)

* Improve some core types xml docs

* Consistent period usage

dotnet/src/Microsoft.Agents.AI.Abstractions/AgentRunOptions.cs

@@ -8,6 +8,14 @@ namespace Microsoft.Agents.AI;
 /// <summary>
 /// Provides optional parameters and configuration settings for controlling agent run behavior.
 /// </summary>
+/// <remarks>
+/// <para>
+/// This class currently has no options, but may be extended in the future to include additional configuration settings.
+/// </para>
+/// <para>
+/// Implementations of <see cref="AIAgent"/> may provide subclasses of <see cref="AgentRunOptions"/> with additional options specific to that agent type.
+/// </para>
+/// </remarks>
 public class AgentRunOptions
 {
     /// <summary>

dotnet/src/Microsoft.Agents.AI.Abstractions/AgentRunResponse.cs

@@ -23,11 +23,16 @@ namespace Microsoft.Agents.AI;
 /// Represents the response to an <see cref="AIAgent"/> run request, containing messages and metadata about the interaction.
 /// </summary>
 /// <remarks>
+/// <para>
 /// <see cref="AgentRunResponse"/> 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.
+/// </para>
+/// <para>
+/// To get the text result of the response, use the <see cref="Text"/> property or simply call <see cref="ToString()"/> on the <see cref="AgentRunResponse"/>.
+/// </para>
 /// </remarks>
 public class AgentRunResponse
 {

dotnet/src/Microsoft.Agents.AI.Abstractions/AgentRunResponseUpdate.cs

@@ -21,6 +21,9 @@ namespace Microsoft.Agents.AI;
 /// <see cref="AgentRunResponse"/> and <see cref="ChatMessage"/> in streaming output.
 /// </para>
 /// <para>
+/// To get the text result of this response chunk, use the <see cref="Text"/> property or simply call <see cref="ToString()"/> on the <see cref="AgentRunResponseUpdate"/>.
+/// </para>
+/// <para>
 /// The relationship between <see cref="AgentRunResponse"/> and <see cref="AgentRunResponseUpdate"/> is
 /// codified in the <see cref="AgentRunResponseExtensions.ToAgentRunResponseAsync"/> and
 /// <see cref="AgentRunResponse.ToAgentRunResponseUpdates"/>, which enable bidirectional conversions

dotnet/src/Microsoft.Agents.AI.Abstractions/AgentThread.cs

@@ -12,8 +12,42 @@ namespace Microsoft.Agents.AI;
 
 /// <summary>
 /// Base abstraction for all agent threads.
-/// A thread represents a specific conversation with an agent.
 /// </summary>
+/// <remarks>
+/// <para>
+/// An <see cref="AgentThread"/> contains the state of a specific conversation with an agent which may include:
+/// <list type="bullet">
+/// <item><description>Conversation history or a reference to externally stored conversation history.</description></item>
+/// <item><description>Memories or a reference to externally stored memories.</description></item>
+/// <item><description>Any other state that the agent needs to persist across runs for a conversation.</description></item>
+/// </list>
+/// </para>
+/// <para>
+/// An <see cref="AgentThread"/> may also have behaviors attached to it that may include:
+/// <list type="bullet">
+/// <item><description>Customized storage of state.</description></item>
+/// <item><description>Data extraction from and injection into a conversation.</description></item>
+/// <item><description>Chat history reduction, e.g. where messages needs to be summarized or truncated to reduce the size.</description></item>
+/// </list>
+/// An <see cref="AgentThread"/> is always constructed by an <see cref="AIAgent"/> so that the <see cref="AIAgent"/>
+/// can attach any necessary behaviors to the <see cref="AgentThread"/>. See the <see cref="AIAgent.GetNewThread()"/>
+/// and <see cref="AIAgent.DeserializeThread(JsonElement, JsonSerializerOptions?)"/> methods for more information.
+/// </para>
+/// <para>
+/// Because of these behaviors, an <see cref="AgentThread"/> may not be reusable across different agents, since each agent
+/// may add different behaviors to the <see cref="AgentThread"/> it creates.
+/// </para>
+/// <para>
+/// To support conversations that may need to survive application restarts or separate service requests, an <see cref="AgentThread"/> can be serialized
+/// and deserialized, so that it can be saved in a persistent store.
+/// The <see cref="AgentThread"/> provides the <see cref="Serialize(JsonSerializerOptions?)"/> method to serialize the thread to a
+/// <see cref="JsonElement"/> and the <see cref="AIAgent.DeserializeThread(JsonElement, JsonSerializerOptions?)"/> method
+/// can be used to deserialize the thread.
+/// </para>
+/// </remarks>
+/// <seealso cref="AIAgent"/>
+/// <seealso cref="AIAgent.GetNewThread()"/>
+/// <seealso cref="AIAgent.DeserializeThread(JsonElement, JsonSerializerOptions?)"/>
 public abstract class AgentThread
 {
     /// <summary>