Skip to main content

How to Use an Enum Parameter in a Microsoft Agent Framework Function Tool in C#

· 10 min read
Jagdish Kumawat
Founder @ Dewiride

Some tool parameters can only take a few values: a size, a priority, a status. Make such a parameter a C# enum, and Microsoft Agent Framework tells the model exactly which values exist, so it picks one of them instead of making one up. One thing still gets through: a number that isn't one of the values. This guide shows both with a small coffee-ordering agent and a real model, and adds the one-line check that closes the gap.

Syntax​

Syntax
enum <EnumName>
{
<Value1>,
<Value2>,
}

[Description("<what the tool does>")]
static <return type> <MethodName>([Description("<what the value is>")] <EnumName> <parameterName>)
PartWhat to put there
<EnumName>The name of the list of values, such as CoffeeSize
<Value1>, <Value2>The values the model may choose. The model sees these names, so make them plain words
<what the tool does>, <what the value is>Descriptions for the model, as for any function tool
<parameterName>The parameter, typed as the enum. AIFunctionFactory.Create turns the method into a tool

The enum's names reach the model as text because of the JSON options Agent Framework uses for tools. Their documentation lists among their settings: Enables string based enum serialization as implemented by JsonStringEnumConverter.

The Example​

A console app runs an agent that takes coffee orders. Its one tool, order_coffee, takes a size: Small, Medium or Large. The customer asks for a big coffee, then for an extra-large coffee, which the shop doesn't sell.

Prerequisites​

  • A model deployment in a Microsoft Foundry project, and the Foundry User role on the Foundry resource for your account. The app calls the model as you.
  • The .NET 10 SDK (dotnet --version prints a version that starts with 10.0) and the Azure CLI, signed in with az login.

Step 1: Create a Console App​

In a terminal, in the folder where you keep your projects, create a console app, move into it and add two packages:

Terminal
dotnet new console -n CoffeeAgent
cd CoffeeAgent
dotnet add package Microsoft.Agents.AI.Foundry --version 1.28.0-preview.261106.1
dotnet add package Azure.Identity --version 1.21.0
Output (first command)
The template "Console App" was created successfully.

Processing post-creation actions...
Restoring /Users/you/source/CoffeeAgent/CoffeeAgent.csproj:
Restore succeeded.
PackageWhat it gives the app
Microsoft.Agents.AI.FoundryAsAIAgent, which turns a model in a Foundry project into an agent, and AIFunctionFactory, which turns a method into a tool
Azure.IdentityAzureCliCredential, which signs the app in to Foundry with your Azure CLI sign-in

Microsoft Agent Framework 1.28.0 is generally available, but its Foundry package ships only as a preview of the same release, so it needs its exact --version. Open the CoffeeAgent folder in VS Code, or CoffeeAgent.csproj in Visual Studio.

Step 2: Write a Tool with an Enum Parameter​

Replace everything in Program.cs with:

Program.cs
using System.ComponentModel;
using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;

// Turn the OrderCoffee method below into a tool, and print what the model receives about it.
AIFunction orderCoffee = AIFunctionFactory.Create(OrderCoffee, name: "order_coffee");
Console.WriteLine(orderCoffee.JsonSchema);

AIAgent agent = new AIProjectClient(
new Uri("https://foundry-devblogs-exp.services.ai.azure.com/api/projects/proj-devblogs-exp"),
new AzureCliCredential())
.AsAIAgent(
model: "gpt-5.6-luna",
instructions: "You take coffee orders at a coffee shop. Answer in one sentence.",
tools: [orderCoffee]);

Console.WriteLine(await agent.RunAsync("I'd like a big coffee, please."));

[Description("Orders one coffee in the size the customer wants.")]
static string OrderCoffee([Description("The size of the coffee.")] CoffeeSize size)
{
Console.WriteLine($"(order_coffee was called with size = {size})");
return $"One {size} coffee is on its way.";
}

// The sizes the coffee shop sells.
enum CoffeeSize
{
Small,
Medium,
Large,
}
  • enum CoffeeSize lists the three sizes. A type can follow the top-level statements in Program.cs, so the whole app stays in one file.
  • CoffeeSize size is the tool's only parameter. Nothing else in the tool is special: the enum does the work.
  • Console.WriteLine(orderCoffee.JsonSchema) prints the parameters' JSON schema, the part of the tool the model reads to fill in the arguments.
  • The AIProjectClient URI and gpt-5.6-luna are my Foundry project's endpoint and model deployment. Use your own; How to Create a Microsoft Foundry Resource and Deploy a Model shows where to find them.

Run the app:

In the terminal, in the CoffeeAgent folder, run:

Terminal
dotnet run
Output
{"type":"object","properties":{"size":{"description":"The size of the coffee.","type":"string","enum":["Small","Medium","Large"]}},"required":["size"]}
(order_coffee was called with size = Large)
Your Large coffee is on its way.

The first line is what the model knows about size: a string with an enum list, Small, Medium and Large. The model turned a big coffee into Large, one of those three, and the tool ran with it.

Step 3: Ask for a Size That Isn't on the List​

Change the question on the RunAsync line to I'd like an extra-large coffee, please. and run the app again:

Output
{"type":"object","properties":{"size":{"description":"The size of the coffee.","type":"string","enum":["Small","Medium","Large"]}},"required":["size"]}
We only offer small, medium, or large—would you like a large coffee?

No order_coffee was called line: the model didn't call the tool at all. It knew from the schema that there is no extra-large, and asked instead. With a plain string parameter, it could only have guessed what the tool accepts.

Step 4: Check the Value in the Tool​

The schema guides the model, but the tool still gets whatever arguments the model sends. AIFunctionFactory's documentation says it plainly: the data supplied via an AIFunctionArguments's dictionary is supplied from an AI service and should be considered unvalidated and untrusted. I called the tool directly with three arguments a model could send, to see what reaches OrderCoffee:

ArgumentWhat happened
{"size":"large"}OrderCoffee ran with Large. The converter's documentation says Reading is case insensitive
{"size":"Huge"}OrderCoffee never ran: JsonException: The JSON value could not be converted to CoffeeSize. An agent sends the model a generic error for a tool call that throws
{"size":7}OrderCoffee ran with size = 7 and answered One 7 coffee is on its way.

The last one is the gap. JsonStringEnumConverter has an allowIntegerValues setting, and its documentation says it is true by default, to allow undefined enum values. So a number goes straight through, even one that is none of the sizes. One line closes it. Replace the OrderCoffee method with:

Program.cs (OrderCoffee)
[Description("Orders one coffee in the size the customer wants.")]
static string OrderCoffee([Description("The size of the coffee.")] CoffeeSize size)
{
Console.WriteLine($"(order_coffee was called with size = {size})");

// The JSON converter also accepts numbers, so a value that isn't a size can still arrive.
if (!Enum.IsDefined(size))
{
return "There is no such size. Choose Small, Medium or Large.";
}

return $"One {size} coffee is on its way.";
}

Enum.IsDefined(size) is true only for the values in the enum. For anything else, the tool returns a message the model can act on, instead of ordering a coffee in size 7. The complete file, with the question back to a big coffee:

Program.cs
using System.ComponentModel;
using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;

// Turn the OrderCoffee method below into a tool, and print what the model receives about it.
AIFunction orderCoffee = AIFunctionFactory.Create(OrderCoffee, name: "order_coffee");
Console.WriteLine(orderCoffee.JsonSchema);

AIAgent agent = new AIProjectClient(
new Uri("https://foundry-devblogs-exp.services.ai.azure.com/api/projects/proj-devblogs-exp"),
new AzureCliCredential())
.AsAIAgent(
model: "gpt-5.6-luna",
instructions: "You take coffee orders at a coffee shop. Answer in one sentence.",
tools: [orderCoffee]);

Console.WriteLine(await agent.RunAsync("I'd like a big coffee, please."));

[Description("Orders one coffee in the size the customer wants.")]
static string OrderCoffee([Description("The size of the coffee.")] CoffeeSize size)
{
Console.WriteLine($"(order_coffee was called with size = {size})");

// The JSON converter also accepts numbers, so a value that isn't a size can still arrive.
if (!Enum.IsDefined(size))
{
return "There is no such size. Choose Small, Medium or Large.";
}

return $"One {size} coffee is on its way.";
}

// The sizes the coffee shop sells.
enum CoffeeSize
{
Small,
Medium,
Large,
}

macOS-style code window titled Program.cs showing AIFunctionFactory.Create turning OrderCoffee into a tool named order_coffee and printing its JSON schema, an agent created with AsAIAgent and the tool, the question I'd like a big coffee, please, the OrderCoffee method with Description attributes that returns There is no such size when Enum.IsDefined is false, and the CoffeeSize enum with Small, Medium and Large

Run it once more:

Output
{"type":"object","properties":{"size":{"description":"The size of the coffee.","type":"string","enum":["Small","Medium","Large"]}},"required":["size"]}
(order_coffee was called with size = Large)
Your large coffee is on its way!

And with {"size":7}, called directly as before, the tool now answers There is no such size. Choose Small, Medium or Large.

Common Mistakes​

MistakeWhat happensDo this instead
A string parameter for a value with a fixed set of choicesThe model has to guess which words the tool acceptsUse an enum, so the schema lists the choices
Trusting the enum without Enum.IsDefinedA number such as 7 reaches the method as a value that doesn't existCheck with Enum.IsDefined before acting on it
Enum names the model can't understand, such as Sz1The model has nothing to match the customer's words againstUse plain names, such as Large

Troubleshooting​

SymptomLikely causeFix
The tool's value is a number, such as 7The converter accepts numbers, defined or notCheck with Enum.IsDefined, as in Step 4
The JSON value could not be converted to CoffeeSizeThe arguments named a value that isn't in the enum, such as HugeNothing to fix in the tool: the call fails before your method runs

FAQ​

Are the names case-sensitive?​

Not when reading: the documentation of JsonStringEnumConverter says Reading is case insensitive, and {"size":"large"} ran the tool with Large. The schema lists the names exactly as the enum spells them.

Does the model see the numbers behind the names?​

No. The schema has only the names, "enum":["Small","Medium","Large"], because the tool's JSON options write enums as strings.

Conclusion​

An enum parameter turns any text into one of these values: the tool's JSON schema lists the names, and the model chooses from them, or asks, as it did for an extra-large coffee. A number that isn't one of the values still reaches your method, because the JSON converter allows undefined values, so check it with Enum.IsDefined before acting on it.

Additional Resources​