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¶

From your browser, navigate to the agent-builder-workshop repository on GitHub. This repository has all the code and resources for the workshop.
Fork this repository to your own GitHub account.
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.

Understanding the Labs Structure¶

The workshop consists of the following labs:

The codebase for the workshop is organized into two main parts: the backend (.NET) and the frontend (React).

src/
├── backend/    # .NET backend code
└── frontend/   # React frontend code

The labs are expected to be completed in order as they build incrementally on the previous one. In most of the labs, you will only be modifying the agents in the backend codebase to implement new capabilities.

Set Up Azure Infrastructure¶

Create your Azure Environment by following the instructions in the Azure Resource Setup Guide. This will provision the necessary resources in Azure for completing the labs.

You will connect to these resources when running the application locally on your machine or in GitHub Codespaces.

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.

Navigate to notebooks/cosmosdb-insert.ipynb in your workspace
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
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.

Let's get started 👩‍💻🤖¶

Once your environment is set up, you are ready to begin the labs!

👉 Lab 1: Remember Me - Personalization & Memory

Happy coding!