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

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.

Azure AI Foundry Project Endpoint

Next, we log in to Azure AI Foundry to retrieve the project endpoint, 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. Navigate to All Resources to view the list of AI resources that have been pre-provisioned for you.
  5. Select the resource name that starts with prj-contoso-agent-nnnnnn.
  6. Review the introduction guide and click Close.

  7. From the Overview sidebar menu, locate the Endpoints and keys -> Libraries -> Azure AI Foundry section, click the Copy icon to copy the Azure AI Foundry project endpoint.

    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 endpoint you copied from Azure AI Foundry into the .env file.

    PROJECT_ENDPOINT="<project endpoint>"

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

    MODEL_DEPLOYMENT_NAME="gpt-4o-mini"
PROJECT_ENDPOINT="<project endpoint>"

  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 endpoint you copied from Azure AI Foundry to the user secrets.

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

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

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

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

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-nnnn resource group in your Azure subscription.

  • An Azure AI Foundry hub named fdy-contoso-agent-nnnn
  • An Azure AI Foundry project named prj-contoso-agent-nnnn
  • A Serverless (pay-as-you-go) GPT-4o-mini model deployment named gpt-4o-mini. See pricing details here.

You will need 120K TPM quota availability for the gpt-4o-mini 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.

The script deploy.sh deploys to the westus 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 endpoint, model deployment name.

You'll see this file when you open the Python workspace in VS Code. Your .env file will look similar to this but with your project endpoint.

MODEL_DEPLOYMENT_NAME="gpt-4o-mini"
PROJECT_ENDPOINT="<your_project_endpoint>"

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 after you have opened the C# workspace in VS Code:

dotnet user-secrets list

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