Document JSON schema derivation for return types in AIFunctionFactory (#7400)

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: stephentoub <2642209+stephentoub@users.noreply.github.com>

Author: 2 people

src/Libraries/Microsoft.Extensions.AI.Abstractions/Functions/AIFunctionDeclaration.cs

@@ -40,15 +40,29 @@ protected AIFunctionDeclaration()
     /// The metadata present in the schema document plays an important role in guiding AI function invocation.
     /// </para>
     /// <para>
+    /// When an <see cref="AIFunction"/> is created via <see cref="AIFunctionFactory"/>, this schema is automatically derived from the
+    /// method's parameters using the configured <see cref="JsonSerializerOptions"/> and <see cref="AIJsonSchemaCreateOptions"/>.
+    /// </para>
+    /// <para>
     /// When no schema is specified, consuming chat clients should assume the "{}" or "true" schema, indicating that any JSON input is admissible.
     /// </para>
     /// </remarks>
     public virtual JsonElement JsonSchema => AIJsonUtilities.DefaultJsonSchema;
 
     /// <summary>Gets a JSON Schema describing the function's return value.</summary>
     /// <remarks>
-    /// A <see langword="null"/> typically reflects a function that doesn't specify a return schema
-    /// or a function that returns <see cref="void"/>, <see cref="Task"/>, or <see cref="ValueTask"/>.
+    /// <para>
+    /// When an <see cref="AIFunction"/> is created via <see cref="AIFunctionFactory"/>, this schema is automatically derived from the
+    /// method's return type using the configured <see cref="JsonSerializerOptions"/> and <see cref="AIJsonSchemaCreateOptions"/>.
+    /// For methods returning <see cref="Task{TResult}"/> or <see cref="ValueTask{TResult}"/>, the schema is based on the
+    /// unwrapped result type. Return schema generation can be excluded by setting
+    /// <see cref="AIFunctionFactoryOptions.ExcludeResultSchema"/> to <see langword="true"/>.
+    /// </para>
+    /// <para>
+    /// A <see langword="null"/> value typically reflects a function that doesn't specify a return schema,
+    /// a function that returns <see cref="void"/>, <see cref="Task"/>, or <see cref="ValueTask"/>,
+    /// or a function for which <see cref="AIFunctionFactoryOptions.ExcludeResultSchema"/> was set to <see langword="true"/>.
+    /// </para>
     /// </remarks>
     public virtual JsonElement? ReturnJsonSchema => null;
 }

src/Libraries/Microsoft.Extensions.AI.Abstractions/Functions/AIFunctionFactory.cs

@@ -27,6 +27,19 @@
 namespace Microsoft.Extensions.AI;
 
 /// <summary>Provides factory methods for creating commonly-used implementations of <see cref="AIFunction"/>.</summary>
+/// <remarks>
+/// <para>
+/// The <see cref="AIFunctionFactory"/> class creates <see cref="AIFunction"/> instances that wrap .NET methods
+/// (specified as <see cref="Delegate"/> or <see cref="MethodInfo"/>). As part of this process, JSON schemas are
+/// automatically derived for both the function's input parameters (exposed via <see cref="AIFunctionDeclaration.JsonSchema"/>)
+/// and, by default, the function's return type (exposed via <see cref="AIFunctionDeclaration.ReturnJsonSchema"/>).
+/// These schemas are produced using the <see cref="AIFunctionFactoryOptions.SerializerOptions"/> and
+/// <see cref="AIFunctionFactoryOptions.JsonSchemaCreateOptions"/>, and enable AI services to understand and
+/// interact with the function. Return value serialization and schema derivation behavior can be customized
+/// via <see cref="AIFunctionFactoryOptions.MarshalResult"/> and <see cref="AIFunctionFactoryOptions.ExcludeResultSchema"/>,
+/// respectively.
+/// </para>
+/// </remarks>
 /// <related type="Article" href="https://learn.microsoft.com/dotnet/ai/quickstarts/use-function-calling">Invoke .NET functions using an AI model.</related>
 public static partial class AIFunctionFactory
 {
@@ -98,7 +111,14 @@ public static partial class AIFunctionFactory
     /// special-cased and are not serialized: the created function returns the original instance(s) directly to enable
     /// callers (such as an <c>IChatClient</c>) to perform type tests and implement specialized handling. If
     /// <see cref="AIFunctionFactoryOptions.MarshalResult"/> is supplied, that delegate governs the behavior instead.
-    /// Handling of return values can be overridden via <see cref="AIFunctionFactoryOptions.MarshalResult"/>.
+    /// </para>
+    /// <para>
+    /// In addition to the parameter schema, a JSON schema is also derived from the method's return type and exposed via the
+    /// returned <see cref="AIFunction"/>'s <see cref="AIFunctionDeclaration.ReturnJsonSchema"/>. For methods returning
+    /// <see cref="void"/>, <see cref="Task"/>, or <see cref="ValueTask"/>, no return schema is produced (the property is <see langword="null"/>).
+    /// For methods returning <see cref="Task{TResult}"/> or <see cref="ValueTask{TResult}"/>, the schema is derived from the
+    /// unwrapped result type. Return schema generation can be excluded via <see cref="AIFunctionFactoryOptions.ExcludeResultSchema"/>,
+    /// and its generation is governed by <paramref name="options"/>'s <see cref="AIFunctionFactoryOptions.JsonSchemaCreateOptions"/>.
     /// </para>
     /// </remarks>
     /// <exception cref="ArgumentNullException"><paramref name="method"/> is <see langword="null"/>.</exception>
@@ -169,6 +189,11 @@ public static AIFunction Create(Delegate method, AIFunctionFactoryOptions? optio
     /// derived type of <see cref="AIContent"/>, or any type assignable from <see cref="IEnumerable{AIContent}"/> are not serialized;
     /// they are returned as-is to facilitate specialized handling.
     /// </para>
+    /// <para>
+    /// A JSON schema is also derived from the method's return type and exposed via <see cref="AIFunctionDeclaration.ReturnJsonSchema"/>.
+    /// For methods returning <see cref="void"/>, <see cref="Task"/>, or <see cref="ValueTask"/>, no return schema is produced.
+    /// For methods returning <see cref="Task{TResult}"/> or <see cref="ValueTask{TResult}"/>, the schema is derived from the unwrapped result type.
+    /// </para>
     /// </remarks>
     /// <exception cref="ArgumentNullException"><paramref name="method"/> is <see langword="null"/>.</exception>
     /// <exception cref="JsonException">A parameter to <paramref name="method"/> is not serializable.</exception>
@@ -255,6 +280,14 @@ public static AIFunction Create(Delegate method, string? name = null, string? de
     /// any type assignable from <see cref="IEnumerable{AIContent}"/> are not serialized and are instead returned directly.
     /// Handling of return values can be overridden via <see cref="AIFunctionFactoryOptions.MarshalResult"/>.
     /// </para>
+    /// <para>
+    /// In addition to the parameter schema, a JSON schema is also derived from the method's return type and exposed via the
+    /// returned <see cref="AIFunction"/>'s <see cref="AIFunctionDeclaration.ReturnJsonSchema"/>. For methods returning
+    /// <see cref="void"/>, <see cref="Task"/>, or <see cref="ValueTask"/>, no return schema is produced (the property is <see langword="null"/>).
+    /// For methods returning <see cref="Task{TResult}"/> or <see cref="ValueTask{TResult}"/>, the schema is derived from the
+    /// unwrapped result type. Return schema generation can be excluded via <see cref="AIFunctionFactoryOptions.ExcludeResultSchema"/>,
+    /// and its generation is governed by <paramref name="options"/>'s <see cref="AIFunctionFactoryOptions.JsonSchemaCreateOptions"/>.
+    /// </para>
     /// </remarks>
     /// <exception cref="ArgumentNullException"><paramref name="method"/> is <see langword="null"/>.</exception>
     /// <exception cref="ArgumentNullException"><paramref name="method"/> represents an instance method but <paramref name="target"/> is null.</exception>
@@ -334,6 +367,11 @@ public static AIFunction Create(MethodInfo method, object? target, AIFunctionFac
     /// derived type of <see cref="AIContent"/>, or any type assignable from <see cref="IEnumerable{AIContent}"/> are returned
     /// without serialization to enable specialized handling.
     /// </para>
+    /// <para>
+    /// A JSON schema is also derived from the method's return type and exposed via <see cref="AIFunctionDeclaration.ReturnJsonSchema"/>.
+    /// For methods returning <see cref="void"/>, <see cref="Task"/>, or <see cref="ValueTask"/>, no return schema is produced.
+    /// For methods returning <see cref="Task{TResult}"/> or <see cref="ValueTask{TResult}"/>, the schema is derived from the unwrapped result type.
+    /// </para>
     /// </remarks>
     /// <exception cref="ArgumentNullException"><paramref name="method"/> is <see langword="null"/>.</exception>
     /// <exception cref="ArgumentNullException"><paramref name="method"/> represents an instance method but <paramref name="target"/> is null.</exception>
@@ -433,6 +471,14 @@ public static AIFunction Create(MethodInfo method, object? target, string? name
     /// assignable from <see cref="IEnumerable{AIContent}"/> are returned directly without serialization.
     /// Handling of return values can be overridden via <see cref="AIFunctionFactoryOptions.MarshalResult"/>.
     /// </para>
+    /// <para>
+    /// In addition to the parameter schema, a JSON schema is also derived from the method's return type and exposed via the
+    /// returned <see cref="AIFunction"/>'s <see cref="AIFunctionDeclaration.ReturnJsonSchema"/>. For methods returning
+    /// <see cref="void"/>, <see cref="Task"/>, or <see cref="ValueTask"/>, no return schema is produced (the property is <see langword="null"/>).
+    /// For methods returning <see cref="Task{TResult}"/> or <see cref="ValueTask{TResult}"/>, the schema is derived from the
+    /// unwrapped result type. Return schema generation can be excluded via <see cref="AIFunctionFactoryOptions.ExcludeResultSchema"/>,
+    /// and its generation is governed by <paramref name="options"/>'s <see cref="AIFunctionFactoryOptions.JsonSchemaCreateOptions"/>.
+    /// </para>
     /// </remarks>
     /// <exception cref="ArgumentNullException"><paramref name="method"/> is <see langword="null"/>.</exception>
     /// <exception cref="ArgumentNullException"><paramref name="createInstanceFunc"/> is <see langword="null"/>.</exception>

src/Libraries/Microsoft.Extensions.AI.Abstractions/Functions/AIFunctionFactoryOptions.cs

@@ -30,10 +30,13 @@ public AIFunctionFactoryOptions()
     public JsonSerializerOptions? SerializerOptions { get; set; }
 
     /// <summary>
-    /// Gets or sets the <see cref="AIJsonSchemaCreateOptions"/> governing the generation of JSON schemas for the function.
+    /// Gets or sets the <see cref="AIJsonSchemaCreateOptions"/> governing the generation of JSON schemas for
+    /// the function's input parameters and return type.
     /// </summary>
     /// <remarks>
     /// If no value has been specified, the <see cref="AIJsonSchemaCreateOptions.Default"/> instance will be used.
+    /// This setting affects both the <see cref="AIFunctionDeclaration.JsonSchema"/> (input parameters) and
+    /// the <see cref="AIFunctionDeclaration.ReturnJsonSchema"/> (return type).
     /// </remarks>
     public AIJsonSchemaCreateOptions? JsonSchemaCreateOptions { get; set; }
 
@@ -107,14 +110,16 @@ public AIFunctionFactoryOptions()
     public Func<object?, Type?, CancellationToken, ValueTask<object?>>? MarshalResult { get; set; }
 
     /// <summary>
-    /// Gets or sets a value indicating whether a schema should be created for the function's result type, if possible, and included as <see cref="AIFunctionDeclaration.ReturnJsonSchema" />.
+    /// Gets or sets a value indicating whether to exclude generation of a JSON schema for the function's return type.
     /// </summary>
     /// <remarks>
     /// <para>
-    /// The default value is <see langword="false"/>.
+    /// The default value is <see langword="false"/>, meaning a return type schema will be generated and exposed
+    /// via <see cref="AIFunctionDeclaration.ReturnJsonSchema"/> when the method has a return type other than
+    /// <see cref="void"/>, <see cref="Task"/>, or <see cref="ValueTask"/>.
     /// </para>
     /// <para>
-    /// When set to <see langword="true"/>, results in the produced <see cref="AIFunctionDeclaration.ReturnJsonSchema"/> to always be <see langword="null"/>.
+    /// When set to <see langword="true"/>, the produced <see cref="AIFunctionDeclaration.ReturnJsonSchema"/> will always be <see langword="null"/>.
     /// </para>
     /// </remarks>
     public bool ExcludeResultSchema { get; set; }