.NET: run_skill_script generates invalid schema for arguments

[riteshksriv]

Description

When an agent uses strict structured output, AgentSkillsProvider causes OpenAI/Azure OpenAI to reject the request before model execution.

AgentSkillsProvider always exposes run_skill_script for a file-based skill, even when the skill contains no scripts. In Microsoft.Agents.AI 1.20.0, the generated JSON Schema for its optional arguments parameter is:

{"default":null}

Because the property has no type, OpenAI/Azure OpenAI rejects the complete request when strict schema validation is enabled for the response:

HTTP 400 (invalid_request_error: invalid_function_parameters)
Parameter: tools[...].function.parameters

Invalid schema for function 'run_skill_script':
In context=('properties', 'arguments'), schema must have a 'type' key.

Without strict structured output, the same request is accepted by Azure OpenAI. Enabling strict output with:

chatOptions.AdditionalProperties["strict"] = true;

exposes the invalid tool schema. Although strict mode is configured for the response schema, the service validates every function-tool schema in the same request.

This also affects scriptless file skills because AgentSkillsProviderBuilder.UseFileSkill(s) requires a script runner, and the provider advertises run_skill_script regardless of whether any discovered skill contains scripts.

Minimal reproduction

The following is the only file required. Run it with the .NET 10 SDK:

// Program.cs
#:package Microsoft.Agents.AI@1.20.0

using System.Runtime.CompilerServices;
using System.Text.Json;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;

var rootDirectory = Path.Combine(Path.GetTempPath(), $"agent-framework-repro-{Guid.NewGuid():N}");
var skillDirectory = Path.Combine(rootDirectory, "hello");
Directory.CreateDirectory(skillDirectory);
File.WriteAllText(
    Path.Combine(skillDirectory, "SKILL.md"),
    """
    ---
    name: hello
    description: Says hello.
    ---

    Say hello to the user.
    """);

try
{
    using var skills = new AgentSkillsProviderBuilder()
        .UseFileSkills([skillDirectory])
        .UseFileScriptRunner((_, _, _, _, _) =>
            throw new NotSupportedException("This skill has no scripts."))
        .UseOptions(options =>
        {
            options.DisableLoadSkillApproval = true;
            options.DisableReadSkillResourceApproval = true;
        })
        .Build();

    using var client = new CaptureChatClient();
    using var outputSchema = JsonDocument.Parse(
        """{"type":"object","properties":{"message":{"type":"string"}},"required":["message"],"additionalProperties":false}""");
    var chatOptions = new ChatOptions
    {
        ResponseFormat = ChatResponseFormat.ForJsonSchema(outputSchema.RootElement.Clone()),
        AdditionalProperties = new AdditionalPropertiesDictionary
        {
            ["strict"] = true,
        },
    };
    var agent = client.AsAIAgent(
        new ChatClientAgentOptions
        {
            AIContextProviders = [skills],
            ChatOptions = chatOptions,
        });

    await agent.RunAsync([new ChatMessage(ChatRole.User, "Hello")]);

    var function = (AIFunction)client.Options!.Tools!
        .Single(tool => tool.Name == AgentSkillsProvider.RunSkillScriptToolName);
    var argumentsSchema = function.JsonSchema
        .GetProperty("properties")
        .GetProperty("arguments");

    Console.WriteLine(argumentsSchema);
    Console.WriteLine($"Has type: {argumentsSchema.TryGetProperty("type", out _)}");
}
finally
{
    Directory.Delete(rootDirectory, recursive: true);
}

sealed class CaptureChatClient : IChatClient
{
    public ChatOptions? Options { get; private set; }

    public Task<ChatResponse> GetResponseAsync(
        IEnumerable<ChatMessage> messages,
        ChatOptions? options = null,
        CancellationToken cancellationToken = default)
    {
        Options = options;
        return Task.FromResult(
            new ChatResponse(new ChatMessage(ChatRole.Assistant, "Hello!")));
    }

    public async IAsyncEnumerable<ChatResponseUpdate> GetStreamingResponseAsync(
        IEnumerable<ChatMessage> messages,
        ChatOptions? options = null,
        [EnumeratorCancellation] CancellationToken cancellationToken = default)
    {
        Options = options;
        await Task.Yield();
        yield return new ChatResponseUpdate(ChatRole.Assistant, "Hello!");
    }

    public object? GetService(Type serviceType, object? serviceKey = null) =>
        serviceType.IsInstanceOfType(this) ? this : null;

    public void Dispose()
    {
    }
}

dotnet run Program.cs

Actual output:

{"default":null}
Has type: False

Expected behavior

Either:

1. Do not expose run_skill_script when discovered file skills contain no scripts, or provide an option to disable script execution; and/or
2. Generate a valid schema for arguments, for example an object schema that OpenAI-compatible providers accept.

Package and runtime versions

• Microsoft.Agents.AI: 1.20.0
• .NET SDK: 10.0.303
• OS: Windows

[manjunathshiva]

Roger Barreto (@rogerbarreto) I’d like to take on #8094 if it isn’t already being worked on. Before implementing, could you confirm the preferred approach?

Source inspection shows that run_skill_script exposes JsonElement? arguments, producing an unconstrained parameter schema. File scripts use array arguments, while inline scripts generally use objects, so narrowing this to an object would exclude existing supported inputs. Current tests also explicitly expect all skill tools to remain available for scriptless skills.

My proposed direction is to advertise arguments as a nullable JSON-encoded string, then decode it once at the provider boundary before passing the resulting JsonElement to the script. This would allow strict validation of the outer tool schema while retaining flexible script payloads. The decoded payload would still be validated by the script or its argument marshaler.

I would aim to preserve existing direct object/array invocation, tool names, approval behavior, and C# script interfaces. However, the advertised argument shape changes, and custom marshalers that expect raw strings need consideration—particularly alongside #7989.

Proposed coverage includes strict request serialization, file-array and inline-object execution, omitted/null arguments, malformed encoded JSON, legacy object/array calls, and approval wrapping.

Is this contract change acceptable for a focused fix, or would you prefer the smaller alternative of opting only run_skill_script out of strict validation while leaving structured responses strict? If the proposed direction is acceptable, I’m happy to implement it.

I have now reproduced the generated-schema defect locally on macOS arm64 using .NET SDK 10.0.303, with both:

• the released Microsoft.Agents.AI 1.20.0 package; and
• this repository’s source at commit 2c49f50.

Both runs of the issue’s reproduction produced:

{"default":null}
Has type: False

I have also reproduced the issue against a live Azure OpenAI environment, using the gpt-5.5 deployment, the v1 Chat Completions API, and Azure CLI authentication. The live harness uses this repository’s source at 2c49f50, .NET SDK 10.0.303, Microsoft.Extensions.AI.OpenAI 10.9.0, and OpenAI 2.12.0.

The same framework-generated skill tools and response schema produced:

ChatOptions.AdditionalProperties["strict"]	Result
true	HTTP 400 — invalid_function_parameters
false	HTTP 200 — {"message":"Hello"}

The live service returned:

Parameter: tools[2].function.parameters

Invalid schema for function 'run_skill_script': In context=('properties', 'arguments'), schema must have a 'type' key.

Both requests used tool_choice: none, so the rejection occurs during schema validation even when no tool is executed. Captured request bodies confirm that the global strict setting applies to both the function tools and the response schema. In strict mode, the adapter transforms {"default":null} into {"description":"Default value: null"}, which still has no type.

This confirms the reported live service rejection with the unmodified framework. No framework source changes were made.

[github-actions]

🤖 Automated triage reproduction notes (agent-authored — trust but verify)

Agent analysis

dotnet/src/Microsoft.Agents.AI/Skills/AgentSkillsProvider.cs::BuildTools generates {"default":null} without a type for the optional JsonElement? arguments parameter at line 334. The failure occurs whenever a discovered skill causes run_skill_script to be advertised and the provider strictly validates function schemas, including for scriptless skills. Minimal repro: create a scriptless file skill, invoke AgentSkillsProvider, and inspect run_skill_script.JsonSchema.properties.arguments.

• Failing test: dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/AgentSkillsProviderTests.cs
• Files examined: dotnet/src/Microsoft.Agents.AI/Skills/AgentSkillsProvider.cs, dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/AgentSkillsProviderTests.cs, dotnet/nuget/nuget-package.props
• Tests run: InvokingCoreAsync_WithSkills_AppendsInstructionsAndToolsAsync, RunSkillScriptTool_ArgumentsSchema_HasTypeAsync
• Reported version: 1.20.0
• Current version: 1.20.0