← Back to Articles         
Building Your First .NET 10 AI Agent with Microsoft Foundry

Building Your First .NET 10 AI Agent with Microsoft Foundry

Published on 19 Nov 2026 11 min read Agentic AI (.NET)
Building .NET 10 AI Agent with Microsoft Foundry

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

Azure.AI.OpenAI

Provides the Azure OpenAI client for connecting to AI models.

Azure.Identity

Provides authentication mechanisms such as Azure CLI credentials.

Microsoft.Agents.AI.OpenAI

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

Azure.AI.OpenAI

AzureOpenAIClient

Connect to Azure OpenAI.

Azure.Identity

AzureCliCredential

Authenticate using Azure CLI.

Microsoft.Agents.AI

AIAgent

Represent an AI agent.

OpenAI.Chat

ChatClient

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.Environment class.

  • 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.OpenAI namespace.

  • 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

Environment

.NET class

Access environment information

GetEnvironmentVariable()

Static method

Retrieve configuration

Uri

.NET class

Represent endpoint URI

AzureCliCredential

Azure Identity class

Obtain Azure CLI-based credentials

AzureOpenAIClient

Azure OpenAI class

Access Azure OpenAI functionality

GetChatClient()

Instance method

Obtain chat client for a deployment

ChatClient

OpenAI chat class

Interact with chat model

AsAIAgent()

Extension method

Adapt chat client into an AI agent

AIAgent

Agent abstraction

Represent and execute the agent

RunAsync()

Asynchronous method

Execute agent with a prompt

Console.WriteLine()

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}");
← Back to Articles