Skip to content

Setting Up Your Environment for the Workshop

Prerequisites

  • GitHub Account: If you don't have one yet, sign up on GitHub.
  • Azure Subscription: Sign up for a free Azure account.

Setup Source Code Repository

  1. From your browser, navigate to the agent-builder-workshop repository on GitHub. This repository has all the code and resources for the workshop.

  2. Fork this repository to your own GitHub account.
    Fork on GitHub

  3. The recommended way to work through this workshop is with GitHub Codespaces, which provides a ready-to-use environment with all required tools.
    Alternatively, you can use a Visual Studio Code to run the workshop locally.

    Using GitHub Codespaces: Once you've forked the repository, navigate to your forked repository on GitHub and click the green Code button, then select the Codespaces tab and click Create codespace on main.

    The Codespace will be pre-configured with all the necessary dependencies and tools to run the labs.

    It may take a few minutes for the Codespace to be created and all dependencies to be installed.

    If you encounter any issues, refer to the GitHub Codespaces documentation for troubleshooting tips and solutions.

Set Up Azure Infrastructure

Deploy the application to Azure. You will also connect to these resources when running the application from your local machine or Codespace.

1. Authenticate with Azure

First, authenticate with your Azure account using the Azure Developer CLI:

azd auth login --use-device-code

Follow the prompts to complete the authentication process in your browser.

2. Create and Configure Environment

Create a new environment for your Azure resources:

azd env new dev
azd env select dev
azd env set AZURE_LOCATION australiaeast

Azure Location

You can change australiaeast to any Azure region that supports AI Foundry. Common options include: eastus, westus2, westeurope, southeastasia.

3. Provision and Deploy

Deploy all required Azure resources using a single command:

azd up

This command will:

  • Provision all the necessary resources in Azure.
  • Deploy AI models.
  • Configure authentication and permissions

Deployment Time

The deployment process may take 5-10 minutes to complete. Please be patient while Azure provisions all resources.

Verify Deployment ✅

  1. Navigate to the Azure Portal and verify the resources under the resource group rg-aiagent-ws-dev.

Load Sample Data

Before running the application, you should load your database with sample data which includes chat history and flight information. This will allow you to test the agent's memory capabilities and the flight search tool in later labs.

  1. Navigate to notebooks/cosmosdb-insert.ipynb in your workspace
  2. Run the notebook cells to connect to your Azure Cosmos DB instance and insert sample records. You can run the cells in two ways:
    • Option 1 - Run All: Click the "Run All" button at the top of the notebook to execute all cells sequentially
    • Option 2 - Run Individual Cells: Click the play button next to each cell to run them one by one
  3. Verify that the data has been inserted successfully by checking the output messages in the notebook. You should see confirmation messages for each record inserted.

Running the Application Locally

To work through the labs, you need to run both the backend (.NET) and frontend (React) applications simultaneously.

1. Start the Backend Server

  • Navigate to the backend folder:

    cd src/backend

  • Start the backend server by running the following command. This will start the backend API server on http://localhost:5001

    dotnet run

2. Start the Frontend Development Server

  • In a separate terminal, navigate to the frontend folder by running the following command:

    cd src/frontend

  • Install the required npm packages (if you haven't already):

    npm install

  • Build the frontend application:

    npm run build

  • Start the frontend server. The frontend is configured to communicate with the backend API on port 5001:

    npm start

To access the frontend application:

  • Local Development: Open your browser to http://localhost:3000
  • GitHub Codespaces: When the frontend starts, Codespaces will automatically forward port 3000. Go to the Ports panel in VS Code, find port 3000, and click the globe icon (🌐) to open the frontend in your browser.

3. Test Your Setup

  • API Testing: Navigate to the file src/backend/ContosoTravelAgent.http in the code repository.

    This file contains HTTP requests that you can use to interact with the backend API. To send a request, click on the Send Request link above each request in the file.

  • Web Application Testing: Open your web browser and navigate to http://localhost:3000.

    Click on the New Chat button to start a new conversation with the travel assistant.

    Send a few messages to verify that the frontend and backend are communicating correctly.

(Optional) Set Up Aspire Dashboard for Observability

The .NET Aspire Dashboard provides a web-based UI for viewing OpenTelemetry traces, metrics, and logs in real-time. This is useful for monitoring your agent's behavior and debugging .

Refer to the Aspire Dashboard Setup Guide for detailed instructions on how to set up the dashboard locally using Docker.

GitHub Codespaces Limitations

Running Docker containers in GitHub Codespaces may have limitations depending on your configuration. If you encounter issues running the Aspire Dashboard in Codespaces, you can skip this optional step and still complete all labs. The dashboard provides enhanced observability but is not required.

Completed Source Code

The complete source code for all labs is available in the completed branch of the repository. You can switch to this branch at any time to view the final implementation.

View Completed Code