Skip to content

Open the Workshop

Select your workshop experience:

Microsoft Event Attendees

The instructions on this page assume you are attending an event and have access to a pre-configured lab environment. This environment provides an Azure subscription with all the tools and resources needed to complete the workshop.

Introduction

This workshop is designed to teach you about the Azure AI Agents Service and the associated SDK. It consists of multiple labs, each highlighting a specific feature of the Azure AI Agents Service. The labs are meant to be completed in order, as each one builds on the knowledge and work from the previous lab.

Workshop Cloud Resources

The following resources are pre-provisioned in your lab Azure subscription:

  • A resource group named rg-zava-agent-wks-nnnnnnnn
  • An Azure AI Foundry hub named fdy-zava-agent-wks-nnnnnnnn
  • An Azure AI Foundry project named prj-zava-agent-wks-nnnnnnnn
  • Two models are deployed: gpt-4o-mini and text-embedding-3-small. See pricing.
  • Azure Database for PostgreSQL Flexible Server (B1ms Burstable 32GB) database named pg-zava-agent-wks-nnnnnnnn. See pricing
  • Application Insights resource named appi-zava-agent-wks-nnnnnnnn. See pricing

Select Workshop Programming Language

The workshop is available in both Python and C#. Please make sure to select the language that fits the lab room or preference by using the language selector tabs. Note, don't switch languages mid-workshop.

Select the language tab that matches your lab room:

The default language for the workshop is set to Python.

The default language for the workshop is set to C#.

The C#/.NET version of this workshop is in beta and has known stability issues.

Ensure you read the troubleshooting guide section BEFORE starting the workshop. Else, select the Python version of the workshop.

Authenticate with Azure

You need to authenticate with Azure so the agent app can access the Azure AI Agents Service and models. Follow these steps:

  1. Open a terminal window. The terminal app is pinned to the Windows 11 taskbar.

    Open the terminal window

  2. Run the following command to authenticate with Azure:

    az login

    Note

    You'll be prompted to open a browser link and log in to your Azure account.

    1. A browser window will open automatically, select Work or school account and then select Continue.
    2. Use the Username and TAP (Temporary Access Pass) found in the top section of the Resources tab in the lab environment.
    3. Select Yes, all apps
    4. Select Done

  3. Then select the Default subscription from the command line, by selecting Enter.

  4. Leave the terminal window open for the next steps.

Authenticate with the DevTunnel Service

DevTunnel enables the Azure AI Agents Service to access your local MCP Server during the workshop.

devtunnel login

Note

You will be prompted to use the account you used for az login. Select the account and continue.

Leave the terminal window open for the next steps.

Open the Workshop

Follow these steps to open the workshop in Visual Studio Code:

The following command block updates the workshop repository, activates the Python virtual environment, and opens the project in VS Code.

Copy and paste the following command block to the terminal and press Enter.

; cd $HOME\aitour26-WRK540-unlock-your-agents-potential-with-model-context-protocol `
; git pull `
; .\src\python\workshop\.venv\Scripts\activate `
; code .vscode\python-workspace.code-workspace

When the project opens in VS Code, two notifications appear in the bottom right corner. Click ✖ to close both notifications.

  1. Open the workshop in Visual Studio Code. From the terminal window, run the following command:

    ; cd $HOME\aitour26-WRK540-unlock-your-agents-potential-with-model-context-protocol `
; git pull `
;code .vscode\csharp-workspace.code-workspace

When the project opens in VS Code, a notification will appear in the bottom right corner to install the C# extension. Click Install to install the C# extension, as this will provide the necessary features for C# development.

  1. Open the workshop in Visual Studio 2022. From the terminal window, run the following command:

    ; git pull `
;cd $HOME; start .\aitour26-WRK540-unlock-your-agents-potential-with-model-context-protocol\src\csharp\McpAgentWorkshop.slnx

    You may be asked what program to open the solution with. Select Visual Studio 2022.

Project Structure

Familiarize yourself with the key folders and files in the workspace you’ll be working with throughout the workshop.

The "workshop" folder

  • The app.py file: The entry point for the app, containing its main logic.

    Note the INSTRUCTIONS_FILE variable—it sets which instructions file the agent uses. You will update this variable in a later lab.

  • The resources.txt file: Contains the resources used by the agent app.

  • The .env file: Contains the environment variables used by the agent app.

The "mcp_server" folder

  • The sales_analysis.py file: The MCP Server with tools for sales analysis.

The "shared/instructions" folder

  • The instructions folder: Contains the instructions passed to the LLM.

Lab folder structure

Project Structure

The project uses Aspire to simplify building the agent application, managing the MCP server, and orchestrating all the external dependencies. The solution is comprised for four projects, all prefixed with McpAgentWorkshop:

  • AppHost: The Aspire orchestrator, and launch project for the workshop.
  • McpServer: The MCP server project.
  • ServiceDefaults: Default configuration for services, such as logging and telemetry.
  • WorkshopApi: The Agent API for the workshop. The core application logic is in the AgentService class.

In addition to the .NET projects in the solution, there is a shared folder (visible as a Solution Folder, and via the file explorer), which contains:

  • instructions: The instructions passed to the LLM.
  • scripts: Helper shell scripts for various tasks, these will be referred to when required.
  • webapp: The front-end client application. Note: This is a Python application, which Aspire will manage the lifecycle of.

Lab folder structure

Self-Guided Learners

These instructions are for self-guided learners who do not have access to a pre-configured lab environment. Follow these steps to set up your environment and begin the workshop.

Introduction

This workshop is designed to teach you about the Azure AI Agents Service and the associated SDK. It consists of multiple labs, each highlighting a specific feature of the Azure AI Agents Service. The labs are meant to be completed in order, as each one builds on the knowledge and work from the previous lab.

Prerequisites

  1. Access to an Azure subscription. If you don't have an Azure subscription, create a free account before you begin.
  2. You need a GitHub account. If you don’t have one, create it at GitHub.

Select Workshop Programming Language

The workshop is available in both Python and C#. Use the language selector tabs to choose your preferred language. Note, don't switch languages mid-workshop.

Select the tab for your preferred language:

The default language for the workshop is set to Python.

The default language for the workshop is set to C#.

The C#/.NET version of this workshop is in beta and has known stability issues.

Ensure you read the troubleshooting guide section BEFORE starting the workshop. Else, select the Python version of the workshop.

Open the Workshop

Preferred: GitHub Codespaces, which provides a preconfigured environment with all required tools. Alternatively, run locally with a Visual Studio Code Dev Container and Docker. Use the tabs below to choose.

Tip

Codespaces or Dev Container builds take about 5 minutes. Start the build, then continue reading while it completes.

Select Open in GitHub Codespaces to open the project in GitHub Codespaces.

Open in GitHub Codespaces

  1. Ensure you have the following installed on your local machine:

  2. Clone the repository to your local machine:

    git clone https://github.com/microsoft/aitour26-WRK540-unlock-your-agents-potential-with-model-context-protocol.git

  3. Open the cloned repository in Visual Studio Code.

  4. When prompted, select Reopen in Container to open the project in a Dev Container.

Authenticate Azure Services

Danger

Before proceeding, ensure that your Codespace or Dev Container is fully built and ready.

Authenticate with DevTunnel

DevTunnel provides a port forwarding service that will be used in the workshop to allow the Azure AI Agents Service to access the MCP Server you'll be running on your local development environment. Follow these steps to authenticate:

  1. From VS Code, press Ctrl + Shift + ` to open a new terminal window. Then run the following command:
  2. Run the following command to authenticate with DevTunnel:
devtunnel login

  1. Follow these steps to authenticate:

  2. Copy the Authentication Code to the clipboard.

  3. Press and hold the ctrl or cmd key.
  4. Select the authentication URL to open it in your browser.
  5. Paste the code and click Next.
  6. Pick an account and sign in.
  7. Select Continue

  8. Return to the terminal window in VS Code.

  9. Leave the terminal window open for the next steps.

Authenticate with Azure

Authenticate with Azure to allow the agent app access to the Azure AI Agents Service and models. Follow these steps:

  1. Then run the following command:

    az login --use-device-code

    Warning

    If you have multiple Azure tenants, specify the correct one using:

    az login --use-device-code --tenant <tenant_id>

  2. Follow these steps to authenticate:

    1. Copy the Authentication Code to the clipboard.
    2. Press and hold the ctrl or cmd key.
    3. Select the authentication URL to open it in your browser.
    4. Paste the code and click Next.
    5. Pick an account and sign in.
    6. Select Continue
    7. Return to the terminal window in VS Code.
    8. If prompted, select a subscription.

  3. Leave the terminal window open for the next steps.

Deploy the Azure Resources

This deployment creates the following resources in your Azure subscription.

  • A resource group named rg-zava-agent-wks-nnnnnnnn
  • An Azure AI Foundry hub named fdy-zava-agent-wks-nnnnnnnn
  • An Azure AI Foundry project named prj-zava-agent-wks-nnnnnnnn
  • Two models are deployed: gpt-4o-mini and text-embedding-3-small. See pricing.
  • Application Insights resource named appi-zava-agent-wks-nnnnnnnn. See pricing
  • To keep workshop costs low, PostgreSQL runs in a local container within your Codespace or Dev Container rather than as a cloud service. See Azure Database for PostgreSQL Flexible Server to learn about options for a managed PostgreSQL service.

Ensure you have at least the following model quotas" - 120K TPM quota for the gpt-4o-mini Global Standard SKU, as the agent makes frequent model calls. - 50K TPM for the text-embedding-3-small model Global Standard SKU. - Check your quota in the AI Foundry Management Center.

Automated Deployment

Run the following bash script to automate the deployment of the resources required for the workshop. The deploy.sh script deploys resources to the westus region by default. To run the script:

cd infra && ./deploy.sh

Workshop Configuration

Azure Resource Configuration

The deploy script generates the .env file, which contains the project and model endpoints, model deployment names, and Application Insights connection string. The .env file will automatically be saved in the src/python/workshop folder.

Your .env file will look similar to the following, updated with your values:

PROJECT_ENDPOINT="<your_project_endpoint>"
GPT_MODEL_DEPLOYMENT_NAME="<your_model_deployment_name>"
EMBEDDING_MODEL_DEPLOYMENT_NAME="<your_embedding_model_deployment_name>"
APPLICATIONINSIGHTS_CONNECTION_STRING="<your_application_insights_connection_string>"
AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED="true"
AZURE_OPENAI_ENDPOINT="<your_azure_openai_endpoint>"

Azure Resource Names

You'll also find a file named resources.txt in the workshop folder. This file contains the names of the Azure resources created during the deployment.

I'll look similar to the following:

Azure AI Foundry Resources:
- Resource Group Name: rg-zava-agent-wks-nnnnnnnn
- AI Project Name: prj-zava-agent-wks-nnnnnnnn
- Foundry Resource Name: fdy-zava-agent-wks-nnnnnnnn
- Application Insights Name: appi-zava-agent-wks-nnnnnnnn

The script securely stores project variables using the Secret Manager for ASP.NET Core development secrets.

You can view the secrets by running the following command after you have opened the C# workspace in VS Code:

dotnet user-secrets list

Open the VS Code Workspace

There are two VS Code workspaces in the workshop, one for Python and one for C#. The workspace contains the source code and all the files needed to complete the labs for each language. Choose the workspace that matches the language you want to work with.

  1. Copy the following path to the clipboard:

    /workspace/.vscode/python-workspace.code-workspace

  2. From the VS Code menu, select File then Open Workspace from File.

  3. Replace and paste the copied path name and select OK.

Project Structure

Familiarize yourself with the key folders and files in the workspace you’ll be working with throughout the workshop.

The "workshop" folder

  • The app.py file: The entry point for the app, containing its main logic.

    Note the INSTRUCTIONS_FILE variable—it sets which instructions file the agent uses. You will update this variable in a later lab.

  • The resources.txt file: Contains the resources used by the agent app.

  • The .env file: Contains the environment variables used by the agent app.

The "mcp_server" folder

  • The sales_analysis.py file: The MCP Server with tools for sales analysis.

The "shared/instructions" folder

  • The instructions folder: Contains the instructions passed to the LLM.

Lab folder structure

  1. In Visual Studio Code, go to File > Open Workspace from File.

  2. Replace the default path with the following:

    /workspace/.vscode/csharp-workspace.code-workspace

  3. Select OK to open the workspace.

Project Structure

The project uses Aspire to simplify building the agent application, managing the MCP server, and orchestrating all the external dependencies. The solution is comprised for four projects, all prefixed with McpAgentWorkshop:

  • AppHost: The Aspire orchestrator, and launch project for the workshop.
  • McpServer: The MCP server project.
  • ServiceDefaults: Default configuration for services, such as logging and telemetry.
  • WorkshopApi: The Agent API for the workshop. The core application logic is in the AgentService class.

In addition to the .NET projects in the solution, there is a shared folder (visible as a Solution Folder, and via the file explorer), which contains:

  • instructions: The instructions passed to the LLM.
  • scripts: Helper shell scripts for various tasks, these will be referred to when required.
  • webapp: The front-end client application. Note: This is a Python application, which Aspire will manage the lifecycle of.

Lab folder structure