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.