Skip to content

Commit bc4d716

Browse files
sophia-ramseysophia-ramsey
authored
update readme with bug bash issues and template validation (#54)
Restructures readme, adds quick deploy section. Addresses comments from bug bash and conforms with template validation. Bug Bash readme issues (from chat template + agents template): * Include additional details in the deployment section of the ReadMe file * "Deployment options" could be added before "deployment" section in Read Me file * #39 Code validation template issues: * now includes `Features`, `Getting Started`, and `Guidance`
1 parent dfab9d5 commit bc4d716

File tree

1 file changed

+114
-84
lines changed

1 file changed

+114
-84
lines changed

‎README.md

Lines changed: 114 additions & 84 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,25 @@
11
# Getting Started with Agents Using Azure AI Foundry
22

3-
MENU: [**PREREQUISITES**](#prerequisites) \| [**DEVELOPMENT**](#development) \| [**DEPLOYMENT**](#deployment) \| [**TRACING AND MONITORING**](#tracing-and-monitoring) \| [**DEVELOPMENT OPTIONS**](#development-options) \| [**SUPPORTING DOCUMENTATION**](#supporting-documentation) \| [**TROUBLESHOOTING**](#troubleshooting)
4-
<!-- TODO: rename repo azure-ai-agents-chat -->
3+
MENU: [**FEATURES**](#features) \| [**QUICK DEPLOY**](#quick-deploy) \| [**GETTING STARTED**](#getting-started) \| [**DEVELOPMENT**](#development) \| [**DEPLOYMENT**](#deployment) \| [**TRACING AND MONITORING**](#tracing-and-monitoring) \| [**DEVELOPMENT OPTIONS**](#development-options) \| [**GUIDANCE**](#guidance) \| [**TROUBLESHOOTING**](#troubleshooting)
54

6-
This project creates an Azure AI Foundry hub, project and connected resources including Azure AI Services, AI Search and more. It deploys an agent chat application to Azure Container Apps that uses Azure File Search with uploaded files and can provide citations.
5+
## Features
76

7+
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.
8+
9+
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.
10+
11+
Instructions are provided for deployment through GitHub Codespaces, VS Code Dev Containers, and your local development environment.
12+
13+
#### Architecture diagram
814

915
![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)
1016

17+
## Quick Deploy
1118

12-
## Running the Template
19+
| [![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) | |
20+
|---|---|---|
21+
22+
## Getting Started
1323

1424
### Prerequisites
1525

@@ -30,16 +40,7 @@ Make sure the following tools are installed:
3040
1. [Azure Developer CLI (azd)](https://aka.ms/install-azd) Install or update to the latest version. Instructions can be found on the linked page.
3141
2. [Python 3.9+](https://www.python.org/downloads/)
3242
3. [Git](https://git-scm.com/downloads)
33-
34-
#### Quota Recommendations (Optional)
35-
36-
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).
37-
38-
* Navigate to the [Azure AI Foundry Portal](https://ai.azure.com/)
39-
* Select the AI Project you are using for this template if you are not already in the project.
40-
* Select Management center from the bottom left navigation menu
41-
* 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.
42-
* Request more quota or delete any unused model deployments as needed.
43+
4. [Docker Desktop](https://www.docker.com/products/docker-desktop/)
4344

4445
## Development
4546

@@ -52,7 +53,7 @@ git clone https://github.com/Azure-Samples/get-started-with-ai-agents.git
5253
At this point you could make changes to the code if required. However, no changes are needed to deploy and test the app as shown in the next step.
5354

5455
#### How to configure Agent model and version
55-
<!-- TODO where do we want this? probably after downloading the code -->
56+
5657
By default, the template uses model `gpt-4o-mini`, version `2024-07-18` for text generation and `text-embedding-3-small` version `1` for embeddings. If you want to personalize your agent, you can change the default configuration for your agent. Additional details on changing your agent can be found in [customizing model deployments](docs/deploy_customization.md#customizing-model-deployments). For more information on the Azure OpenAI models and non-Microsoft models that can be used in your deployment, view the [list of models supported by Azure AI Agent Service](https://learn.microsoft.com/azure/ai-services/agents/concepts/model-region-support).
5758

5859
To specify the model (e.g. gpt-4o-mini, gpt-4o) that is deployed for the agent when `azd up` is called, set the following environment variables:
@@ -79,92 +80,82 @@ If you want to enable logging to a file, uncomment the following line in Dockerf
7980
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.
8081

8182
#### Tracing to Azure Monitor
82-
To enable tracing to Azure Monitor, modify the value of ENABLE_AZURE_MONITOR_TRACING environment variable to true in Dockerfile found in src directory:
83+
To enable tracing to Azure Monitor, modify the value of `ENABLE_AZURE_MONITOR_TRACING` environment variable to true in `Dockerfile` found in src directory:
8384
```code
8485
ENV ENABLE_AZURE_MONITOR_TRACING=true
8586
```
8687
Note that the optional App Insights resource is required for tracing to Azure Monitor (it is created by default).
8788

88-
To enable message contents to be included in the traces, set the following environment variable to true in the same Dockerfile. Note that the messages may contain personally identifiable information.
89+
To enable message contents to be included in the traces, set the following environment variable to true in the same `Dockerfile`. Note that the messages may contain personally identifiable information.
8990

9091
```code
9192
ENV AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED=true
9293
```
9394

94-
## Deployment
95-
96-
Once you've opened the project locally and made any desired adjustments, you can deploy it to Azure.
97-
98-
1. Login to Azure:
95+
#### Quota Recommendations (Optional)
9996

100-
```shell
101-
azd auth login
102-
```
97+
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).
10398

104-
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),
105-
or [customize the models](docs/deploy_customization.md#customizing-model-deployments), you can follow those steps now.
99+
* Navigate to the [Azure AI Foundry Portal](https://ai.azure.com/)
100+
* Select the AI Project you are using for this template if you are not already in the project.
101+
* Select Management center from the bottom left navigation menu
102+
* 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.
103+
* Request more quota or delete any unused model deployments as needed.
106104

107-
3. Provision and deploy all the resources:
105+
## Deployment
108106

109-
```shell
110-
azd up
111-
```
107+
### Deployment Options
112108

113-
It will prompt you to provide an `azd` environment name (like "azureaiapp"), select a subscription from your Azure account, and select a location which has quota for all the resources. Then it will provision the resources in your account and deploy the latest code. If you get an error or timeout with deployment, changing the location can help, as there may be availability constraints for the resources.
109+
Pick from the options below to see step-by-step instructions for: GitHub Codespaces, VS Code Dev Containers, and Local Environments.
114110

115-
**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.
111+
<details>
112+
<summary><b>GitHub Codespaces</b></summary>
116113

114+
#### GitHub Codespaces
117115

118-
4. When `azd` has finished deploying, you'll see an endpoint URI in the command output. Visit that URI, and you should see the app! 🎉
116+
You can run this template virtually by using GitHub Codespaces. The button will open a web-based VS Code instance in your browser:
119117

120-
You can view information about your deployment with:
121-
```shell
122-
azd show
123-
```
118+
1. Open the template (this may take several minutes):
124119

125-
5. If you make further modification to the app code, you can deploy the updated version with:
120+
[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/Azure-Samples/get-started-with-ai-agents)
126121

127-
```shell
128-
azd deploy
129-
```
130-
You can get more detailed output with the ```--debug``` parameter.
131-
```shell
132-
azd deploy --debug
133-
```
134-
Check for any errors during the deployment, since updated app code will not get deployed if errors occur.
122+
2. Open a terminal window
123+
3. Continue with the [deploying steps](#deploying-steps)
135124

136-
⚠️ To avoid unnecessary costs, remember to take down your app if it's no longer in use,
137-
either by deleting the resource group in the Portal or running `azd down`.
125+
</details>
138126

139-
## Tracing and Monitoring
127+
<details>
128+
<summary><b>VS Code Dev Containers</b></summary>
140129

141-
You can view console logs in Azure portal. You can get the link to the resource group with the azd tool:
142-
```shell
143-
azd show
144-
```
130+
#### VS Code Dev Containers
145131

146-
Or if you want to navigate from the Azure portal main page, select your resource group from the 'Recent' list, or by clicking the 'Resource groups' and searching your resource group there.
132+
A related option is VS Code Dev Containers, which will open the project in your local VS Code using the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers):
147133

148-
After accessing you resource group in Azure portal, choose your container app from the list of resources. Then open 'Monitoring' and 'Log Stream'. Choose the 'Application' radio button to view application logs. You can choose between real-time and historical using the corresponding radio buttons. Note that it may take some time for the historical view to be updated with the latest logs.
134+
1. Start Docker Desktop (install it if not already installed [Docker Desktop](https://www.docker.com/products/docker-desktop/))
135+
2. Open the project:
149136

150-
If you enabled logging to a file, you can view the log file by choosing 'Console' under the 'Monitoring' (same location as above for the console traces), opening the default console and then for example running the following command (replace app.log with the actual name of your log file):
137+
[![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)
151138

152-
```shell
153-
more app.log
154-
```
139+
3. In the VS Code window that opens, once the project files show up (this may take several minutes), open a terminal window.
140+
4. Continue with the [deploying steps](#deploying-steps)
141+
</details>
155142

156-
You can view the App Insights tracing in Azure AI Foundry. Select your project on the Azure AI Foundry page and then click 'Tracing'.
143+
<details>
144+
<summary><b>Local Environment</b></summary>
157145

158-
## Development Options
146+
#### Local Environment
159147

160-
In addition to the development setup documented above, the following development environment options can be used.
148+
1. Confirm that you have the required tools installed from the [prerequisites](#prerequisites) section and the code downloaded from the [code](#code) section
149+
2. Open the project folder in your terminal or editor
150+
3. Continue with the [deploying steps](#deploying-steps)
151+
</details>
161152

162153
<details>
163154
<summary><b>Local Development Server</b></summary>
164155

165156
#### Local Development Server
166157

167-
You can optionally use a local development server to test app changes locally. Make sure you first [deployed the app](#deployment) to Azure before running the development server.
158+
You can optionally use a local development server to test app changes locally. Make sure you first [deployed the app](#deploying-steps) to Azure before running the development server.
168159

169160
1. Create a [Python virtual environment](https://docs.python.org/3/tutorial/venv.html#creating-virtual-environments) and activate it.
170161

@@ -205,39 +196,78 @@ You can optionally use a local development server to test app changes locally. M
205196
6. Enter your message in the box.
206197
</details>
207198

208-
<details>
209-
<summary><b>GitHub Codespaces</b></summary>
199+
### Deploying Steps
210200

211-
#### Deploy in GitHub Codespaces
201+
Once you've opened the project in [Codespaces](#github-codespaces) or in [Dev Containers](#vs-code-dev-containers) or [locally](#local-environment), you can deploy it to Azure following the following steps.
212202
213-
You can run this template virtually by using GitHub Codespaces. The button will open a web-based VS Code instance in your browser:
203+
1. Login to Azure:
214204
215-
1. Open the template (this may take several minutes):
205+
```shell
206+
azd auth login
207+
```
216208
217-
[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/Azure-Samples/get-started-with-ai-agents)
209+
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.
218210
219-
2. Open a terminal window
220-
3. Continue with the [deploying steps](#deployment)
211+
3. Provision and deploy all the resources by running the following in get-started-with-ai-agents directory:
221212
222-
</details>
213+
```shell
214+
azd up
215+
```
223216
224-
<details>
225-
<summary><b>VS Code Dev Containers</b></summary>
217+
4. You will be prompted to provide an `azd` environment name (like "azureaiapp"), select a subscription from your Azure account, and select a location which has quota for all the resources. Then, it will provision the resources in your account and deploy the latest code.
226218
227-
#### VS Code Dev Containers
219+
* This deployment will take 8-12 minutes to provision the resources in your account and set up the solution with sample data.
220+
* If you get an error or timeout with deployment, changing the location can help, as there may be availability constraints for the resources.
228221
229-
A related option is VS Code Dev Containers, which will open the project in your local VS Code using the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers):
222+
**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.
230223
231-
1. Start Docker Desktop (install it if not already installed [Docker Desktop](https://www.docker.com/products/docker-desktop/))
232-
2. Open the project:
224+
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! 🎉
233225

234-
[![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)
226+
You can view information about your deployment with:
227+
```shell
228+
azd show
229+
```
235230

236-
3. In the VS Code window that opens, once the project files show up (this may take several minutes), open a terminal window.
237-
4. Continue with the [deploying steps](#deployment)
238-
</details>
231+
6. If you make further modification to the app code, you can deploy the updated version with:
232+
233+
```shell
234+
azd deploy
235+
```
236+
You can get more detailed output with the ```--debug``` parameter.
237+
```shell
238+
azd deploy --debug
239+
```
240+
>**Important:**
241+
>
242+
>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.
243+
244+
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.
245+
246+
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.
247+
248+
⚠️ To avoid unnecessary costs, remember to take down your app if it's no longer in use,
249+
either by deleting the resource group in the Portal or running `azd down`.
250+
251+
## Tracing and Monitoring
252+
253+
You can view console logs in Azure portal. You can get the link to the resource group with the azd tool:
254+
```shell
255+
azd show
256+
```
257+
258+
Or if you want to navigate from the Azure portal main page, select your resource group from the 'Recent' list, or by clicking the 'Resource groups' and searching your resource group there.
259+
260+
After accessing you resource group in Azure portal, choose your container app from the list of resources. Then open 'Monitoring' and 'Log Stream'. Choose the 'Application' radio button to view application logs. You can choose between real-time and historical using the corresponding radio buttons. Note that it may take some time for the historical view to be updated with the latest logs.
261+
262+
If you enabled logging to a file, you can view the log file by choosing 'Console' under the 'Monitoring' (same location as above for the console traces), opening the default console and then for example running the following command (replace app.log with the actual name of your log file):
263+
264+
```shell
265+
more app.log
266+
```
267+
268+
You can view the App Insights tracing in Azure AI Foundry. Select your project on the Azure AI Foundry page and then click 'Tracing'.
239269
240-
## Supporting Documentation
270+
## Guidance
241271
242272
#### Costs
243273

0 commit comments

Comments
 (0)