Update readme with feedback (#74)

sophia-ramsey · web-flow · commit 3f813c1da89e · 2025-03-24T14:32:48.000-07:00
* #67: * emphasize increase quota requirements * change features section to improve flow * add additional info to quick deployment * add post deployment steps to ensure everything is deployed correctly * add guidance to use another deployment option upon failure * #60 * #59 * add recommended prompts/chats for after app is deployed * add short instructions for quick deploy
diff --git a/README.md b/README.md
@@ -6,22 +6,22 @@ MENU: [**FEATURES**](#features) \| [**QUICK DEPLOY**](#quick-deploy) \| [**GETTI
 
 This solution deploys a web-based chat application with an AI agent running in Azure Container Apps. The agent leverages the Azure AI Agent service and utilizes Azure AI Search for knowledge retrieval from uploaded files, enabling it to generate responses with citations. The solution also includes built-in monitoring capabilities with tracing to ensure easier troubleshooting and optimized performance.
 
-This solution creates an Azure AI Foundry hub, project and connected resources including Azure AI Services, AI Search and more. For more details about the resources that are created, view the [resources](#resources) documentation. There are options to enable Retrieval-Augmented Generation (RAG) and use logging, tracing, and monitoring. 
+This solution creates an Azure AI Foundry hub, project and connected resources including Azure AI Services, AI Search and more. More details about the resources that are created are located in the [resources](#resources) documentation. There are options to enable Retrieval-Augmented Generation (RAG) and use logging, tracing, and monitoring. 
 
 Instructions are provided for deployment through GitHub Codespaces, VS Code Dev Containers, and your local development environment.
 
 #### Architecture diagram
 
 ![Architecture diagram showing that user input used in conjunction with user identity to call app code running in Azure Container apps that processes the user input and generates a response to the user. The app code leverages Azure AI projects, Azure AI model inference, prompty, and Azure AI Search.](docs/architecture.png)
 
-## Quick Deploy
+## Getting Started
+
+### Quick Deploy
 
 | [![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/Azure-Samples/get-started-with-ai-agents) | [![Open in Dev Containers](https://img.shields.io/static/v1?style=for-the-badge&label=Dev%20Containers&message=Open&color=blue&logo=visualstudiocode)](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/Azure-Samples/get-started-with-ai-agents) | 
 |---|---|
 
-Github Codespaces and Dev Containers both allow you to download and deploy the code for development. Deploy to Azure will create the resources for later deployment. Detailed instructions for options to deploy this solution can be found in [deployment](#deployment).   
-
-## Getting Started
+Github Codespaces and Dev Containers both allow you to download and deploy the code for development. You can also continue with local development. Once you have selected your environment, follow the instructions below to customize and deploy your solution.    
 
 ### Prerequisites 
 
@@ -47,7 +47,9 @@ Make sure the following tools are installed:
 ## Development
 
 #### Code
-Download the project code:
+If you are using one of the [Quick Deploy options](#quick-deploy), open the codespace now. 
+
+If you are not using any of the Quick Deploy options, download the project code:
 
 ```shell
 git clone https://github.com/Azure-Samples/get-started-with-ai-agents.git
@@ -61,11 +63,11 @@ When you start a deployment, most parameters will have default values. You can c
 | **Setting** | **Description** |  **Default value** |
 |------------|----------------|  ------------|
 | **Azure Region** | Select a region with quota which supports your selected model. |   |
-| **Model** | Choose from the [list of models supported by Azure AI Agent Service](https://learn.microsoft.com/azure/ai-services/agents/concepts/model-region-support) for your selected region | gpt-4o-mini |  
-| **Model Format** | Choose from OpenAI or Microsoft, depending on your model | OpenAI |  
-| **Model Deployment Capacity** | Configure capacity for your model. Recommended value is 100k. | 50k |
-| **Embedding Model** | Choose from text-embedding-3-large, text-embedding-3-small, and text-embedding-ada-002. |  text-embedding-3-small |
-| **Embedding Model Capacity** | Configure capacity for your embedding model. |  50k |
+| **Model** | Choose from the [list of models supported by Azure AI Agent Service](https://learn.microsoft.com/azure/ai-services/agents/concepts/model-region-support) for your selected region. | gpt-4o-mini |  
+| **Model Format** | Choose from OpenAI or Microsoft, depending on your model. | OpenAI |  
+| **Model Deployment Capacity** | Configure capacity for your model. Recommended value is 100k. | 30k |
+| **Embedding Model** | Choose from text-embedding-3-large, text-embedding-3-small, and text-embedding-ada-002. This may only be deployed if Azure AI Search is enabled. |  text-embedding-3-small |
+| **Embedding Model Capacity** | Configure capacity for your embedding model. |  30k |
 | **Knowledge Retrieval** | Choose from OpenAI's file search or including Azure AI Search Index. |  OpenAI's file search |
 
 For a detailed description of customizable fields and instructions, view the [deployment customization guide](docs/deploy_customization.md).
@@ -85,10 +87,10 @@ By default, the template deploys OpenAI's [file search](https://learn.microsoft.
 To use index search, please set the local environment variable `USE_AZURE_AI_SEARCH_SERVICE` to `true` during the `azd up` command. In this case the Azure AI Search resource will be deployed and used.
 
 #### Logging
-If you want to enable logging to a file, uncomment the following line in Dockerfile located in the src directory:
+If you want to enable logging to a file, navigate to `src/Dockerfile` and edit the code to uncomment the following line:
 
  ```
- ENV APP_LOG_FILE=app.log
+ # ENV APP_LOG_FILE=app.log
  ```
 
  By default the file name app.log is used. You can provide your own file name by replacing app.log with the desired log file name.
@@ -98,8 +100,8 @@ If you want to enable logging to a file, uncomment the following line in Dockerf
 The provided file logging implementation is intended for development purposes only, specifically for testing with a single client/worker. It should not be used in production environments after the R&D phase.
 
 #### Tracing to Azure Monitor
-To enable tracing to Azure Monitor, modify the value of `ENABLE_AZURE_MONITOR_TRACING` environment variable to true in `Dockerfile` found in src directory:
-```code
+To enable tracing to Azure Monitor, navigate to `src/Dockerfile` and modify the value of `ENABLE_AZURE_MONITOR_TRACING` environment variable to true:
+```
 ENV ENABLE_AZURE_MONITOR_TRACING=true
 ```
 Note that the optional App Insights resource is required for tracing to Azure Monitor (it is created by default).
@@ -112,19 +114,18 @@ ENV AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED=true
 
 #### Quota Recommendations (Optional)
 
-The default for the model capacity in deployment is 50k tokens. For optimal performance, it is recommended to increase to 100k tokens. You can change the capacity by following the steps in [setting capacity and deployment SKU](docs/deploy_customization.md#customizing-model-deployments).
+The default for the model capacity in deployment is 30k tokens. For optimal performance, it is recommended to increase to 100k tokens. You can change the capacity by following the steps in [setting capacity and deployment SKU](docs/deploy_customization.md#customizing-model-deployments).
 
-* Navigate to the [Azure AI Foundry Portal](https://ai.azure.com/)
-* Select the AI Project you are using for this template if you are not already in the project.
-* Select Management center from the bottom left navigation menu
-* Select Quota, click the GlobalStandard dropdown and select the model and region you are using for this accelerator to see your available quota. Please note GPT-4o mini and text-embedding-ada-002 are used as default.
+* Navigate to the home screen of the [Azure AI Foundry Portal](https://ai.azure.com/)
+* Select Quota Management buttom at the bottom of the home screen
+* In the Quota tab, click the GlobalStandard dropdown and select the model and region you are using for this accelerator to see your available quota. Please note gpt-4o-mini and text-embedding-ada-002 are used as default.
 * Request more quota or delete any unused model deployments as needed.
 
 ## Deployment
 
 ### Deployment Options
 
-Pick from the options below to see step-by-step instructions for: GitHub Codespaces, VS Code Dev Containers, and Local Environments. 
+Pick from the options below to see step-by-step instructions for: GitHub Codespaces, VS Code Dev Containers, and Local Environments. If you encounter an issue with any of the following options, try a different one. 
 
 <details>
   <summary><b>GitHub Codespaces</b></summary>
@@ -205,7 +206,7 @@ You can optionally use a local development server to test app changes locally. M
 
 4. Duplicate `src/.env.sample` and name to `.env`.
 
-5. Fill in the environamnet variables in `.env`.
+5. Fill in the environment variables in `.env`.
 
 6. Run the local server:
 
@@ -230,6 +231,12 @@ Once you've opened the project in [Codespaces](#github-codespaces) or in [Dev Co
 
 2. (Optional) If you would like to customize the deployment to [disable resources](docs/deploy_customization.md#disabling-resources), [customize resource names](docs/deploy_customization.md#customizing-resource-names), [customize the models](docs/deploy_customization.md#customizing-model-deployments) or [increase quota](docs/deploy_customization.md#customizing-model-deployments), you can follow those steps now. 
 
+    ⚠️ **NOTE!** For optimal performance, the recommended quota is 100k tokens per minute. If you have the capacity, we recommend increasing the quota by running the following command: 
+    ```shell
+    azd env set AZURE_AI_AGENT_DEPLOYMENT_CAPACITY 100
+    ```
+    If you do not increase your quota, you may encounter rate limit issues. If needed, you can increase the quota after deployment by editing your model in the Models and Endpoints tab of the [Azure AI Foundry Portal](https://ai.azure.com/).
+
 3. Provision and deploy all the resources by running the following in get-started-with-ai-agents directory:
 
     ```shell
@@ -244,14 +251,20 @@ Once you've opened the project in [Codespaces](#github-codespaces) or in [Dev Co
 
     **NOTE!** If you get authorization failed and/or permission related errors during the deployment, please refer to the Azure account requirements in the [Prerequisites](#prerequisites) section. If you were recently granted these permissions, it may take a few minutes for the authorization to apply.
 
-5. When `azd` has finished deploying, you'll see an     endpoint URI in the command output. Visit that URI, and you should see the app! 🎉
+5. When `azd` has finished deploying, you'll see an endpoint URI in the command output. Visit that URI, and you should see the app! 🎉
 
-    You can view information about your deployment with:
-    ```shell
-    azd show
-    ```
+    * From here, you can interact with the agent. Try chatting with the agent by asking for a joke, or you could try a more specific query to see the agent's citation capabilities. By default, this solution uploads two documents from the `src/files` folder. To see the agent use this information, try asking about Contoso's products.
+
+    * You can view information about your deployment with:
+        ```shell
+        azd show
+        ```
+
+6. (Optional) Now that your app has deployed, you can view your resources in the Azure Portal and your deployments in Azure AI Foundry. 
+    * In the [Azure Portal](https://portal.azure.com/), navigate to your environment's resource group. The name will be `rg-[your environment name]`. Here, you should see your container app, storage account, and all of the other [resources](#resources) that are created in the deployment.
+    * In the [Azure AI Foundry Portal](https://ai.azure.com/), select your project. If you navigate to the Assistants tab, you should be able to view your new assistant, named `agent-template-assistant`. If you navigate to the Models and Endpoints tab, you should see your AI Services connection with your model deployments. 
 
-6. If you make further modification to the app code, you can deploy the updated version with:
+7. (Optional) If you make further modification to the app code, you can deploy the updated version with:
 
     ```shell
     azd deploy
@@ -264,12 +277,27 @@ Once you've opened the project in [Codespaces](#github-codespaces) or in [Dev Co
     >
     >Check carefully for any errors during deployment and the startup phase of the Azure Container App. If the container fails to start correctly after deployment, the application changes you made will not take effect, and Azure Container Apps will continue serving requests from the previous stable revision.
 
-7. You can optionally use a local development server to test app changes locally. To do so, follow the steps in [local deployment server](#local-development-server) after your app is deployed.
+8. (Optional) You can use a local development server to test app changes locally. To do so, follow the steps in [local deployment server](#local-development-server) after your app is deployed.
 
-8. When you are done using your application, you can now delete the resources by running `azd down`. This may take up to 20 minutes. 
+## Resource Clean-up
 
-⚠️ To avoid unnecessary costs, remember to take down your app if it's no longer in use,
-either by deleting the resource group in the Portal or running `azd down`.
+To prevent incurring unnecessary charges, it's important to clean up your Azure resources after completing your work with the application.
+
+- **When to Clean Up:**
+  - After you have finished testing or demonstrating the application.
+  - If the application is no longer needed or you have transitioned to a different project or environment.
+  - When you have completed development and are ready to decommission the application.
+
+- **Deleting Resources:**
+  To delete all associated resources and shut down the application, execute the following command:
+  
+    ```bash
+    azd down
+    ```
+
+    Please note that this process may take up to 20 minutes to complete.
+
+⚠️ Alternatively, you can delete the resource group directly from the Azure Portal to clean up resources.
 
 ## Tracing and Monitoring
 
diff --git a/infra/main.json b/infra/main.json
@@ -198,7 +198,7 @@
       "metadata": {
         "description": "Capacity of the chat deployment"
       },
-      "defaultValue": 50
+      "defaultValue": 30
     },
     "embedModelFormat": {
       "type": "string",
@@ -215,7 +215,8 @@
       "type": "string",
       "metadata": {
         "description": "Name of the embedding model to deploy"
-      }
+      },
+      "defaultValue": "text-embedding-3-small"
     },
     "embeddingDeploymentName": {
       "type": "string",
@@ -250,7 +251,7 @@
       "metadata": {
         "description": "Capacity of the embedding deployment"
       },
-      "defaultValue": 50
+      "defaultValue": 30
     },
     "useContainerRegistry": {
       "type": "bool",
diff --git a/infra/main.parameters.json b/infra/main.parameters.json
@@ -72,7 +72,7 @@
       "value": "${AZURE_AI_AGENT_DEPLOYMENT_SKU=GlobalStandard}"
     },
     "agentDeploymentCapacity": {
-      "value": "${AZURE_AI_AGENT_DEPLOYMENT_CAPACITY=50}"
+      "value": "${AZURE_AI_AGENT_DEPLOYMENT_CAPACITY=30}"
     },
     "embeddingDeploymentName": {
       "value": "${AZURE_AI_EMBED_DEPLOYMENT_NAME=text-embedding-3-small}"
@@ -90,7 +90,7 @@
       "value": "${AZURE_AI_EMBED_DEPLOYMENT_SKU=Standard}"
     },
     "embedDeploymentCapacity": {
-      "value": "${AZURE_AI_EMBED_DEPLOYMENT_CAPACITY=50}"
+      "value": "${AZURE_AI_EMBED_DEPLOYMENT_CAPACITY=30}"
     },
     "embeddingDeploymentDimensions": {
       "value": "${AZURE_AI_EMBED_DIMENSIONS=100}"
