Quickstart: Create an agent with the Agents SDK

This example shows you how to:

• Download and run the sample agent code from GitHub sample repos
• Create an agent using the Agents SDK
• Add events and responses
• Send messages
• Add AI services and orchestration

If you use the sample empty agent sample, the agent echoes the message you enter. This lets get started with the SDK. It isn't intended for use in production scenarios.

Prerequisites

You need a few things before you get started.

Set up and run the sample agent

The quickest way to get started is using the Microsoft 365 Agents Toolkit. The toolkit has built-in templates for Visual Studio and Visual Studio Code that use the Microsoft 365 Agents SDK, speeding up development time.

You can start with templates:

• Echo Agent/Empty Agent: Start from the basic scaffolding and add your own AI, orchestration and knowledge
• Weather Agent: Add in your Azure Foundry agent or OpenAI AI services and use configured orchestration with Semantic Kernel or LangChain

Other ways to get started are:

• Cloning and running the Empty/echo agent sample available on GitHub
• Using the CLI, as shown in the quickstart

The steps depend on the language you're using. Follow the instructions for your language of choice.

pip install -i https://test.pypi.org/simple/ microsoft-agents-core
pip install -i https://test.pypi.org/simple/ microsoft-agents-authorization
pip install -i https://test.pypi.org/simple/ microsoft-agents-connector
pip install -i https://test.pypi.org/simple/ microsoft-agents-builder
pip install -i https://test.pypi.org/simple/ microsoft-agents-authentication-msal
pip install -i https://test.pypi.org/simple/ microsoft-agents-hosting-aiohttp

The app creates a simple agent that echoes back the messages you send to it. You can now test your agent locally and build on it as desired.

Create an Agents SDK agent using CLI and code

You can also set up an agent using the Microsoft 365 Agents SDK directly via command line and code editor. Instructions are provided for .NET.

Set up a new project

First, create a new .NET Console Application project.

mkdir my_project
cd my_project
dotnet new console -n myexample
cd myexample

Next, install the Microsoft 365 Agents SDK:

dotnet add package microsoft.agents.hosting.aspnet.core

You may need to update the Agents SDK packages from NuGet.

Next, build, and run your project.

dotnet build
dotnet run

You should now see your console app running which outputs "Hello World." You can also navigate to your new folder and open the .csproj file you created and run it from Visual Studio (myexample.csproj).

With the project created, and Agents SDK libraries added to the project, you can now add elements from the Microsoft 365 Agents SDK.

Create an Agents SDK agent

An Agents SDK agent acts like a container (AgentApplication) and can also be created with other client services (for example, Microsoft Teams).

To begin, create some initial setup.

var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddControllers();
builder.Services.AddHttpClient();

builder.Services.AddSingleton<IStorage, MemoryStorage>();
builder.AddAgentApplicationOptions();

Next, add your agent:

builder.AddAgent( sp =>
{
    // Setup the Agent. 
    var agent = new AgentApplication(sp.GetRequiredService<AgentApplicationOptions>());

    // Respond to message events. 
    // We will add an event in the next step in 'Events and Responses' below
    return agent;
});

Finish building HTTP components:

var app = builder.Build();

// Configure the HTTP request pipeline.
app.UseRouting();
app.MapPost("/api/messages", async (HttpRequest request, HttpResponse response, IAgentHttpAdapter adapter, IAgent agent, CancellationToken cancellationToken) =>
{
    await adapter.ProcessAsync(request, response, agent, cancellationToken);
});


// Setup port and listening address.
var port = args.Length > 0 ? args[0] : "5000";
app.Urls.Add($"http://localhost:{port}");

// Start listening. 
await app.RunAsync();

This agent also listens for a message type activity and sends a message back

The container itself is an 'agent' implementing your chosen AI Service (for example, Azure OpenAI). The container manages the conversation using turns and activities.

Add events and responses

Use the OnActivity event to trigger when a new activity is sent from the client (for example, a user message).

Add your AI service or chat endpoint & use the SendActivityAsync method to send a response back to the requesting client (which can be from an AI service):

    agent.OnActivity(ActivityTypes.Message, async (turnContext, turnState, cancellationToken) =>
    {
        var text = turnContext.Activity.Text;
        await turnContext.SendActivityAsync(MessageFactory.Text($"Echo: {text}"), cancellationToken);
    });

You need to update the packages from NuGet. Specifically, pull the Hosting package and it also adds dependencies. If you want to add auth, additionally install the MSAL package microsoft.agents.authentication.msal.

To learn more about the agent and some of the basics, review the following sections.

Send Messages

The Agents SDK makes it easy to send different types of messages back, when required. The support for different types of messages saves developers time formatting different types, and takes advantage of common types of messages supported by a broad set of clients.

Messages can be sent using MessageFactory that supports types like text, images, cards, attachments, adaptive cards, and more.

Messages are constructed and sent back within the SendActivityAsync method:

    await turnContext.SendActivityAsync(MessageFactory.Text($"{response}"), cancellationToken);

Add AI services and orchestration to your agent

If you begin with the Empty/Echo agent sample or build an agent using the CLI, you need to add AI services and orchestration to enable more sophisticated behavior. A key feature of the Agents SDK is that you can make your choice of AI services and orchestrator and integrate these into your agent using their SDKs. Choose from Azure AI Foundry, Semantic Kernel, LangChain and more.

      var builder = Kernel.CreateBuilder();

      builder.AddAzureOpenAIChatCompletion(
      deploymentName: "gpt-4o-mini",
      endpoint: "url",
      apiKey: apiKey,
      apiVersion: apiVersion);

      var kernel = builder.Build();
      var result = await kernel.InvokePromptAsync(userInput);

Once there's a response or behavior from the orchestrator you want to send back to the user or service, you can send the response in the SendActivityAsync method.

      await turnContext.SendActivityAsync(MessageFactory.Text(result), cancellationToken);

There are multiple patterns to integrate AI services and orchestrators into your agent, depending on the functionality they bring and how you want to surface them in your agent. Check out an example of integration where we integrate Semantic Kernel directly into the agent at runtime.

Test your agent locally

npm run test