run-agent

title: Create and run an agent with Agent Framework
description: Learn how to create and run an AI agent using Agent Framework
zone_pivot_groups: programming-languages
author: westey-m
ms.topic: tutorial
ms.author: westey
ms.date: 09/15/2025
ms.service: agent-framework

Create and run an agent with Agent Framework

::: zone pivot="programming-language-csharp"

This tutorial shows you how to create and run an agent with Agent Framework, based on the Azure OpenAI Chat Completion service.

> [!IMPORTANT] > Agent Framework supports many different types of agents. This tutorial uses an agent based on a Chat Completion service, but all other agent types are run in the same way. For more information on other agent types and how to construct them, see the [Agent Framework user guide](../../user-guide/overview.md).

Prerequisites

Before you begin, ensure you have the following prerequisites:

• [.NET 8.0 SDK or later](https://dotnet.microsoft.com/download)
• [Azure OpenAI service endpoint and deployment configured](/azure/ai-foundry/openai/how-to/create-resource)
• [Azure CLI installed](/cli/azure/install-azure-cli) and [authenticated (for Azure credential authentication)](/cli/azure/authenticate-azure-cli)
• [User has the `Cognitive Services OpenAI User` or `Cognitive Services OpenAI Contributor` roles for the Azure OpenAI resource.](/azure/ai-foundry/openai/how-to/role-based-access-control)

> [!NOTE] > Microsoft Agent Framework is supported with all actively supported versions of .NET. For the purposes of this sample, we recommend the .NET 8 SDK or a later version.

> [!IMPORTANT] > This tutorial uses Azure OpenAI for the Chat Completion service, but you can use any inference service that provides a <xref:Microsoft.Extensions.AI.IChatClient> implementation.

Install NuGet packages

To use Microsoft Agent Framework with Azure OpenAI, you need to install the following NuGet packages:

dotnet add package Azure.AI.OpenAI --prerelease
dotnet add package Azure.Identity
dotnet add package Microsoft.Agents.AI.OpenAI --prerelease

Create the agent

• First, create a client for Azure OpenAI by providing the Azure OpenAI endpoint and using the same login as you used when authenticating with the Azure CLI in the [Prerequisites](#prerequisites) step.
• Then, get a chat client for communicating with the chat completion service, where you also specify the specific model deployment to use. Use one of the deployments that you created in the [Prerequisites](#prerequisites) step.
• Finally, create the agent, providing instructions and a name for the agent.

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

AIAgent agent = new AzureOpenAIClient(
    new Uri("https://<myresource>.openai.azure.com"),
    new AzureCliCredential())
        .GetChatClient("gpt-4o-mini")
        .AsAIAgent(instructions: "You are good at telling jokes.", name: "Joker");

Running the agent

To run the agent, call the `RunAsync` method on the agent instance, providing the user input. The agent will return an `AgentResponse` object, and calling `.ToString()` or `.Text` on this response object, provides the text result from the agent.

Console.WriteLine(await agent.RunAsync("Tell me a joke about a pirate."));

Sample output:

Why did the pirate go to school?

Because he wanted to improve his "arrr-ticulation"! 🏴‍☠️

Running the agent with streaming

To run the agent with streaming, call the `RunStreamingAsync` method on the agent instance, providing the user input. The agent will return a stream `AgentResponseUpdate` objects, and calling `.ToString()` or `.Text` on each update object provides the part of the text result contained in that update.

await foreach (var update in agent.RunStreamingAsync("Tell me a joke about a pirate."))
{
    Console.WriteLine(update);
}

Sample output:

Why
 did
 the
 pirate
 go
 to
 school
?


To
 improve
 his
 "
ar
rrrr
rr
tic
ulation
!"

Running the agent with ChatMessages

Instead of a simple string, you can also provide one or more `ChatMessage` objects to the `RunAsync` and `RunStreamingAsync` methods.

Here is an example with a single user message:

ChatMessage message = new(ChatRole.User, [
    new TextContent("Tell me a joke about this image?"),
    new UriContent("https://upload.wikimedia.org/wikipedia/commons/1/11/Joseph_Grimaldi.jpg", "image/jpeg")
]);

Console.WriteLine(await agent.RunAsync(message));

Sample output:

Why did the clown bring a bottle of sparkling water to the show?

Because he wanted to make a splash!

Here is an example with a system and user message:

ChatMessage systemMessage = new(
    ChatRole.System,
    """
    If the user asks you to tell a joke, refuse to do so, explaining that you are not a clown.
    Offer the user an interesting fact instead.
    """);
ChatMessage userMessage = new(ChatRole.User, "Tell me a joke about a pirate.");

Console.WriteLine(await agent.RunAsync([systemMessage, userMessage]));

Sample output:

I'm not a clown, but I can share an interesting fact! Did you know that pirates often revised the Jolly Roger flag? Depending on the pirate captain, it could feature different symbols like skulls, bones, or hourglasses, each representing their unique approach to piracy.

::: zone-end ::: zone pivot="programming-language-python"

This tutorial shows you how to create and run an agent with Agent Framework, based on the Azure OpenAI Chat Completion service.

> [!IMPORTANT] > Agent Framework supports many different types of agents. This tutorial uses an agent based on a Chat Completion service, but all other agent types are run in the same way. For more information on other agent types and how to construct them, see the [Agent Framework user guide](../../user-guide/overview.md).

Prerequisites

Before you begin, e