Skip to content

Module-00.md

Latest commit

 

History

History
447 lines (296 loc) · 18.6 KB

Module-00.md

File metadata and controls

447 lines (296 loc) · 18.6 KB

Module 00 - Prerequisites - Deployment and Setup

< Home - Creating Your First Agent >

Introduction

In this Module, you'll deploy the Azure Services needed to run this workshop and get your local environment configured and ready. You will also learn about the structure of this workshop and get an overview of Multi-Agent Systems.

This workshop covers the complete journey from basic multi-agent systems to advanced architectural patterns using the Model Context Protocol (MCP) in Module 06.

Learning Objectives and Activities

  • Begin the deployment of the Azure Services
  • Learn the structure and get an overview of this workshop
  • Explore the core principals of multi-agent systems
  • Complete the configuration of your local environment
  • Compile and run the starter solution locally

Module Exercises

  1. Activity 1: Configure Workshop Environment
  2. Activity 2: Deploy Azure Services
  3. Activity 3: Workshop Structure and Overview Session
  4. Activity 4: Configure Environment Variables
  5. Activity 5: Compile and Run

Note: This module prepares your environment for the complete workshop, including the advanced Module 6 covering Model Context Protocol (MCP) architectural patterns.

Activity 1 Configure Workshop Environment

Complete the following tasks in order to prepare your environment for this workshop.

⚠️ Important: These pre-requisites are a hard requirement for successful completion of this workshop. If you do not have all three you will not be able to successfully complete this workshop.

Prerequisites

  • Laptop or workstation with administrator rights You will need to install packages and apps on your machine. (Alternatively you can run this workshop virtually in GitHub Codespaces)

  • Azure subscription with owner rights

  • Subscription access to Azure OpenAI service. Start here to Request Access to Azure OpenAI Service. If you have access, see below for ensuring enough quota to deploy.

    Checking Azure OpenAI quota limits

    For this sample to deploy successfully, there needs to be enough Azure OpenAI quota for the models used by this sample within your subscription. This sample deploys a new Azure OpenAI account with two models, gpt-4.1-mini with 30K tokens per minute and text-3-large with 5k tokens per minute. For more information on how to check your model quota and change it, see Manage Azure OpenAI Service Quota

    Azure Subscription Permission Requirements

    This solution deploys a user-assigned managed identity and defines then applies Azure Cosmos DB and Azure OpenAI RBAC permissions to this as well as your own Service Principal Id. You will need the following Azure RBAC roles assigned to your identity in your Azure subscription or Subscription Owner access which will give you both of the following.

Option for Beginners: Creating a Custom Security Group (Recommended)

If you're new to Azure security or don't have direct role assignments, you can create a custom security group with the necessary permissions. This approach is recommended for workshop participants and follows Azure best practices for role-based access control (RBAC).

Benefits of this approach:

  • Centralized permission management
  • Easier onboarding for multiple workshop participants
  • Follows principle of least privilege
  • Clear audit trail
  • Reusable for team members

Step 1: Create a Security Group

# Set variables
GROUP_NAME="Banking-Workshop-Developers"
GROUP_DESCRIPTION="Developers for Banking Multi-Agent Workshop with minimal required permissions"

# Create the group
GROUP_ID=$(az ad group create \
  --display-name "$GROUP_NAME" \
  --mail-nickname "banking-workshop-devs" \
  --description "$GROUP_DESCRIPTION" \
  --query id -o tsv)

echo "Created Group ID: $GROUP_ID"

Step 2: Add Your User to the Group

# Get your user's Object ID
USER_OBJECT_ID=$(az ad signed-in-user show --query id -o tsv)

# Add yourself to the group
az ad group member add \
  --group $GROUP_ID \
  --member-id $USER_OBJECT_ID

echo "User added to group"

Step 3: Assign Required Roles at Subscription Level

# Get subscription ID
SUBSCRIPTION_ID=$(az account show --query id -o tsv)
SCOPE="/subscriptions/$SUBSCRIPTION_ID"

# Assign all required roles to the group
az role assignment create --assignee $GROUP_ID --role "Managed Identity Contributor" --scope $SCOPE
az role assignment create --assignee $GROUP_ID --role "Cosmos DB Operator" --scope $SCOPE
az role assignment create --assignee $GROUP_ID --role "Cognitive Services OpenAI User" --scope $SCOPE
az role assignment create --assignee $GROUP_ID --role "Contributor" --scope $SCOPE

echo "All roles assigned to group"

Step 4: Verify Role Assignments

az role assignment list \
  --assignee $GROUP_ID \
  --query "[].{Role:roleDefinitionName, Scope:scope}" \
  -o table

Step 5: Refresh Your Credentials

After adding yourself to the group, you need to refresh your Azure credentials to pick up the new permissions:

# Log out completely
azd auth logout
az logout

# Log back in
az login
azd auth login

# Verify you're logged in
az account show

Note: Azure AD group membership changes can take 5-15 minutes to propagate. If you still get permission errors after logging back in, wait a few minutes and try again.

Step 6: Verify Your Group Membership

# Check your group memberships
az rest --method GET \
  --uri "https://graph.microsoft.com/v1.0/me/memberOf" \
  --query 'value[].displayName' -o table

You should see "Banking-Workshop-Developers" in the list.

Get Started

You can choose from the following options to get started with the workshop.

GitHub Codespaces

You can run this sample app and workshop virtually by using GitHub Codespaces. The button will open a web-based VS Code instance in your browser:

💡 Note: It is recommended to extend the time-out period for Codespaces in your GitHub profile. During lunchtime your Codespace may sit idle which will force you to relaunch your Codespace and you may lose any changes. To extend the time-out go to your profile in GitHub, click on Settings, then Codespaces. You can extend up to 240 minutes (4 hours). Be sure to change this back after the workshop to avoid excessive compute charges to your GitHub Codespaces.

  1. Open the template (this may take several minutes):

    Open in GitHub Codespaces

  2. Open a terminal in VS Code.

Local Environment using VS Code Dev Containers

  1. Install Docker Desktop, and VS Code along with the Dev Containers extension extension.

  2. Clone the repository and checkout the WorkShop_v2_PythonLangGraph branch:

    git clone -b WorkShop_v2_PythonLangGraph https://github.com/AzureCosmosDB/banking-multi-agent-workshop/
cd banking-multi-agent-workshop/01_exercises

  3. Open the repository in VS Code and select Reopen in Container when prompted.

  4. Wait for the container to build and start. This is a one time operation and may take a few minutes.

  5. Move on to the Deployment section.

Local Environment without VS Code Dev Containers

⚠️ NOTE For the MCP parts of the workshop in module 5 to function properly, you must be running in a Linux environment. If you are on Windows, consider installing WSL, switching to dev containers or running in Codespaces.

  1. To run the workshop locally on your machine, install the following:

    ⚠️ To complete the deployment from WSL into Azure you must first install PowerShell and Docker into WSL. You will also need to install the WSL extension into VS Code. You can then open a WSL session and type code . and follow the

  2. Clone the repository and navigate to the folder:

    git clone -b WorkShop_v2_PythonLangGraph https://github.com/AzureCosmosDB/banking-multi-agent-workshop/
cd banking-multi-agent-workshop/01_exercises

  3. Move on to the Deployment section.

Activity 2: Deploy Azure Services

Deployment

  1. From the terminal, switch to the WorkShop_v2_PythonLangGraph branch:

    git checkout WorkShop_v2_PythonLangGraph

  2. Navigate to the correct folder:

    cd 01_exercises/python/infra

  3. Log in to Azure using AZD.

    azd auth login

  4. If using Codespaces, also log in to Azure CLI.

    az login

  5. Provision the Azure services and deploy the application.

    azd up

This step will take approximately 10-15 minutes. If you encounter an error during step, first rerun azd up. This tends to correct most errors.

Important

If you encounter any errors during the deployment, rerun azd up to continue the deployment from where it left off. This will not create duplicate resources, and tends to resolve most issues.

  1. When the resources are finally deployed, you will see a message in the terminal like below:
Deploying services (azd deploy)

  (✓) Done: Deploying service ChatServiceWebApi
  - Endpoint: https://ca-webapi-6xbkqp3ybtbuw.whitemoss-86b36485.eastus2.azurecontainerapps.io/

Do you want to add some dummy data for testing? (yes/no): y

  1. Press y to load the data for the workshop.

  2. Press y to deploy the front end for the workshop.

⚠️ You may run into errors trying to deploy the web app from WSL. If so, modify your DNS to use public DNS server.

sudo cp /etc/resolv.conf /etc/resolv.conf.backup
echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf

Activity 3: Workshop Structure and Overview Session

While the Azure Services are deploying we will have a presentation to cover on the structure for this workshop for today as well as provide an introduction and overview of multi-agent systems.

Workshop Module Overview

This workshop consists of 6 progressive modules:

  • Module 0: Prerequisites and Setup (this module)
  • Module 1: Creating Your First Agent
  • Module 2: Connecting Agents to Memory
  • Module 3: Agent Specialization
  • Module 4: Multi-Agent Orchestration
  • Module 5: Converting to Model Context Protocol (MCP)
  • Module 6: Lessons Learned, Agent Futures, Q&A

Module 5 introduces advanced architectural patterns using the Model Context Protocol (MCP), showing how to convert your multi-agent system from native LangChain tools to a standardized, loosely-coupled architecture that enables better team collaboration and maintainability.

Activity 4: Configure Environment Variables

When you deploy this solution it automatically injects endpoints and configuration values for the required resources into a .env file at root (python) folder.

But you will still need to install dependencies to run the solution locally.

  1. Navigate to the python folder of the project.

  2. Create and activate a virtual environment (Linux/Mac/WSL/Codespaces):

    python -m venv .venv
source .venv/bin/activate

  3. Install the required dependencies for the project.

    pip install -r src/app/requirements.txt

    Note: If getting requirements.txt file not found when using GitHub codespaces, please navigate to the src/app folder and run the command there pip install -r requirements.txt

Activity 5: Compile and Run

Running the solution

  1. Navigate to the python folder of the project.

  2. Start the fastapi server.

    uvicorn src.app.banking_agents_api:app --reload --host 0.0.0.0 --port 63280

The API will be available at http://localhost:63280/docs. This has been pre-built with boilerplate code that will create chat sessions and store the chat history in Cosmos DB.

Run the Frontend on local machine

  1. Open a new terminal, navigate to the 01_exercises/frontend folder and run the following to start the application:

    npm install
ng serve

  2. Open your browser and navigate to http://localhost:4200/.

Run the Frontend App on Codespaces

  1. Open a new terminal, navigate to the 01_exercises/frontend folder and run the following to start the application:

    npm install
ng serve

  2. From the Ports tab:

    1. Right-click and select the Port Visibility option to set port ChatAPI (63280) as Public.
    2. For the port with the label Frontend app. Hover over the address and choose Open in Browser (second icon) to access the frontend application.

Exploring your new app

Lets try a couple of things:

  1. Try out the API by creating a chat session in the front end. This should return a response saying "Hello, I am not yet implemented".
  2. Navigate to the Cosmos DB account in the Azure portal to view the containers. You should see an entry in the Chat container. If you selected "yes" to the option during azd up, there will also be some transactional data in the OffersData, AccountsData, and Users containers as well.
  3. Take a look at the files in the src/app/services folder - these are the boilerplate code for interacting with the Cosmos DB and Azure OpenAI services.
  4. You will also see an empty file src/app/banking_agents.py as well as empty files in the src/app/tools and src/app/prompts folder. This is where you will build your multi-agent system!

Next, we will start building the agents that will be served by the API layer and interact with Cosmos DB and Azure OpenAI using LangGraph!

Deployment Validation

Use the steps below to validate that the solution was deployed successfully.

  • All Azure resources are deployed successfully
  • You can compile the solution in CodeSpaces or locally
  • You can start the project and it runs without errors

Common Issues and Troubleshooting

  1. Errors during azd deployment:

    • Service principal "not found" error.
      • Rerun azd up
    • If you are running on Windows with Powershell, you may get:
      • "error executing step command 'deploy --all': getting target resource: resource not found: unable to find a resource tagged with 'azd-service-name: ChatServiceWebApi'"
      • This is likely because you have used Az CLI before, and have an old default resource group name cached that is different from the one specified during azd up.
    • To resolve this:
      • Delete .azure in the root folder and .azd folders in your home directory (C:\Users\<user name>).
      • Start again, but first set resource group explicitly. Replace in the below with the name you intend to set for your environment:
        • azd env set AZURE_RESOURCE_GROUP rg-<environment name>
        • Then enter when prompted:
        • Enter a new environment name: <environment name>
        • Run azd auth login again
        • Then run azd up again.

  2. Azure OpenAI deployment issues:

    • Ensure your subscription has access to Azure OpenAI
    • Check regional availability

  3. Python environment issues:

    • Ensure correct Python version
    • Verify all dependencies are installed

  4. Your Codespace times out

    You need to restart your Codespace and backend and frontend for the app.

    Start the backend, go to the Terminal

    # Navigate to the python folder
cd 01_exercises/python

# start the virtual environment
source .venv/bin/activate

#Restart the backend
uvicorn src.app.banking_agents_api:app --reload --host 0.0.0.0 --port 63280

    Start the front end, open a New Terminal

    # Navigate to the frontend folder
cd 01_exercises/frontend

# start the frontend
ng serve

    Be sure to check the ports for the frontend (4200) and backend (63280) are still set to Public. Click the second icon, a globe in the Ports tab to open the frontend web app.

Success Criteria

To complete this Module successfully, you should be able to:

  • Verify that all services have been deployed successfully.
  • Have an open IDE or CodeSpaces session with the source code and environment variables loaded.
  • Be able to compile and run the application with no warnings or errors.

Next Steps

Proceed to Creating Your First Agent to begin building your multi-agent banking system. The complete learning path will take you through:

  1. Modules 1-4: Core multi-agent system development
  2. Module 5: Advanced MCP architectural patterns
  3. Module 6: Best practices, lessons learned, Q&A and wrap-up

Resources