Make markdown configuration compatible with VSC chat modes

See https://code.visualstudio.com/docs/copilot/customization/custom-chat-modes (seems to have been renamed to "custom agents" in VSC insiders now).

Our extensions (such as `client`, `use` and `options`  can be persisted in other config files (since they are aggregated at run-time) or kept in the same agents.md file since VSCode will ignore them.

Author: kzu

assets/img/agent-model.png

@@ -11,23 +11,16 @@ instructions = """\
     You are an AI agent responsible for processing orders for food or other items.
     Your primary goals are to identify user intent, extract or request provider information, manage order data using tools and friendly responses to guide users through the ordering process.
     """
+options = { modelid = "gpt-4o-mini" }
+# 👇 alternative syntax to specify options
+# [ai.agents.orders.options]
+# modelid = "gpt-4o-mini"
 
 # ai.clients.openai, can omit the ai.clients prefix
 client = "openai"
-use = ["tone", "get_date", "create_order", "cancel_order"]
+use = ["tone"]
+tools = ["get_date", "create_order", "cancel_order"]
 
-[ai.agents.orders.options]
-modelid = "gpt-4o-mini"
-# additional properties could be added here
-
-[ai.agents.notes]
-description = "Help users create, manage, and retrieve notes effectively."
-instructions = """
-    You are an AI agent that assists users in creating, managing, and retrieving notes.
-    Your primary goals are to understand user requests related to notes, provide clear and concise responses, and utilize tools to organize and access note data efficiently.
-    """
-client = "grok"
-use = ["tone", "save_notes", "get_date"]
 
 [ai.context.tone]
 instructions = """\

sample/Server/ai.toml

@@ -1,8 +1,9 @@
 ---
 id: ai.agents.notes
 description: Provides free-form memory
-client: Grok
-options: 
-  modelid: grok-4-fast
+client: grok
+model: grok-4-fast
+use: ["tone"]
+tools: ["save_notes", "get_date"]
 ---
 You organize and keep notes for the user, using JSON-LD

sample/Server/notes.md

@@ -106,6 +106,12 @@ public override IAsyncEnumerable<AgentRunResponseUpdate> RunStreamingAsync(IEnum
         if (chat is not null)
             options.ChatOptions = chat;
 
+        if (options.Model is not null)
+        {
+            options.ChatOptions ??= new();
+            options.ChatOptions.ModelId = options.Model;
+        }
+
         configure?.Invoke(name, options);
 
         if (options.AIContextProviderFactory is null)
@@ -127,10 +133,10 @@ public override IAsyncEnumerable<AgentRunResponseUpdate> RunStreamingAsync(IEnum
 
                 options.AIContextProviderFactory = _ => contextProvider;
             }
-            else if (options.Use?.Count > 0)
+            else if (options.Use?.Count > 0 || options.Tools?.Count > 0)
             {
                 var contexts = new List<AIContext>();
-                foreach (var use in options.Use)
+                foreach (var use in options.Use ?? [])
                 {
                     var context = services.GetKeyedService<AIContext>(use);
                     if (context is not null)
@@ -139,13 +145,6 @@ public override IAsyncEnumerable<AgentRunResponseUpdate> RunStreamingAsync(IEnum
                         continue;
                     }
 
-                    var function = services.GetKeyedService<AITool>(use) ?? services.GetKeyedService<AIFunction>(use);
-                    if (function is not null)
-                    {
-                        contexts.Add(new AIContext { Tools = [function] });
-                        continue;
-                    }
-
                     if (configuration.GetSection("ai:context:" + use) is { } ctxSection &&
                         ctxSection.Get<AIContextConfiguration>() is { } ctxConfig)
                     {
@@ -161,7 +160,7 @@ public override IAsyncEnumerable<AgentRunResponseUpdate> RunStreamingAsync(IEnum
                             {
                                 var tool = services.GetKeyedService<AITool>(toolName) ??
                                     services.GetKeyedService<AIFunction>(toolName) ??
-                                    throw new InvalidOperationException($"Specified tool '{toolName}' for AI context '{ctxSection.Path}:tools' is not registered, and is required by agent section '{configSection.Path}'.");
+                                    throw new InvalidOperationException($"Specified tool '{toolName}' for AI context '{ctxSection.Path}:tools' is not registered as a keyed {nameof(AITool)} or {nameof(AIFunction)}, and is required by agent section '{configSection.Path}'.");
 
                                 configured.Tools ??= [];
                                 configured.Tools.Add(tool);
@@ -172,7 +171,16 @@ public override IAsyncEnumerable<AgentRunResponseUpdate> RunStreamingAsync(IEnum
                         continue;
                     }
 
-                    throw new InvalidOperationException($"Specified AI context '{use}' for agent '{name}' is not registered as either {nameof(AIContent)}, {nameof(AITool)} or configuration section 'ai:context:{use}'.");
+                    throw new InvalidOperationException($"Specified AI context '{use}' for agent '{name}' is not registered as either {nameof(AIContent)} or configuration section 'ai:context:{use}'.");
+                }
+
+                foreach (var toolName in options.Tools ?? [])
+                {
+                    var tool = services.GetKeyedService<AITool>(toolName) ??
+                        services.GetKeyedService<AIFunction>(toolName) ??
+                        throw new InvalidOperationException($"Specified tool '{toolName}' for agent '{section}' is not registered as a keyed {nameof(AITool)} or {nameof(AIFunction)}.");
+
+                    contexts.Add(new AIContext { Tools = [tool] });
                 }
 
                 options.AIContextProviderFactory = _ => new CompositeAIContextProvider(contexts);
@@ -215,7 +223,9 @@ void OnReload(object? state)
     internal class AgentClientOptions : ChatClientAgentOptions
     {
         public string? Client { get; set; }
+        public string? Model { get; set; }
         public IList<string>? Use { get; set; }
+        public IList<string>? Tools { get; set; }
     }
 }
 

src/Agents/ConfigurableAIAgent.cs

@@ -539,7 +539,7 @@ public async Task UseAIToolFromKeyedServiceAsync()
             [ai.agents.chat]
             description = "Chat agent."
             client = "openai"
-            use = ["get_date"]
+            tools = ["get_date"]
             """");
 
         AITool tool = AIFunctionFactory.Create(() => DateTimeOffset.Now, "get_date");
@@ -561,6 +561,32 @@ public async Task UseAIToolFromKeyedServiceAsync()
         Assert.Same(tool, context.Tools[0]);
     }
 
+    [Fact]
+    public async Task MissingAIToolFromKeyedServiceThrows()
+    {
+        var builder = new HostApplicationBuilder();
+
+        builder.Configuration.AddToml(
+            $$"""
+            [ai.clients.openai]
+            modelid = "gpt-4.1"
+            apikey = "sk-asdf"
+
+            [ai.agents.chat]
+            description = "Chat agent."
+            client = "openai"
+            tools = ["get_date"]
+            """);
+
+        builder.AddAIAgents();
+        var app = builder.Build();
+
+        var exception = Assert.ThrowsAny<Exception>(() => app.Services.GetRequiredKeyedService<AIAgent>("chat"));
+
+        Assert.Contains("get_date", exception.Message);
+        Assert.Contains("ai:agents:chat", exception.Message);
+    }
+
     [Fact]
     public async Task UseAIContextFromSection()
     {
@@ -668,5 +694,57 @@ public async Task UnknownUseThrows()
 
         Assert.Contains("foo", exception.Message);
     }
+
+    [Fact]
+    public async Task OverrideModelFromAgentChatOptions()
+    {
+        var builder = new HostApplicationBuilder();
+
+        builder.Configuration.AddToml(
+            $$"""
+            [ai.clients.openai]
+            modelid = "gpt-4.1"
+            apikey = "sk-asdf"
+
+            [ai.agents.chat]
+            description = "Chat"
+            client = "openai"
+            options = { modelid = "gpt-5" }
+            """);
+
+        builder.AddAIAgents();
+        var app = builder.Build();
+
+        var agent = app.Services.GetRequiredKeyedService<AIAgent>("chat");
+        var options = agent.GetService<ChatClientAgentOptions>();
+
+        Assert.Equal("gpt-5", options?.ChatOptions?.ModelId);
+    }
+
+    [Fact]
+    public async Task OverrideModelFromAgentModel()
+    {
+        var builder = new HostApplicationBuilder();
+
+        builder.Configuration.AddToml(
+            $$"""
+            [ai.clients.openai]
+            modelid = "gpt-4.1"
+            apikey = "sk-asdf"
+
+            [ai.agents.chat]
+            description = "Chat"
+            client = "openai"
+            model = "gpt-5"
+            """);
+
+        builder.AddAIAgents();
+        var app = builder.Build();
+
+        var agent = app.Services.GetRequiredKeyedService<AIAgent>("chat");
+        var options = agent.GetService<ChatClientAgentOptions>();
+
+        Assert.Equal("gpt-5", options?.ChatOptions?.ModelId);
+    }
 }