Building the First .NET 10 AI Agent with Microsoft Foundry
The objective is to create a .NET 10 console application that connects to a model deployed in Microsoft Foundry and executes a prompt using the Microsoft Agent Framework.
The implementation uses:
-
Azure OpenAI SDK – communicate with the deployed model.
-
Azure Identity – authenticate using Microsoft Entra ID.
-
Microsoft Agent Framework – create and execute an AI agent.
-
Environment Variables – manage endpoint and deployment configuration.
1. Create the Console Application
Create a new Console App using Visual Studio 2026.
Solution
|
+-- HelloAgent
|
+-- Dependencies
|
+-- Program.cs
|
+-- HelloAgent.csproj
Select .NET 10 as the target framework.
A console application is suitable for learning because it allows the AI integration to be implemented without additional complexity from MVC, Web API, or frontend applications.
2. Install Required NuGet Packages
Three NuGet packages are required.
dotnet add package Azure.AI.OpenAI
dotnet add package Azure.Identity
dotnet add package Microsoft.Agents.AI.OpenAI
|
Package |
Purpose |
|---|---|
|
|
Provides the Azure OpenAI client for connecting to AI models. |
|
|
Provides authentication mechanisms such as Azure CLI credentials. |
|
|
Integrates OpenAI chat clients with the Microsoft Agent Framework. |
The responsibilities are separated:
Azure.AI.OpenAI
|
v
Model Communication
Azure.Identity
|
v
Authentication
Microsoft.Agents.AI.OpenAI
|
v
AI Agent Abstraction
3. Authenticate Using Azure CLI
Before developing the agent, authenticate with Azure.
Execute this command in the terminal:
az login
This opens the Azure authentication process using Microsoft Entra ID.
What is Microsoft Entra ID?
Microsoft Entra ID is Microsoft's identity and access management service. It authenticates users and applications and issues access tokens for authorized resource access.
The authentication flow:
Developer
|
| az login
v
Azure CLI
|
v
Microsoft Entra ID
|
v
Authenticated Identity
|
v
Azure Access Token
The authenticated identity must also have the necessary permissions to access the Microsoft Foundry resource.
4. Configure Environment Variables
The application needs two configuration values.
1. Azure OpenAI Endpoint
Navigate to the Microsoft Foundry project and locate its project endpoint.
Example:
https://myresource.services.ai.azure.com
Configure this Windows environment variable:
AZURE_OPENAI_ENDPOINT
2. Deployment Name
The deployment name identifies the model deployment that the application will access.
Example:
gpt-5-mini
Configure:
AZURE_OPENAI_DEPLOYMENT_NAME
The configuration structure becomes:
Windows Environment Variables
|
+-- AZURE_OPENAI_ENDPOINT
| |
| v
| Foundry Endpoint
|
+-- AZURE_OPENAI_DEPLOYMENT_NAME
|
v
gpt-5-mini
Why environment variables?
They separate configuration from application source code. Development and production can use different endpoints and deployments without modifying the C# implementation.
5. Complete Program.cs Implementation
using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;
using OpenAI.Chat;
// 1. Read configuration
var endpoint =
Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")
?? throw new InvalidOperationException();
var model =
Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME")
?? "gpt-5-mini";
// 2. Create the AI Agent
AIAgent agent = new AzureOpenAIClient(
new Uri(endpoint),
new AzureCliCredential())
.GetChatClient(model)
.AsAIAgent(
instructions:
"You are a friendly assistant. Keep your answers brief.");
// 3. Invoke the Agent
Console.WriteLine(
await agent.RunAsync(
"What is the largest city in France?"));
6. Import Required Namespaces
using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;
using OpenAI.Chat;
A namespace groups related classes and types.
|
Namespace |
Important type |
Responsibility |
|---|---|---|
|
|
|
Connect to Azure OpenAI. |
|
|
|
Authenticate using Azure CLI. |
|
|
|
Represent an AI agent. |
|
|
|
Communicate with a chat model. |
These namespaces allow the application to use the required SDK classes without writing their fully qualified names.
7. Read the Environment Variables
var endpoint =
Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")
?? throw new InvalidOperationException();
Environment
-
Type: .NET
System.Environmentclass. -
Purpose: Provides information and functionality related to the operating system and application environment.
-
Here: Used to access Windows environment variables.
GetEnvironmentVariable()
-
Type: Static method of
Environment. -
Parameter: Environment variable name (
string). -
Return:
string?because the variable might not exist. -
Purpose: Retrieves a configuration value from the operating system.
For example:
Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT");
This retrieves the value associated with AZURE_OPENAI_ENDPOINT.
What is var?
var is a C# keyword for implicit type inference. The compiler determines the variable's type during compilation.
Here, endpoint is inferred as a string.
What is ???
The null-coalescing operator checks whether the left-hand expression is null.
value ?? fallbackValue
In this example:
?? throw new InvalidOperationException();
If the endpoint is missing, an exception is thrown immediately. This prevents the application from continuing without a mandatory configuration value.
8. Read the Deployment Name
var model =
Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME")
?? "gpt-5-mini";
This retrieves the model deployment name.
The difference from the endpoint configuration is the fallback value.
Read Deployment Name
|
v
Environment Variable Exists?
/ \
Yes No
| |
v v
Use Value gpt-5-mini
If the environment variable is missing, gpt-5-mini is used.
Important distinction: Model vs Deployment
A model is the underlying AI model, whereas a deployment is the configured deployment through which an application accesses that model.
The deployment name passed to the SDK must match the name configured in Microsoft Foundry.
9. Create the Azure OpenAI Client
new AzureOpenAIClient(
new Uri(endpoint),
new AzureCliCredential())
This statement creates the client required to communicate with Azure OpenAI.
AzureOpenAIClient
-
Type: Class from the
Azure.AI.OpenAInamespace. -
Purpose: Provides access to Azure OpenAI service functionality.
-
Constructor inputs:
-
Uri– Azure OpenAI endpoint. -
TokenCredential– Authentication credential.
-
Conceptually:
AzureOpenAIClient
|
+-- Endpoint
| |
| v
| Where is the service?
|
+-- Credential
|
v
Who is accessing it?
new Uri(endpoint)
Uri is a .NET class from the System namespace.
It represents a Uniform Resource Identifier.
The endpoint is initially stored as a string. The Uri constructor creates a URI object from that string.
string endpoint =
"https://myresource.services.ai.azure.com";
Uri endpointUri = new Uri(endpoint);
The resulting Uri object is passed to AzureOpenAIClient.
new AzureCliCredential()
-
Type: Class from
Azure.Identity. -
Implements:
TokenCredential. -
Purpose: Obtains access tokens using the authenticated Azure CLI session.
It uses the login established by:
az login
The SDK can then obtain an access token when communicating with Azure.
Azure CLI Login
|
v
AzureCliCredential
|
v
Access Token
|
v
Azure OpenAI Service
No API key is embedded in the application.
10. Get the Chat Client
.GetChatClient(model)
This is a method call on the AzureOpenAIClient object.
What is GetChatClient()?
-
Type: Instance method exposed by
AzureOpenAIClient. -
Parameter: Deployment name (
string). -
Return:
OpenAI.Chat.ChatClient. -
Purpose: Obtains a chat client configured for the specified model deployment.
Example:
ChatClient chatClient =
azureClient.GetChatClient("gpt-5-mini");
The method uses the deployment name to configure the chat client for subsequent model interactions.
What is ChatClient?
ChatClient is a class from the OpenAI.Chat namespace.
Its responsibility is to provide chat interaction with the configured model.
The distinction:
AzureOpenAIClient
|
| GetChatClient(model)
v
ChatClient
|
v
Chat Model Interaction
AzureOpenAIClient provides access to the Azure OpenAI service, while ChatClient provides the chat-specific interaction interface.
11. Convert ChatClient into an AI Agent
.AsAIAgent(
instructions:
"You are a friendly assistant. Keep your answers brief.");
This is an extension method provided by the Microsoft Agent Framework integration.
What is an extension method?
An extension method adds functionality to an existing type without modifying its original class.
Here, the Microsoft Agent Framework provides the ability to adapt the ChatClient into an agent abstraction.
ChatClient
|
| AsAIAgent()
v
AIAgent
What is AsAIAgent()?
-
Type: Extension method.
-
Provided through: Microsoft Agent Framework OpenAI integration.
-
Input: Agent configuration, including instructions.
-
Return:
AIAgent. -
Purpose: Creates an agent abstraction using the chat client.
What is instructions?
instructions is a named parameter that defines the agent's expected behavior.
Example:
instructions:
"You are a friendly assistant. Keep your answers brief."
These instructions guide how the agent responds to user prompts.
There are two separate inputs:
Agent Instructions
|
v
You are a friendly assistant.
Keep your answers brief.
User Prompt
|
v
What is the largest city in France?
Instructions define the agent's behavior. The prompt defines the task to execute.
12. Store the Agent in AIAgent
AIAgent agent = ...
What is AIAgent?
-
Type: Abstract agent class from
Microsoft.Agents.AI. -
Purpose: Represents an AI agent that can be executed through the Agent Framework.
The variable declaration:
AIAgent agent
means that agent holds a reference to an object represented by the AIAgent type.
The complete creation chain is:
AzureOpenAIClient
|
| GetChatClient(model)
v
ChatClient
|
| AsAIAgent(instructions)
v
AIAgent
|
v
agent
13. Invoke the Agent Using RunAsync()
await agent.RunAsync(
"What is the largest city in France?");
What is RunAsync()?
-
Type: Asynchronous method of the agent abstraction.
-
Input: User prompt.
-
Return: An asynchronous operation that produces an agent response.
-
Purpose: Executes the agent with the supplied input.
The prompt is:
What is the largest city in France?
The execution flow:
agent.RunAsync(prompt)
|
v
Agent Framework
|
v
Chat Client
|
v
Microsoft Foundry
|
v
GPT Deployment
|
v
Generated Response
Why await?
RunAsync() performs an asynchronous operation involving network communication.
The await keyword asynchronously waits for the operation to complete before continuing execution.
This avoids unnecessarily blocking the calling thread while waiting for the remote response.
14. Display the Response
Console.WriteLine(
await agent.RunAsync(
"What is the largest city in France?"));
Console.WriteLine() is a static method of the .NET Console class.
Its purpose is to write output to the console window.
The execution order is:
RunAsync(prompt)
|
v
Wait for response using await
|
v
Receive Agent Response
|
v
Console.WriteLine()
|
v
Display Output
For this question, the expected factual answer is Paris.
15. Complete Application Architecture
The complete implementation can be understood through two connected flows.
Authentication flow
Developer
|
| az login
v
Azure CLI
|
v
Microsoft Entra ID
|
v
AzureCliCredential
|
v
Access Token
AI execution flow
.NET 10 Console Application
|
v
Read Environment Variables
|
v
AzureOpenAIClient
|
| GetChatClient(model)
v
ChatClient
|
| AsAIAgent(instructions)
v
AIAgent
|
| RunAsync(prompt)
v
Microsoft Foundry
|
v
GPT Deployment
|
v
Agent Response
|
v
Console Output
16. Alternative Authentication — API Key
The transcript also demonstrates API key authentication as an alternative.
Instead of:
new AzureCliCredential()
an API key credential can be supplied to the appropriate Azure OpenAI client constructor.
The conceptual difference:
Azure CLI Authentication
|
v
Microsoft Entra ID
|
v
Access Token
API Key Authentication
|
v
API Key Credential
|
v
Azure OpenAI Client
The subsequent chat client and agent creation steps remain conceptually the same.
However, the course establishes a security rule: use Azure CLI credentials for local development rather than hard-coded API keys.
In production, a suitable alternative is Managed Identity.
LOCAL DEVELOPMENT
AzureCliCredential
|
v
Microsoft Entra ID
AZURE PRODUCTION
Managed Identity
|
v
Microsoft Entra ID
Both approaches use identity-based authentication without embedding an API key in application source code.
17. Important Classes and Methods — Quick Reference
|
Element |
Type |
Responsibility |
|---|---|---|
|
|
.NET class |
Access environment information |
|
|
Static method |
Retrieve configuration |
|
|
.NET class |
Represent endpoint URI |
|
|
Azure Identity class |
Obtain Azure CLI-based credentials |
|
|
Azure OpenAI class |
Access Azure OpenAI functionality |
|
|
Instance method |
Obtain chat client for a deployment |
|
|
OpenAI chat class |
Interact with chat model |
|
|
Extension method |
Adapt chat client into an AI agent |
|
|
Agent abstraction |
Represent and execute the agent |
|
|
Asynchronous method |
Execute agent with a prompt |
|
|
Static method |
Display output |
Central concept to remember:
new AzureOpenAIClient(...)
.GetChatClient(model)
.AsAIAgent(instructions: "...")
.RunAsync(prompt);
Each operation has a distinct responsibility:
-
AzureOpenAIClient– service connectivity. -
GetChatClient()– obtain the chat client for a deployment. -
AsAIAgent()– create the agent abstraction. -
RunAsync()– execute the agent.
This is the foundation for moving towards tools, function calling, agent context, and multi-agent orchestration using .NET and C#.
Complete Program
using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
// 1. Define the variables we extracted from Microsoft Foundry
var endpoint = Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
var deploymentName = Environment.GetEnvironmentVariable("AZURE_OPENAI_DEPLOYMENT_NAME") ?? "gpt-5-mini";
// 2. Instantiate the universal chat client
IChatClient chatClient = new AzureOpenAIClient(
new Uri(endpoint),
new AzureCliCredential())
.GetChatClient(deploymentName)
.AsIChatClient();
// Alternative initialization using API Key
//AIAgent agent = new AzureOpenAIClient(
//new Uri(endpoint),
//new ApiKeyCredential(apikey)) .GetChatClient(model)
//AsAIAgent (instructions: "You are a friendly assistant. Keep your answers brief.");
// 3. Define the Agent's Anatomy
AIAgent supportAgent = chatClient.AsAIAgent(
name: "NetworkSupport",
instructions: "You are a Tier 1 IT Support Agent. Your answers must be concise, professional, and limited strictly to troubleshooting network and VPN connectivity. Keep your answers brief."
);
Console.WriteLine($"Agent '{supportAgent.Name}' is online.\n");
// 4. Execute the Agent
string userIssue = "I am getting a DNS resolution error when connecting to the corporate VPN from a coffee shop. Keep your answers brief.";
Console.WriteLine($"User: {userIssue}\n");
AgentResponse response = await supportAgent.RunAsync(userIssue);
Console.WriteLine($"Agent: {response.Text}");