|
| 1 | +--- |
| 2 | +page_type: sample |
| 3 | +languages: |
| 4 | + - azdeveloper |
| 5 | + - javascript |
| 6 | + - typescript |
| 7 | + - nodejs |
| 8 | + - bicep |
| 9 | +products: |
| 10 | + - azure |
| 11 | + - ai-services |
| 12 | + - azure-openai |
| 13 | +urlFragment: azure-openai-assistant-javascript |
| 14 | +name: Serverless Azure OpenAI Assistant Quick Start with Function Calling |
| 15 | +description: Azure OpenAI Assistants allows you to create AI assistants tailored to your needs through custom instructions and augmented by advanced tools like code interpreter, and custom functions. In this article, we provide an in-depth walkthrough of getting started with the Assistants API. |
| 16 | +--- |
| 17 | + |
| 18 | +<!-- YAML front-matter schema: https://review.learn.microsoft.com/help/contribute/samples/process/onboarding?branch=main#supported-metadata-fields-for-readmemd --> |
| 19 | + |
| 20 | + |
| 21 | +<!-- prettier-ignore --> |
| 22 | +<div align="center"> |
| 23 | + |
| 24 | +# Serverless Azure OpenAI Assistant Quick Start<br> Function Calling |
| 25 | + |
| 26 | +[](https://codespaces.new/Azure-Samples/azure-openai-assistant-javascript?hide_repo_select=true&ref=main&quickstart=true) |
| 27 | +[](https://github.com/Azure-Samples/azure-openai-assistant-javascript/actions) |
| 28 | + |
| 29 | +[](LICENSE) |
| 30 | + |
| 31 | +:star: Like and fork this sample to receive lastest changes and updates! |
| 32 | + |
| 33 | +[Overview](#overview) • [Get started](#get-started) • [Run the sample](#run-the-sample) • [Resources](#resources) |
| 34 | + |
| 35 | + <img src="./azure-openai-assistant-demo.png" alt="Screenshot showing the assistant app in action" width="640px" /> |
| 36 | + |
| 37 | +</div> |
| 38 | + |
| 39 | +This sample shows how to quickly get started with [OpenAI Assistant](https://learn.microsoft.com/azure/ai-services/openai/how-to/assistant) on Azure. The application is hosted on [Azure Static Web Apps](https://learn.microsoft.com/azure/static-web-apps/overview) and [Azure Functions](https://learn.microsoft.com/azure/azure-functions/functions-overview?pivots=programming-language-javascript). You can use it as a starting point for building more complex Assistant and Agent applications. |
| 40 | + |
| 41 | +## Overview |
| 42 | + |
| 43 | +Azure OpenAI Assistants allows you to create AI assistants tailored to your needs through custom instructions and augmented by advanced tools like code interpreter, and custom functions. In this article, we provide an in-depth walkthrough of getting started with the Assistants API. |
| 44 | + |
| 45 | +<div align="center"> |
| 46 | + <img src="./docs/architecture-diagram-assistant-javascript.png" alt="Screenshot showing the assistant app high level diagram" width="640px" /> |
| 47 | +</div> |
| 48 | + |
| 49 | +This application is built around two main components: |
| 50 | + |
| 51 | +- A simple HTML page with a vanilla CSS and JavaScript files, and hosted on [Azure Static Web Apps](https://learn.microsoft.com/azure/static-web-apps/overview). The code is located in the [`src`](../src/) folder. |
| 52 | + |
| 53 | +- A serverless API built with [Azure Functions](https://learn.microsoft.com/azure/azure-functions/functions-overview?pivots=programming-language-javascript) and using OpenAI JavaScript SDK. The code is located in the [`api`](../api/) folder. |
| 54 | + |
| 55 | +## Get started |
| 56 | + |
| 57 | +There are multiple ways to get started with this project. |
| 58 | + |
| 59 | +The quickest way is to use [GitHub Codespaces](#use-github-codespaces) that provides a preconfigured environment for you. Alternatively, you can [set up your local environment](#use-your-local-environment) following the instructions below. |
| 60 | + |
| 61 | +### Use your local environment |
| 62 | + |
| 63 | +You need to install following tools to work on your local machine: |
| 64 | + |
| 65 | +- [Node.js LTS](https://nodejs.org/download/) |
| 66 | +- [Azure Developer CLI](https://aka.ms/azure-dev/install) |
| 67 | +- [SWA CLI](https://github.com/Azure/static-web-apps-cli) |
| 68 | +- [Git](https://git-scm.com/downloads) |
| 69 | +- [PowerShell 7+](https://github.com/powershell/powershell) _(for Windows users only)_ |
| 70 | + - **Important**: Ensure you can run `pwsh.exe` from a PowerShell command. If this fails, you likely need to upgrade PowerShell. |
| 71 | + - Instead of Powershell, you can also use Git Bash or WSL to run the Azure Developer CLI commands. |
| 72 | +- (Optional - if you are not using SWA CLI) [Azure Functions Core Tools](https://learn.microsoft.com/azure/azure-functions/functions-run-local?tabs=macos%2Cisolated-process%2Cnode-v4%2Cpython-v2%2Chttp-trigger%2Ccontainer-apps&pivots=programming-language-javascript) _(should be installed automatically with NPM, only install manually if the API fails to start)_ |
| 73 | + |
| 74 | +Then you can get the project code: |
| 75 | + |
| 76 | +1. [**Fork**](https://github.com/Azure-Samples/azure-openai-assistant-javascript/fork) the project to create your own copy of this repository. |
| 77 | +2. On your forked repository, select the **Code** button, then the **Local** tab, and copy the URL of your forked repository. |
| 78 | +3. Open a terminal and run this command to clone the repo: <code> git clone <your-repo-url> </code> |
| 79 | + |
| 80 | +### Use GitHub Codespaces |
| 81 | + |
| 82 | +You can run this project directly in your browser by using GitHub Codespaces, which will open a web-based VS Code: |
| 83 | + |
| 84 | +[](https://codespaces.new/Azure-Samples/azure-openai-assistant-javascript?hide_repo_select=true&ref&quickstart=true) |
| 85 | + |
| 86 | +### Use a VS Code dev container |
| 87 | + |
| 88 | +A similar option to Codespaces is VS Code Dev Containers, that will open the project in your local VS Code instance using the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers). |
| 89 | + |
| 90 | +You will also need to have [Docker](https://www.docker.com/products/docker-desktop) installed on your machine to run the container. |
| 91 | + |
| 92 | +[](https://vscode.dev/redirect?url=vscode://ms-vscode-remote.remote-containers/cloneInVolume?url=https://github.com/Azure-Samples/azure-openai-assistant-javascript) |
| 93 | + |
| 94 | +## Run the sample locally (with Azure OpenAI models) |
| 95 | + |
| 96 | +First you need to provision the Azure resources needed to run the sample. Follow the instructions in the [Deploy the sample to Azure](#deploy-the-sample-to-azure) section to deploy the sample to Azure, then you'll be able to run the sample locally using the deployed Azure resources. |
| 97 | + |
| 98 | +Once your deployment is complete, you should see a `.env` file in the `api` folder. This file contains the environment variables needed to run the application using Azure resources. |
| 99 | + |
| 100 | +Also, in order for the Assistant to send emails, you need to provide the following env variables in the `./api/.env` file: |
| 101 | + |
| 102 | +``` |
| 103 | +EMAIL_RECEIVER="your email address" |
| 104 | +EMAIL_SENDER_NAME="Azure OpenAI Assistant" |
| 105 | +EMAIL_SENDER_USERNAME="sender email address" |
| 106 | +# Generate an application password from the MFA mobile application |
| 107 | +EMAIL_SENDER_APP_PASSWORD="foobar" |
| 108 | +``` |
| 109 | + |
| 110 | +**Important: Please follow [this guide](https://support.microsoft.com/account-billing/manage-app-passwords-for-two-step-verification-d6dc8c6d-4bf7-4851-ad95-6d07799387e9) to generate an Application Password if you are using MFA.** |
| 111 | + |
| 112 | +To run the sample, run the following command which will start the web app and the API locally: |
| 113 | + |
| 114 | +```bash |
| 115 | +npm install |
| 116 | +npm start |
| 117 | +``` |
| 118 | + |
| 119 | +Open the URL `http://localhost:4280` in your browser to start chatting with the Assistant. |
| 120 | + |
| 121 | +Note that the documents are uploaded automatically when deploying the sample to Azure with `azd up`. |
| 122 | + |
| 123 | +### Deploy the sample to Azure |
| 124 | + |
| 125 | +#### Azure prerequisites |
| 126 | + |
| 127 | +- **Azure account**. If you're new to Azure, [get an Azure account for free](https://azure.microsoft.com/free) to get free Azure credits to get started. If you're a student, you can also get free credits with [Azure for Students](https://aka.ms/azureforstudents). |
| 128 | +- **Azure subscription with access enabled for the Azure OpenAI service**. You can request access with [this form](https://aka.ms/oaiapply). |
| 129 | + |
| 130 | +#### Deploy the sample |
| 131 | + |
| 132 | +1. Open a terminal and navigate to the root of the project. |
| 133 | +2. Authenticate with Azure by running `azd auth login`. |
| 134 | +3. Run `azd up` to deploy the application to Azure. This will provision Azure resources, deploy this sample. |
| 135 | + - You will be prompted to select a base location for the resources. |
| 136 | + - By default, the OpenAI resource will be deployed to `swedencentral`. You can set a different location with `azd env set AZURE_OPENAI_RESOURCE_GROUP_LOCATION <location>`. Currently only a short list of locations is accepted. **Azure OpenAI Assistants are currently available in Sweden Central, East US 2, and Australia East. For more information about model availability in those regions, [see the models guide](https://learn.microsoft.com/azure/ai-services/openai/concepts/models).** |
| 137 | + |
| 138 | +The deployment process will take a few minutes. Once it's done, you'll see the URL of the web app in the terminal. |
| 139 | + |
| 140 | +You can now open the web app in your browser and start chatting with the bot. |
| 141 | + |
| 142 | +#### Clean up |
| 143 | + |
| 144 | +To clean up all the Azure resources created by this sample: |
| 145 | + |
| 146 | +1. Run `azd down --purge` |
| 147 | +2. When asked if you are sure you want to continue, enter `y` |
| 148 | + |
| 149 | +The resource group and all the resources will be deleted. |
| 150 | + |
| 151 | +## Resources |
| 152 | + |
| 153 | +Here are some resources to learn more about the technologies used in this sample: |
| 154 | + |
| 155 | +- [Get started using Azure OpenAI Assistants (Preview)](https://learn.microsoft.com/azure/ai-services/openai/assistants-quickstart?tabs=command-line%2Ctypescript&pivots=programming-language-javascript) |
| 156 | +- [Generative AI For Beginners](https://github.com/microsoft/generative-ai-for-beginners) |
| 157 | +- [Azure OpenAI Service](https://learn.microsoft.com/azure/ai-services/openai/overview) |
| 158 | +- [Azure Cosmos DB for MongoDB vCore](https://learn.microsoft.com/azure/cosmos-db/mongodb/vcore/) |
| 159 | +- [Azure OpenAI Assistant Builder](https://github.com/Azure-Samples/azure-openai-assistant-builder) |
| 160 | +- [Chat + Enterprise data with Azure OpenAI and Azure AI Search](https://github.com/Azure-Samples/azure-search-openai-javascript) |
| 161 | + |
| 162 | +You can also find [more Azure AI samples here](https://github.com/Azure-Samples/azureai-samples). |
| 163 | + |
| 164 | +## Troubleshooting |
| 165 | + |
| 166 | +If you can't find a solution to your problem, please [open an issue](https://github.com/Azure-Samples/azure-openai-assistant-javascript/issues) in this repository. |
| 167 | + |
| 168 | +## Contributing |
| 169 | + |
| 170 | +This project welcomes contributions and suggestions. Most contributions require you to agree to a |
| 171 | +Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us |
| 172 | +the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com. |
| 173 | + |
| 174 | +When you submit a pull request, a CLA bot will automatically determine whether you need to provide |
| 175 | +a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions |
| 176 | +provided by the bot. You will only need to do this once across all repos using our CLA. |
| 177 | + |
| 178 | +This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). |
| 179 | +For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or |
| 180 | +contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments. |
| 181 | + |
| 182 | +## Trademarks |
| 183 | + |
| 184 | +This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft |
| 185 | +trademarks or logos is subject to and must follow |
| 186 | +[Microsoft's Trademark & Brand Guidelines](https://www.microsoft.com/legal/intellectualproperty/trademarks/usage/general). |
| 187 | +Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. |
| 188 | +Any use of third-party trademarks or logos are subject to those third-party's policies. |
0 commit comments