Skip to content

Getting Started

Select your workshop experience:

Microsoft Build Attendees

The instructions on this page assume you are attending Microsoft Build 2025 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.

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 you are in, by using the language selector tabs. Note, don't switch languages mid-lab.

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#.

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 click Next.

    2. Use the Username and Password found in the top section of the Resources tab in the lab environment.

    3. Select OK, then Done.

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

  4. Once you've logged in, run the following command to assign the user role to the resource group:

    $subId = $(az account show --query id --output tsv) `
;$objectId = $(az ad signed-in-user show --query id -o tsv) `
; az role assignment create --role "f6c7c914-8db3-469d-8ca1-694a8f32e121" --assignee-object-id $objectId --scope /subscriptions/$subId/resourceGroups/"rg-agent-workshop" --assignee-principal-type 'User'

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

Open the Workshop

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

  1. From the terminal window, execute the following commands to clone the workshop repository, navigate to the relevant folder, set up a virtual environment, activate it, and install the required packages:

    git clone https://github.com/microsoft/build-your-first-agent-with-azure-ai-agent-service-workshop.git `
; cd build-your-first-agent-with-azure-ai-agent-service-workshop `
; python -m venv src/python/workshop/.venv `
; src\python\workshop\.venv\Scripts\activate `
; pip install -r src/python/workshop/requirements.txt `
; code --install-extension tomoki1207.pdf

  2. Open in VS Code. From the terminal window, run the following command:

    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. From a terminal window, execute the following commands to clone the workshop repository: 
    git clone https://github.com/microsoft/build-your-first-agent-with-azure-ai-agent-service-workshop.git

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

    code build-your-first-agent-with-azure-ai-agent-service-workshop\.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:

    start build-your-first-agent-with-azure-ai-agent-service-workshop\src\csharp\workshop\AgentWorkshop.sln

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

Project Connection String

Next, we log in to Azure AI Foundry to retrieve the project connection string, which the agent app uses to connect to the Azure AI Agents Service.

  1. Navigate to the Azure AI Foundry website.
  2. Select Sign in and use the Username and Password found in the top section of the Resources tab in the lab environment. Click on the Username and Password fields to automatically fill in the login details. Azure credentials
  3. Read the introduction to the Azure AI Foundry and click Got it.

  4. Ensure you are on the AI Foundry home page. Click the AI Foundry tab in the top left corner.

    AI Foundry home page

  5. Select the project name that starts with aip-.

    Select project

  6. Review the introduction guide and click Close.

  7. Locate the Project details section, click the Copy icon to copy the Project connection string.

    Copy connection string

Configure the Workshop

  1. Switch back to the workshop you opened in VS Code.

  2. Rename the .env.sample file to .env.

    • Select the .env.sample file in the VS Code Explorer panel.
    • Right-click the file and select Rename, or press F2.
    • Change the file name to .env and press Enter.

  3. Paste the Project connection string you copied from Azure AI Foundry into the .env file.

    PROJECT_CONNECTION_STRING="<your_project_connection_string>"

    Your .env file should look similar to this but with your project connection string.

    MODEL_DEPLOYMENT_NAME="gpt-4o"
BING_CONNECTION_NAME="groundingwithbingsearch"
PROJECT_CONNECTION_STRING="<your_project_connection_string>"

  4. Save the .env file.

Project Structure

Be sure to familiarize yourself with the key subfolders and files you’ll be working with throughout the workshop.

  1. The main.py file: The entry point for the app, containing its main logic.
  2. The sales_data.py file: The function logic to execute dynamic SQL queries against the SQLite database.
  3. The stream_event_handler.py file: Contains the event handler logic for token streaming.
  4. The shared/files folder: Contains the files created by the agent app.
  5. The shared/instructions folder: Contains the instructions passed to the LLM.

Lab folder structure

Configure the Workshop

  1. Open a terminal and navigate to the src/csharp/workshop/AgentWorkshop.Client folder.

    cd build-your-first-agent-with-azure-ai-agent-service-workshop\src\csharp\workshop\AgentWorkshop.Client

  2. Add the Project connection string you copied from Azure AI Foundry to the user secrets.

    dotnet user-secrets set "ConnectionStrings:AiAgentService" "<your_project_connection_string>"

  3. Add the Model deployment name to the user secrets.

    dotnet user-secrets set "Azure:ModelName" "gpt-4o"

Project Structure

Be sure to familiarize yourself with the key subfolders and files you’ll be working with throughout the workshop.

The workshop folder

  • The Lab1.cs, Lab2.cs, Lab3.cs files: The entry point for each lab, containing its agent logic.
  • The Program.cs file: The entry point for the app, containing its main logic.
  • The SalesData.cs file: The function logic to execute dynamic SQL queries against the SQLite database.

The shared folder

  • The files folder: Contains the files created by the agent app.
  • The fonts folder: Contains the multilingual fonts used by Code Interpreter.
  • The instructions folder: Contains the instructions passed to the LLM.

Lab folder structure

Pro Tips

Tips

  1. The Burger Menu in the right-hand panel of the lab environment offers additional features, including the Split Window View and the option to end the lab. The Split Window View allows you to maximize the lab environment to full screen, optimizing screen space. The lab's Instructions and Resources panel will open in a separate window.
  2. If the lab instructions are slow to scroll in the lab environment, try copying the instructions’ URL and opening it in your computer’s local browser for a smoother experience.
  3. If you have trouble viewing an image, simply click the image to enlarge it.

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 wherever applicable. Note, don't switch languages mid-lab.

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#.

Open the Workshop

The preferred way to run this workshop is using GitHub Codespaces. This option provides a pre-configured environment with all the tools and resources needed to complete the workshop. Alternatively, you can open the workshop locally using a Visual Studio Code Dev Container.

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

Open in GitHub Codespaces

Building the Codespace will take several minutes. You can continue reading the instructions while it builds.

Apple Silicon Users

The automated deployment script you’ll be running soon isn’t supported on Apple Silicon. Please run the deployment script from Codespaces or from macOS instead of the Dev Container.

Alternatively, you can open the project locally using a Visual Studio Code Dev Container, which will open the project in your local VS Code development environment using the Dev Containers extension.

  1. Start Docker Desktop (install it if not already installed)

  2. Select Dev Containers Open to open the project in a VS Code Dev Container.

    Open in Dev Containers

The process of building the Dev Container, which involves downloading and setting it up on your local system, will take several minutes. During this time, you can continue reading the instructions.

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. Ensure the Codespace has been created.
  2. In the Codespace, open a new terminal window by selecting Terminal > New Terminal from the VS Code menu.

  3. Run the following command to authenticate with Azure:

    az login --use-device-code

    Note

    You'll be prompted to open a browser link and log in to your Azure account. Be sure to copy the authentication code first.

    1. A browser window will open automatically, select your account type and click Next.
    2. Sign in with your Azure subscription Username and Password.
    3. Paste the authentication code.
    4. Select OK, then Done.

    Warning

    If you have multiple Azure tenants, then you will need to select the appropriate tenant when authenticating.

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

  4. Next, select the appropriate subscription from the command line.

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

Deploy the Azure Resources

The following resources will be created in the rg-contoso-agent-workshop resource group in your Azure subscription.

  • An Azure AI Foundry hub named agent-wksp
  • An Azure AI Foundry project named Agent Service Workshop
  • A Serverless (pay-as-you-go) GPT-4o model deployment named gpt-4o (Global 2024-08-06). See pricing details here.
  • A Grounding with Bing Search resource. See the documentation and pricing for details.

You will need 140K TPM quota availability for the gpt-4o Global Standard SKU, not because the agent uses lots of tokens, but due to the frequency of calls made by the agent to the model. Review your quota availability in the AI Foundry Management Center.

We have provided a bash script to automate the deployment of the resources required for the workshop. Alternatively, you may deploy resources manually using Azure AI Foundry studio. Select the desired tab.

The script deploy.sh deploys to the eastus2 region by default; edit the file to change the region or resource names. To run the script, open the VS Code terminal and run the following command:

cd infra && ./deploy.sh

Workshop Configuration

The deploy script generates the .env file, which contains the project connection string, model deployment name, and Bing connection name.

Your .env file should look similar to this but with your project connection string.

MODEL_DEPLOYMENT_NAME="gpt-4o"
BING_CONNECTION_NAME="groundingwithbingsearch"
PROJECT_CONNECTION_STRING="<your_project_connection_string>"

The automated deployment script stores project variables securely by using the Secret Manager feature for safe storage of app secrets in development in ASP.NET Core.

You can view the secrets by running the following command:

dotnet user-secrets list

Alternatively, if you prefer not to use the deploy.sh script you can deploy the resources manually using the Azure AI Foundry portal as follows:

  1. Navigate to the Azure AI Foundry web portal using your browser and sign in with your account.

  2. Select + Create project.

    • Name the project

      agent-workshop

    • Create a new hub named

      agent-workshop-hub

    • Select Create and wait for the project to be created.

  3. From My assets, select Models + endpoints.

  4. Select Deploy Model / Deploy Base Model.

    • Select gpt-4o from the model list, then select Confirm.

    • Name the deployment

      gpt-4o

    • Deployment type: Select Global Standard.

    • Select Customize.
    • Model version: Select 2024-08-06.
    • Tokens Per Minute Rate Limit: Select 140k.
    • Select Deploy.

Note

A specific version of GPT-4o may be required depending on your the region where you deployed your project. See Models: Assistants (Preview) for details.

Workshop Configuration

You'll need the project connection string to connect the agent app to the Azure AI Foundry project. You can find this string in the Azure AI Foundry portal in the Overview page for your Project agent-workshop (look in the Project details section).

Create the workshop configuration file with the following command:

cp src/python/workshop/.env.sample src/python/workshop/.env

Then edit the file src/python/workshop/.env to provide the Project Connection String.

  1. Open a new terminal window in VS Code.

  2. Run the following command to set the C# project path $CSHARP_PROJECT_PATH variable:

    CSHARP_PROJECT_PATH="src/csharp/workshop/AgentWorkshop.Client/AgentWorkshop.Client.csproj"

  3. Run the following command to set the ASP.NET Core safe secret for the project connection string:

    Replace <your_project_connection_string> with the actual connection string

    dotnet user-secrets set "ConnectionStrings:AiAgentService" "<your_project_connection_string>" --project "$CSHARP_PROJECT_PATH"

  4. Run the following command to set the ASP.NET Core safe secret for the model deployment name:

    dotnet user-secrets set "Azure:ModelName" "gpt-4o" --project "$CSHARP_PROJECT_PATH"

Selecting the Language Workspace

There are two 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. In Visual Studio Code, go to File > Open Workspace from File.

  2. Replace the default path with the following: 

    /workspaces/build-your-first-agent-with-azure-ai-agent-service-workshop/.vscode/

  3. Choose the file named python-workspace.code-workspace to open the workspace.

Project Structure

Be sure to familiarize yourself with the key folders and files you’ll be working with throughout the workshop.

The workshop folder

  • The main.py file: The entry point for the app, containing its main logic.
  • The sales_data.py file: The function logic to execute dynamic SQL queries against the SQLite database.
  • The stream_event_handler.py file: Contains the event handler logic for token streaming.

The shared folder

  • The files folder: Contains the files created by the agent app.
  • The fonts folder: Contains the multilingual fonts used by Code Interpreter.
  • 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: 

    /workspaces/build-your-first-agent-with-azure-ai-agent-service-workshop/.vscode/

  3. Choose the file named csharp-workspace.code-workspace to open the workspace.

Project Structure

Be sure to familiarize yourself with the key folders and files you’ll be working with throughout the workshop.

The workshop folder

  • The Lab1.cs, Lab2.cs, Lab3.cs files: The entry point for each lab, containing its agent logic.
  • The Program.cs file: The entry point for the app, containing its main logic.
  • The SalesData.cs file: The function logic to execute dynamic SQL queries against the SQLite database.

The shared folder

  • The files folder: Contains the files created by the agent app.
  • The fonts folder: Contains the multilingual fonts used by Code Interpreter.
  • The instructions folder: Contains the instructions passed to the LLM.

Lab folder structure