Implement targeted AI function and parameter name attributes

Author: Copilot

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

@@ -135,7 +135,8 @@ public static AIFunction Create(Delegate method, AIFunctionFactoryOptions? optio
     /// <param name="method">The method to be represented via the created <see cref="AIFunction"/>.</param>
     /// <param name="name">
     /// The name to use for the <see cref="AIFunction"/>. If <see langword="null"/>, the name will be derived from
-    /// any <see cref="DisplayNameAttribute"/> on <paramref name="method"/>, if available, or else from the name of <paramref name="method"/>.
+    /// any <see cref="AIFunctionNameAttribute"/> on <paramref name="method"/>, then from any <see cref="DisplayNameAttribute"/>
+    /// on <paramref name="method"/>, if available, or else from the name of <paramref name="method"/>.
     /// </param>
     /// <param name="description">
     /// The description to use for the <see cref="AIFunction"/>. If <see langword="null"/>, a description will be derived from
@@ -313,7 +314,8 @@ public static AIFunction Create(MethodInfo method, object? target, AIFunctionFac
     /// </param>
     /// <param name="name">
     /// The name to use for the <see cref="AIFunction"/>. If <see langword="null"/>, the name will be derived from
-    /// any <see cref="DisplayNameAttribute"/> on <paramref name="method"/>, if available, or else from the name of <paramref name="method"/>.
+    /// any <see cref="AIFunctionNameAttribute"/> on <paramref name="method"/>, then from any <see cref="DisplayNameAttribute"/>
+    /// on <paramref name="method"/>, if available, or else from the name of <paramref name="method"/>.
     /// </param>
     /// <param name="description">
     /// The description to use for the <see cref="AIFunction"/>. If <see langword="null"/>, a description will be derived from
@@ -806,7 +808,7 @@ private ReflectionAIFunctionDescriptor(DescriptorKey key, JsonSerializerOptions
                     pType != typeof(IServiceProvider) &&
                     !string.IsNullOrEmpty(parameters[i].Name))
                 {
-                    _ = expectedArgumentNames.Add(parameters[i].Name!);
+                    _ = expectedArgumentNames.Add(AIJsonUtilities.GetParameterSchemaName(parameters[i]));
                 }
             }
 
@@ -815,7 +817,7 @@ private ReflectionAIFunctionDescriptor(DescriptorKey key, JsonSerializerOptions
 
             ReturnParameterMarshaller = GetReturnParameterMarshaller(key, serializerOptions, out Type? returnType);
             Method = key.Method;
-            Name = key.Name ?? key.Method.GetCustomAttribute<DisplayNameAttribute>(inherit: true)?.DisplayName ?? GetFunctionName(key.Method);
+            Name = key.Name ?? key.Method.GetCustomAttribute<AIFunctionNameAttribute>(inherit: true)?.Name ?? key.Method.GetCustomAttribute<DisplayNameAttribute>(inherit: true)?.DisplayName ?? GetFunctionName(key.Method);
             Description = key.Description ?? key.Method.GetCustomAttribute<DescriptionAttribute>(inherit: true)?.Description ?? string.Empty;
             JsonSerializerOptions = serializerOptions;
             ReturnJsonSchema = returnType is null || key.ExcludeResultSchema ? null : AIJsonUtilities.CreateJsonSchema(
@@ -949,10 +951,11 @@ static bool IsAsyncMethod(MethodInfo method)
             // Resolve the contract used to marshal the value from JSON -- can throw if not supported or not found.
             JsonTypeInfo? typeInfo = serializerOptions.GetTypeInfo(parameterType);
             bool hasDefaultValue = AIJsonUtilities.TryGetEffectiveDefaultValue(parameter, out object? effectiveDefaultValue);
+            string argumentName = AIJsonUtilities.GetParameterSchemaName(parameter);
             return (arguments, _) =>
             {
                 // If the parameter has an argument specified in the dictionary, return that argument.
-                if (arguments.TryGetValue(parameter.Name, out object? value))
+                if (arguments.TryGetValue(argumentName, out object? value))
                 {
                     return value switch
                     {
@@ -999,7 +1002,7 @@ static bool IsAsyncMethod(MethodInfo method)
                 // If the parameter is required and there's no argument specified for it, throw.
                 if (!hasDefaultValue)
                 {
-                    Throw.ArgumentException(nameof(arguments), $"The arguments dictionary is missing a value for the required parameter '{parameter.Name}'.");
+                    Throw.ArgumentException(nameof(arguments), $"The arguments dictionary is missing a value for the required parameter '{argumentName}'.");
                 }
 
                 // Otherwise, use the optional parameter's default value.

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

@@ -50,7 +50,7 @@ public AIFunctionFactoryOptions()
 
     /// <summary>Gets or sets the name to use for the function.</summary>
     /// <value>
-    /// The name to use for the function. The default value is a name derived from the passed <see cref="Delegate"/> or <see cref="MethodInfo"/> (for example, via a <see cref="DisplayNameAttribute"/> on the method).
+    /// The name to use for the function. The default value is a name derived from the passed <see cref="Delegate"/> or <see cref="MethodInfo"/> (for example, via an <see cref="AIFunctionNameAttribute"/> or <see cref="DisplayNameAttribute"/> on the method).
     /// </value>
     public string? Name { get; set; }
 

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

@@ -0,0 +1,31 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System;
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Shared.DiagnosticIds;
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Extensions.AI;
+
+/// <summary>Specifies the name to use for an <see cref="AIFunction"/>.</summary>
+/// <remarks>
+/// The name is the identifier a model sees and uses to invoke a function.
+/// By default this is inferred from .NET metadata. Apply this attribute to use a different identifier.
+/// </remarks>
+[AttributeUsage(AttributeTargets.Method, AllowMultiple = false, Inherited = true)]
+[Experimental(DiagnosticIds.Experiments.AIFunctionName, UrlFormat = DiagnosticIds.UrlFormat)]
+public sealed class AIFunctionNameAttribute : Attribute
+{
+    /// <summary>Initializes a new instance of the <see cref="AIFunctionNameAttribute"/> class.</summary>
+    /// <param name="name">The name to use for the function.</param>
+    /// <exception cref="ArgumentNullException"><paramref name="name"/> is <see langword="null"/>.</exception>
+    /// <exception cref="ArgumentException"><paramref name="name"/> is empty or composed entirely of whitespace.</exception>
+    public AIFunctionNameAttribute(string name)
+    {
+        Name = Throw.IfNullOrWhitespace(name);
+    }
+
+    /// <summary>Gets the name to use for the function.</summary>
+    public string Name { get; }
+}

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

@@ -0,0 +1,31 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System;
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Shared.DiagnosticIds;
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Extensions.AI;
+
+/// <summary>Specifies the schema name to use for an <see cref="AIFunction"/> parameter.</summary>
+/// <remarks>
+/// The name is the identifier a model sees and uses when supplying an argument to a function.
+/// By default this is inferred from .NET metadata. Apply this attribute to use a different identifier.
+/// </remarks>
+[AttributeUsage(AttributeTargets.Parameter, AllowMultiple = false, Inherited = true)]
+[Experimental(DiagnosticIds.Experiments.AIParameterName, UrlFormat = DiagnosticIds.UrlFormat)]
+public sealed class AIParameterNameAttribute : Attribute
+{
+    /// <summary>Initializes a new instance of the <see cref="AIParameterNameAttribute"/> class.</summary>
+    /// <param name="name">The schema name to use for the parameter.</param>
+    /// <exception cref="ArgumentNullException"><paramref name="name"/> is <see langword="null"/>.</exception>
+    /// <exception cref="ArgumentException"><paramref name="name"/> is empty or composed entirely of whitespace.</exception>
+    public AIParameterNameAttribute(string name)
+    {
+        Name = Throw.IfNullOrWhitespace(name);
+    }
+
+    /// <summary>Gets the schema name to use for the parameter.</summary>
+    public string Name { get; }
+}

src/Libraries/Microsoft.Extensions.AI.Abstractions/Microsoft.Extensions.AI.Abstractions.json

@@ -417,6 +417,38 @@
         }
       ]
     },
+    {
+      "Type": "sealed class Microsoft.Extensions.AI.AIFunctionNameAttribute : System.Attribute",
+      "Stage": "Experimental",
+      "Methods": [
+        {
+          "Member": "Microsoft.Extensions.AI.AIFunctionNameAttribute.AIFunctionNameAttribute(string name);",
+          "Stage": "Experimental"
+        }
+      ],
+      "Properties": [
+        {
+          "Member": "string Microsoft.Extensions.AI.AIFunctionNameAttribute.Name { get; }",
+          "Stage": "Experimental"
+        }
+      ]
+    },
+    {
+      "Type": "sealed class Microsoft.Extensions.AI.AIParameterNameAttribute : System.Attribute",
+      "Stage": "Experimental",
+      "Methods": [
+        {
+          "Member": "Microsoft.Extensions.AI.AIParameterNameAttribute.AIParameterNameAttribute(string name);",
+          "Stage": "Experimental"
+        }
+      ],
+      "Properties": [
+        {
+          "Member": "string Microsoft.Extensions.AI.AIParameterNameAttribute.Name { get; }",
+          "Stage": "Experimental"
+        }
+      ]
+    },
     {
       "Type": "readonly struct Microsoft.Extensions.AI.AIJsonSchemaCreateContext",
       "Stage": "Stable",

src/Libraries/Microsoft.Extensions.AI.Abstractions/Utilities/AIJsonUtilities.Schema.Create.cs

@@ -10,6 +10,7 @@
 using System.Diagnostics.CodeAnalysis;
 using System.Reflection;
 using System.Runtime.CompilerServices;
+using System.Text;
 using System.Text.Json;
 using System.Text.Json.Nodes;
 using System.Text.Json.Schema;
@@ -128,14 +129,20 @@ public static JsonElement CreateFunctionJsonSchema(
                 serializerOptions,
                 inferenceOptions);
 
-            parameterSchemas.Add(parameter.Name, parameterSchema);
+            string parameterSchemaName = GetParameterSchemaName(parameter);
+            if (parameterSchemas.ContainsKey(parameterSchemaName))
+            {
+                Throw.ArgumentException(nameof(method), $"Multiple parameters are mapped to the same name '{parameterSchemaName}'. Ensure that any {nameof(AIParameterNameAttribute)} values do not collide with each other or with other parameter names.");
+            }
+
+            parameterSchemas.Add(parameterSchemaName, parameterSchema);
             bool isRequired = !parameter.IsOptional && !hasDefaultValue;
 #if NET || NETFRAMEWORK
             isRequired = isRequired || parameter.GetCustomAttribute<RequiredAttribute>(inherit: true) is not null;
 #endif
             if (isRequired)
             {
-                (requiredProperties ??= []).Add((JsonNode)parameter.Name);
+                (requiredProperties ??= []).Add((JsonNode)parameterSchemaName);
             }
         }
 
@@ -282,12 +289,14 @@ JsonNode TransformSchemaNode(JsonSchemaExporterContext schemaExporterContext, Js
                 // to accommodate the fact that they're being nested inside of a higher-level schema.
                 if (parameter?.Name is not null && objSchema.TryGetPropertyValue(RefPropertyName, out JsonNode? paramName))
                 {
-                    // Fix up any $ref URIs to match the path from the root document.
+                    // Fix up any $ref URIs to match the path from the root document. The schema name becomes a
+                    // JSON Pointer segment, so escape it per RFC 6901 ('~' => "~0", '/' => "~1").
+                    string parameterSchemaName = EscapeJsonPointerSegment(GetParameterSchemaName(parameter));
                     string refUri = paramName!.GetValue<string>();
                     Debug.Assert(refUri is "#" || refUri.StartsWith("#/", StringComparison.Ordinal), $"Expected {nameof(refUri)} to be either # or start with #/, got {refUri}");
                     refUri = refUri == "#"
-                        ? $"#/{PropertiesPropertyName}/{parameter.Name}"
-                        : $"#/{PropertiesPropertyName}/{parameter.Name}/{refUri.AsMemory("#/".Length)}";
+                        ? $"#/{PropertiesPropertyName}/{parameterSchemaName}"
+                        : $"#/{PropertiesPropertyName}/{parameterSchemaName}/{refUri.AsMemory("#/".Length)}";
 
                     objSchema[RefPropertyName] = (JsonNode)refUri;
                 }
@@ -861,6 +870,30 @@ internal static bool TryGetEffectiveDefaultValue(ParameterInfo parameterInfo, ou
         return false;
     }
 
+    internal static string GetParameterSchemaName(ParameterInfo parameter) =>
+        parameter.GetCustomAttribute<AIParameterNameAttribute>(inherit: true)?.Name ?? parameter.Name!;
+
+    private static string EscapeJsonPointerSegment(string segment)
+    {
+        if (segment.IndexOfAny(['~', '/']) < 0)
+        {
+            return segment;
+        }
+
+        StringBuilder sb = new(segment.Length + 2);
+        foreach (char c in segment)
+        {
+            _ = c switch
+            {
+                '~' => sb.Append("~0"),
+                '/' => sb.Append("~1"),
+                _ => sb.Append(c),
+            };
+        }
+
+        return sb.ToString();
+    }
+
     /// <summary>
     /// Checks whether a parameter is an F# optional parameter declared with the ?param syntax.
     /// F# optional parameters are annotated with Microsoft.FSharp.Core.OptionalArgumentAttribute

src/Shared/DiagnosticIds/DiagnosticIds.cs

@@ -54,6 +54,8 @@ internal static class Experiments
         internal const string AIMcpServers = AIExperiments;
         internal const string AIFunctionApprovals = AIExperiments;
         internal const string AIApprovalsInvocationRequired = AIExperiments;
+        internal const string AIFunctionName = AIExperiments;
+        internal const string AIParameterName = AIExperiments;
 
         internal const string AIChatReduction = AIExperiments;
         internal const string AIToolSearch = AIExperiments;

test/Libraries/Microsoft.Extensions.AI.Abstractions.Tests/Functions/AINameAttributesTests.cs

@@ -0,0 +1,24 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System;
+using Xunit;
+
+namespace Microsoft.Extensions.AI;
+
+public class AINameAttributesTests
+{
+    [Fact]
+    public void AIFunctionNameAttribute_InvalidArguments_Throw()
+    {
+        Assert.Throws<ArgumentNullException>("name", () => new AIFunctionNameAttribute(null!));
+        Assert.Throws<ArgumentException>("name", () => new AIFunctionNameAttribute(" "));
+    }
+
+    [Fact]
+    public void AIParameterNameAttribute_InvalidArguments_Throw()
+    {
+        Assert.Throws<ArgumentNullException>("name", () => new AIParameterNameAttribute(null!));
+        Assert.Throws<ArgumentException>("name", () => new AIParameterNameAttribute(" "));
+    }
+}

test/Libraries/Microsoft.Extensions.AI.Abstractions.Tests/Utilities/AIJsonUtilitiesTests.cs

@@ -580,6 +580,52 @@ static void TestMethod()
         Assert.Equal("override_title", titleElement.GetString());
     }
 
+    [Fact]
+    public static void CreateFunctionJsonSchema_AIParameterNameAttribute_UsedForPropertyName()
+    {
+        Delegate method = ([AIParameterName("$select")] string select, int top) =>
+        {
+        };
+
+        JsonElement schema = AIJsonUtilities.CreateFunctionJsonSchema(method.Method);
+
+        JsonElement properties = schema.GetProperty("properties");
+        Assert.True(properties.TryGetProperty("$select", out _));
+        Assert.False(properties.TryGetProperty("select", out _));
+
+        string[] required = schema.GetProperty("required").EnumerateArray().Select(e => e.GetString()!).ToArray();
+        Assert.Contains("$select", required);
+        Assert.Contains("top", required);
+    }
+
+    [Fact]
+    public static void CreateFunctionJsonSchema_AIParameterNameAttribute_DuplicateNamesThrow()
+    {
+        Delegate duplicateByAttribute = ([AIParameterName("dup")] string first, [AIParameterName("dup")] string second) =>
+        {
+        };
+        Assert.Throws<ArgumentException>(() => AIJsonUtilities.CreateFunctionJsonSchema(duplicateByAttribute.Method));
+
+        Delegate duplicateByCollision = ([AIParameterName("filter")] string select, string filter) =>
+        {
+        };
+        Assert.Throws<ArgumentException>(() => AIJsonUtilities.CreateFunctionJsonSchema(duplicateByCollision.Method));
+    }
+
+    [Fact]
+    public static void CreateFunctionJsonSchema_AIParameterNameAttribute_EscapesJsonPointerSegment()
+    {
+        JsonSerializerOptions options = new() { TypeInfoResolver = new DefaultJsonTypeInfoResolver() };
+        Delegate method = ([AIParameterName("a/b~c")] RecursiveNode node) =>
+        {
+        };
+
+        string schema = AIJsonUtilities.CreateFunctionJsonSchema(method.Method, serializerOptions: options).ToString();
+
+        Assert.Contains("#/properties/a~1b~0c", schema);
+        Assert.DoesNotContain("#/properties/a/b~c", schema);
+    }
+
     [Fact]
     public static void CreateJsonSchema_CanBeBoolean()
     {
@@ -1862,6 +1908,11 @@ public DerivedToolCallContent()
         public int CustomValue { get; set; }
     }
 
+    private sealed class RecursiveNode
+    {
+        public RecursiveNode? Next { get; set; }
+    }
+
     [JsonSerializable(typeof(JsonElement))]
     [JsonSerializable(typeof(CreateJsonSchema_IncorporatesTypesAndAnnotations_Type))]
     [JsonSerializable(typeof(DerivedAIContent))]

test/Libraries/Microsoft.Extensions.AI.Tests/Functions/AIFunctionFactoryTest.cs

@@ -315,6 +315,39 @@ public void Metadata_DisplayNameAttribute()
         Assert.Contains("Metadata_DisplayNameAttribute", func.Name); // Will contain the lambda method name
     }
 
+    [Fact]
+    public void Metadata_AIFunctionNameAttribute()
+    {
+        Func<string> funcWithAttribute = [AIFunctionName("get_user")] () => "test";
+        AIFunction func = AIFunctionFactory.Create(funcWithAttribute);
+        Assert.Equal("get_user", func.Name);
+
+        Func<string> funcWithBoth = [AIFunctionName("my_function")][DisplayName("display_name")] () => "test";
+        func = AIFunctionFactory.Create(funcWithBoth);
+        Assert.Equal("my_function", func.Name);
+
+        func = AIFunctionFactory.Create(funcWithAttribute, name: "explicit_name");
+        Assert.Equal("explicit_name", func.Name);
+
+        func = AIFunctionFactory.Create(funcWithAttribute, new AIFunctionFactoryOptions { Name = "options_name" });
+        Assert.Equal("options_name", func.Name);
+    }
+
+    [Fact]
+    public async Task Parameters_MappedByAIParameterNameAttribute_Async()
+    {
+        AIFunction func = AIFunctionFactory.Create(([AIParameterName("$select")] string select, int top) => select + top);
+
+        AssertExtensions.EqualFunctionCallResults("Name2", await func.InvokeAsync(new()
+        {
+            ["$select"] = "Name",
+            ["top"] = 2,
+        }));
+
+        ArgumentException ex = await Assert.ThrowsAsync<ArgumentException>(() => func.InvokeAsync(new() { ["top"] = 2 }).AsTask());
+        Assert.Contains("$select", ex.Message);
+    }
+
     [Fact]
     public void AIFunctionFactoryCreateOptions_ValuesPropagateToAIFunction()
     {