← Back to Articles         
First AI Agent with Microsoft Agent Framework

First AI Agent with Microsoft Agent Framework

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

Building Your First AI Agent with Microsoft Agent Framework

Until now, the focus was on setting up the .NET environment, Azure authentication, Microsoft Foundry, and the AI model. Now we can build the first actual AI agent.

The important change is that we are moving from simply calling an LLM with a prompt to creating a named, purpose-driven agent with defined instructions and execution behavior.

Traditional LLM
     ↓
Prompt
     ↓
LLM
     ↓
Text Response

With an agent:

User Request
     ↓
AI Agent
 ┌───────────────┐
 │ Name          │
 │ Instructions  │
 │ Chat Client   │
 │ State         │
 │ Tools         │
 └───────────────┘
     ↓
LLM
     ↓
Agent Response

This agent abstraction becomes the foundation for more advanced capabilities such as tools, memory, multi-agent workflows, and human approval.

What Is an AI Agent?

An AI agent can be thought of as a software entity with a defined identity, instructions, and responsibility.

Instead of writing code such as:

"Send this prompt to the LLM and print the answer."

we define an agent with a specific purpose.

For example:

NetworkSupport Agent
        ↓
Responsible for
network and VPN troubleshooting

The agent's behavior is primarily established through two important properties:

  • Name — identifies the agent.
  • Instructions — defines what the agent is supposed to do and what boundaries it must follow.

This distinction becomes especially important when multiple agents are working together.

Agent Name

The name identifies the agent.

For example:

name: "NetworkSupport"

In a single-agent application, the name may not seem very important. However, in a multi-agent system, the orchestrator needs to know which agent is responsible for a particular task.

For example:

                 Manager Agent
                      |
          +-----------+-----------+
          |                       |
          ↓                       ↓
   NetworkSupport           DatabaseAgent
       Agent                    Agent

The agent name becomes an identity that the orchestration layer can use when routing work.

Agent Instructions

The instructions property defines the agent's behavior.

For example:

instructions:
    "You are a Tier 1 IT Support Agent.
     Your answers must be concise, professional,
     and limited strictly to troubleshooting
     network and VPN connectivity."

These instructions establish the agent's operational boundary.

The important concept is that an enterprise agent should not simply be told:

"You are a helpful assistant."

Instead, its responsibility should be clearly defined.

For example:

You are a Network Support Agent.

You can:
- Troubleshoot VPN connectivity
- Troubleshoot DNS problems
- Explain network configuration issues

You cannot:
- Answer HR questions
- Provide financial advice
- Modify production systems

The instructions therefore act as an important behavioral boundary.

Microsoft Agent Framework and Microsoft.Extensions.AI

The architecture behind the agent is also important.

The Microsoft Agent Framework provides the agent abstraction, while Microsoft.Extensions.AI provides the common AI interfaces used to communicate with the underlying model.

The relationship is approximately:

Your C# Application
        ↓
Microsoft Agent Framework
        ↓
AIAgent
        ↓
Microsoft.Extensions.AI
        ↓
IChatClient
        ↓
Azure OpenAI
        ↓
GPT Model

This separation prevents the agent itself from becoming tightly coupled to a specific AI provider.

Step 1 – Read the Azure Configuration

The first part of the code retrieves the Azure OpenAI endpoint and deployment name.

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";

Environment.GetEnvironmentVariable() reads a value from the operating system's environment variables.

This is preferable to putting sensitive configuration directly into the source code.

The ?? operator provides a fallback behavior:

Endpoint
   ↓
Environment Variable
   ↓
Missing?
   ↓
Throw Exception

For the deployment name, the code provides a default value of gpt-5-mini if the environment variable isn't available.

Step 2 – Create the IChatClient

Next, the code creates the Azure OpenAI client and converts it into the standard IChatClient abstraction.

IChatClient chatClient = new AzureOpenAIClient(
        new Uri(endpoint),
        new AzureCliCredential())
    .GetChatClient(deploymentName)
    .AsIChatClient();

There are several important concepts here.

AzureOpenAIClient

AzureOpenAIClient belongs to the Azure OpenAI SDK and provides communication with the Azure-hosted OpenAI resource.

AzureOpenAIClient
       ↓
Azure OpenAI Service

AzureCliCredential

new AzureCliCredential()

This comes from the Azure.Identity namespace.

It uses the Azure CLI authentication established earlier with:

az login

So the application doesn't need an API key in the source code.

az login
   ↓
Microsoft Entra ID
   ↓
AzureCliCredential
   ↓
AzureOpenAIClient

This is especially useful during local development.

Step 3 – Select the Model Deployment

The following method selects the deployed model:

.GetChatClient(deploymentName)

The deploymentName identifies the model deployment that was created in Microsoft Foundry/Azure.

For example:

deploymentName
     ↓
"gpt-5-mini"
     ↓
Azure AI Deployment

The application therefore knows which deployed model should process the request.

Step 4 – Convert to IChatClient

This is one of the most important parts:

.AsIChatClient();

AsIChatClient() converts the provider-specific Azure chat client into the standardized IChatClient abstraction from Microsoft.Extensions.AI.

Instead of the rest of the application depending directly on AzureOpenAIClient, it can work with:

IChatClient

Conceptually:

             IChatClient
                 ↑
       +---------+---------+
       |                   |
 Azure OpenAI           Other Provider
       |                   |
       +---------+---------+
                 |
            Same Application

This abstraction makes the AI integration more flexible.

Step 5 – Create the AI Agent

Now the actual agent is created:

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."
);

AIAgent represents the agent entity from the Microsoft Agent Framework.

The important part is:

chatClient.AsAIAgent(...)

This extension method takes the existing IChatClient and adds the agent abstraction around it.

So the architecture changes from:

IChatClient
    ↓
LLM

to:

IChatClient
    ↓
AIAgent
    ↓
LLM

The agent now has its own identity and behavioral instructions.

Step 6 – Execute the Agent

The user request is stored in a variable:

string userIssue =
    "I am getting a DNS resolution error when connecting " +
    "to the corporate VPN from a coffee shop. Keep your answers brief.";

Then the request is sent to the agent:

AgentResponse response =
    await supportAgent.RunAsync(userIssue);

RunAsync() is the execution method used to run the agent against the supplied user input.

Conceptually:

User Issue
    ↓
RunAsync()
    ↓
AIAgent
    ↓
Agent Instructions
    ↓
IChatClient
    ↓
Azure OpenAI
    ↓
Response

The result is represented by:

AgentResponse

and the generated text is available through:

response.Text

Complete Execution Flow

The complete application is therefore quite small:

                 Program.cs
                     |
                     ↓
          Read Environment Variables
                     |
                     ↓
            AzureCliCredential
                     |
                     ↓
             AzureOpenAIClient
                     |
                     ↓
                IChatClient
                     |
                     ↓
                AIAgent
          Name + Instructions
                     |
                     ↓
              RunAsync()
                     |
                     ↓
              Azure OpenAI
                     |
                     ↓
              AgentResponse
                     |
                     ↓
                response.Text

Complete Code

using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;

// 1. Read configuration
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. Create the universal chat client
IChatClient chatClient = new AzureOpenAIClient(
        new Uri(endpoint),
        new AzureCliCredential())
    .GetChatClient(deploymentName)
    .AsIChatClient();

// 3. Create the AI agent
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}");

What Has Changed from a Simple LLM Call?

The fundamental difference is architectural.

Traditional approach

Prompt
  ↓
IChatClient
  ↓
LLM
  ↓
Text

The application is mainly responsible for constructing prompts and processing responses.

Agent approach

User Request
     ↓
Named Agent
     ↓
Defined Instructions
     ↓
Agent Execution
     ↓
IChatClient
     ↓
LLM
     ↓
AgentResponse

The application now has an entity representing a specific AI worker.

That entity can later be extended with additional capabilities:

                NetworkSupport Agent
                        |
          +-------------+-------------+
          |             |             |
       Tools          Memory        State
          |             |             |
       APIs          Context       History
          |
      External
      Systems

This is why creating the first AIAgent is an important transition in agentic AI development.

Key Takeaway

The first agent is intentionally simple. It has only three essential pieces:

AIAgent
  |
  +-- Name
  |
  +-- Instructions
  |
  +-- IChatClient

The name gives the agent its identity, the instructions define its responsibility and boundaries, and the IChatClient provides the underlying AI capability.

The next major step is to make the agent useful beyond generating text by giving it tools and memory, allowing it to interact with external systems and maintain context across interactions.

← Back to Articles