|
| 1 | +--- |
| 2 | +title: Agentic app with LangGraph or Azure AI Foundry (Node.js) |
| 3 | +description: Learn how to quickly deploy a production-ready, agentic web application using Node.js with Azure App Service, LangGraph, and Azure AI Foundry Agent Service. |
| 4 | +ms.service: azure-app-service |
| 5 | +author: cephalin |
| 6 | +ms.author: cephalin |
| 7 | +ms.devlang: csharp |
| 8 | +ms.topic: tutorial |
| 9 | +ms.date: 06/25/2025 |
| 10 | +ms.custom: |
| 11 | + - devx-track-javascript |
| 12 | +ms.collection: ce-skilling-ai-copilot |
| 13 | +--- |
| 14 | + |
| 15 | +# Tutorial: Build an agentic web app in Azure App Service with LangGraph or Azure AI Foundry Agent Service (Node.js) |
| 16 | + |
| 17 | +This tutorial demonstrates how to add agentic capability to an existing data-driven Express.js CRUD application. It does this using two different approaches: LangGraph and Azure AI Foundry Agent Service. |
| 18 | + |
| 19 | +If your web application already has useful features, like shopping, hotel booking, or data management, it's relatively straightforward to add agent functionality to your web application by wrapping those functionalities in a plugin (for LangGraph) or as an OpenAPI endpoint (for AI Foundry Agent Service). In this tutorial, you start with a simple to-do list app. By the end, you'll be able to create, update, and manage tasks with an agent in an App Service app. |
| 20 | + |
| 21 | +### [LangGraph](#tab/langgraph) |
| 22 | + |
| 23 | + |
| 24 | +:::image type="content" source="media/tutorial-ai-agent-web-app-langgraph-foundry-node/langgraph-agent.png" alt-text="Screenshot of a chat completion session with a LangGraph agent."::: |
| 25 | + |
| 26 | +### [Azure AI Foundry Agent Service](#tab/aifoundry) |
| 27 | + |
| 28 | +:::image type="content" source="media/tutorial-ai-agent-web-app-langgraph-foundry-node/foundry-agent.png" alt-text="Screenshot of a chat completion session with an Azure AI Foundry agent."::: |
| 29 | + |
| 30 | +----- |
| 31 | + |
| 32 | +Both LangGraph and Azure AI Foundry Agent Service enable you to build agentic web applications with AI-driven capabilities. LangGraph is similar to Microsoft Semantic Kernel and is an SDK, but Semantic Kernel doesn't support JavaScript currently. The following table shows some of the considerations and trade-offs: |
| 33 | + |
| 34 | +| Consideration | LangGraph | Azure AI Foundry Agent Service | |
| 35 | +|--------------------|-------------------------------|----------------------------------------| |
| 36 | +| Performance | Fast (runs locally) | Slower (managed, remote service) | |
| 37 | +| Development | Full code, maximum control | Low code, rapid integration | |
| 38 | +| Testing | Manual/unit tests in code | Built-in playground for quick testing | |
| 39 | +| Scalability | App-managed | Azure-managed, autoscaled | |
| 40 | + |
| 41 | +In this tutorial, you learn how to: |
| 42 | + |
| 43 | +> [!div class="checklist"] |
| 44 | +> * Convert existing app functionality into a plugin for LangGraph. |
| 45 | +> * Add the plugin to a LangGraph agent and use it in a web app. |
| 46 | +> * Convert existing app functionaltiy into an OpenAPI endpoint for Azure AI Foundry Agent Service. |
| 47 | +> * Call an Azure AI Foundry agent in a web app. |
| 48 | +- Assign the required permissions for managed identity connectivity. |
| 49 | + |
| 50 | +## Prerequisites |
| 51 | + |
| 52 | +- An Azure account with an active subscription - [Create an account for free](https://azure.microsoft.com/free/nodejs). |
| 53 | +- GitHub account to use GitHub Codespaces - [Learn more about GitHub Codespaces](https://docs.github.com/codespaces/overview). |
| 54 | + |
| 55 | +## Open the sample with Codespaces |
| 56 | + |
| 57 | +The easiest way to get started is by using GitHub Codespaces, which provides a complete development environment with all required tools preinstalled. |
| 58 | + |
| 59 | +1. Navigate to the GitHub repository at [https://github.com/Azure-Samples/app-service-agentic-langgraph-foundry-node](https://github.com/Azure-Samples/app-service-agentic-langgraph-foundry-node). |
| 60 | + |
| 61 | +2. Select the **Code** button, select the **Codespaces** tab, and select **Create codespace on main**. |
| 62 | + |
| 63 | +3. Wait a few moments for your Codespace to initialize. When ready, you'll see a fully configured development environment in your browser. |
| 64 | + |
| 65 | +4. Run the application locally: |
| 66 | + |
| 67 | + ```bash |
| 68 | + npm install |
| 69 | + npm run build |
| 70 | + npm start |
| 71 | + ``` |
| 72 | + |
| 73 | +5. When you see **Your application running on port 3000 is available**, select **Open in Browser** and add a few tasks. |
| 74 | + |
| 75 | +## Review the agent code |
| 76 | + |
| 77 | +Both approaches use the same implementation pattern, where the agent is initialized on application start, and responds to user messages by POST requests. |
| 78 | + |
| 79 | +### [LangGraph](#tab/langgraph) |
| 80 | + |
| 81 | +The `LangGraphTaskAgent` is initialized in the constructor in *src/agents/LangGraphTaskAgent.ts*. The initialization code does the following: |
| 82 | + |
| 83 | +- Configures the [AzureChatOpenAI](https://js.langchain.com/docs/integrations/llms/azure/) client using environment variables. |
| 84 | +- Creates the prebuilt ReAct agent a set of CRUD tools for task management (see [LangGraph: How to use the prebuilt ReAct agent](https://langchain-ai.github.io/langgraphjs/how-tos/create-react-agent)). |
| 85 | +- Sets up memory management (see [LangGraph: How to add memory to the prebuilt ReAct agent](https://langchain-ai.github.io/langgraphjs/how-tos/react-memory/)). |
| 86 | + |
| 87 | +:::code language="typescript" source="~/app-service-agentic-langgraph-foundry-node/src/agents/LangGraphTaskAgent.ts" range="23-143" highlight="13-21,24-37,106-117" ::: |
| 88 | + |
| 89 | +### [Azure AI Foundry Agent Service](#tab/aifoundry) |
| 90 | + |
| 91 | +The `FoundryTaskAgent` is initialized in the constructor of *src/agents/FoundryTaskAgent.ts*. The initialization code does the following: |
| 92 | + |
| 93 | +- Creates an `AgentsClient` using Azure credentials. |
| 94 | +- Fetches the agent from Azure AI Foundry by name. |
| 95 | +- Creates a new thread for the session. |
| 96 | + |
| 97 | +:::code language="typescript" source="~/app-service-agentic-langgraph-foundry-node/src/agents/FoundryTaskAgent.ts" range="34-66" highlight="15,18,22" ::: |
| 98 | + |
| 99 | +This initialization code doesn't define any functionality for the agent, because you would typically build the agent in the Azure AI Foundry portal. As part of the example scenario, it also follows the OpenAPI pattern shown in [Add an App Service app as a tool in Azure AI Foundry Agent Service (Node.js)](tutorial-ai-integrate-azure-ai-agent-node.md), and makes its CRUD functionality available as an OpenAPI endpoint. This lets you add it to the agent later as a callable tool. |
| 100 | +
|
| 101 | +The OpenAPI code is defined in *src/routes/api.ts*. For example, the "GET /api/tasks" route defines `operationId` in the JSDoc Swagger comments, as required by the [OpenAPI spec tool in Azure AI Foundry](/azure/ai-foundry/agents/how-to/tools/openapi-spec#prerequisites), and `description` helps the agent determine how to call the API: |
| 102 | +
|
| 103 | +:::code language="csharp" source="~/app-service-agentic-langgraph-foundry-node/src/routes/api.ts" range="60-70" highlight="2-9" ::: |
| 104 | +
|
| 105 | +----- |
| 106 | +
|
| 107 | +## Deploy the sample application |
| 108 | +
|
| 109 | +The sample repository contains an Azure Developer CLI (AZD) template, which creates an App Service app with managed identity and deploys your sample application. |
| 110 | +
|
| 111 | +1. In the terminal, log into Azure using Azure Developer CLI: |
| 112 | +
|
| 113 | + ```bash |
| 114 | + azd auth login |
| 115 | + ``` |
| 116 | +
|
| 117 | + Follow the instructions to complete the authentication process. |
| 118 | +
|
| 119 | +4. Deploy the Azure App Service app with the AZD template: |
| 120 | +
|
| 121 | + ```bash |
| 122 | + azd up |
| 123 | + ``` |
| 124 | +
|
| 125 | +1. When prompted, give the following answers: |
| 126 | + |
| 127 | + |Question |Answer | |
| 128 | + |---------|---------| |
| 129 | + |Enter a new environment name: | Type a unique name. | |
| 130 | + |Select an Azure Subscription to use: | Select the subscription. | |
| 131 | + |Pick a resource group to use: | Select **Create a new resource group**. | |
| 132 | + |Select a location to create the resource group in:| Select any region. The resources will actually be created in **East US 2**.| |
| 133 | + |Enter a name for the new resource group:| Type **Enter**.| |
| 134 | +
|
| 135 | +1. In the AZD output, find the URL of your app and navigate to it in the browser. The URL looks like this in the AZD output: |
| 136 | +
|
| 137 | + <pre> |
| 138 | + Deploying services (azd deploy) |
| 139 | + |
| 140 | + (✓) Done: Deploying service web |
| 141 | + - Endpoint: <URL> |
| 142 | + </pre> |
| 143 | +
|
| 144 | +1. Select the **OpenAPI schema** item to open the autogenerated OpenAPI schema at the default `/api/schema` path. You need this schema later. |
| 145 | +
|
| 146 | +1. After successful deployment, you'll see a URL for your deployed application. |
| 147 | + |
| 148 | + You now have an App Service app with a system-assigned managed identity. |
| 149 | + |
| 150 | +## Create and configure the Azure AI Foundry resource |
| 151 | + |
| 152 | +1. In the [Azure AI Foundry portal](https://ai.azure.com), deploy a model of your choice (see [Quickstart: Get started with Azure AI Foundry](/azure/ai-foundry/quickstarts/get-started-code?tabs=azure-ai-foundry&pivots=fdp-project)). A project and a default agent are created for you in the process. |
| 153 | + |
| 154 | +1. From the left menu, select **Overview**. |
| 155 | + |
| 156 | +1. Select **Azure AI Foundry** and copy the URL in **Azure AI Foundry project endpoint**. |
| 157 | + |
| 158 | +1. Select **Azure OpenAI** and copy the URL in **Azure OpenAI endpoint** for later. |
| 159 | + |
| 160 | + :::image type="content" source="media/tutorial-ai-agent-web-app-semantic-kernel-foundry-dotnet/foundry-project-endpoints.png" alt-text="Screenshot showing how to copy the OpenAI endpoint and the foundry project endpoint in the foundry portal."::: |
| 161 | + |
| 162 | +1. From the left menu, select **Agents**, then select the default agent. |
| 163 | + |
| 164 | +1. From the **Setup** pane, copy **Agent ID**, as well as the model name in **Deployment**. |
| 165 | + |
| 166 | + :::image type="content" source="media/tutorial-ai-agent-web-app-semantic-kernel-foundry-dotnet/foundry-agent-id-model.png" alt-text="Screenshot showing how to copy the agent ID and the model deployment name in the foundry portal."::: |
| 167 | + |
| 168 | +1. In the **Setup** pane, add an action with the OpenAPI spec tool. Use the OpenAPI schema that you get from the deployed web app and **anonymous** authentication. For detailed steps, see [How to use the OpenAPI spec tool](/azure/ai-foundry/agents/how-to/tools/openapi-spec-samples?pivots=portal). |
| 169 | + |
| 170 | + Your application code is already configured to include the server's `url` and `operationId`, which are needed by the agent. For more information, see [How to use Azure AI Foundry Agent Service with OpenAPI Specified Tools: Prerequisites](/azure/ai-foundry/agents/how-to/tools/openapi-spec#prerequisites). |
| 171 | +
|
| 172 | +1. Select **Try in playground** and test your AI Foundry agent with prompts like "*Show me all the tasks*." |
| 173 | +
|
| 174 | + If you get a valid response, the agent is making tool calls to the OpenAPI endpoint on your deployed web app. |
| 175 | +
|
| 176 | +## Assign required permissions |
| 177 | +
|
| 178 | +1. At the upper right corner of the foundry portal, select the name of the resource, then select **Resource Group** to open it in the Azure portal. |
| 179 | +
|
| 180 | + :::image type="content" source="media/tutorial-ai-agent-web-app-semantic-kernel-foundry-dotnet/go-to-azure-portal.png" alt-text="Screenshot showing how to quickly go to the resource group view for the foundry resource in the Azure portal."::: |
| 181 | +
|
| 182 | +1. Add a role for each of the two resources for the App Service app's manage identity using the following table: |
| 183 | + |
| 184 | + | Target resource | Required role | Needed for | |
| 185 | + |--------------------------------|-------------------------------------|-------------------------| |
| 186 | + | Azure AI Foundry | Cognitive Services OpenAI User | The chat completion service in the LangGraph. | |
| 187 | + | Azure AI Foundry Project | Azure AI User | Reading and calling the AI Foundry agent. | |
| 188 | + |
| 189 | + For instructions, see [Assign Azure roles using the Azure portal](/azure/role-based-access-control/role-assignments-portal). |
| 190 | + |
| 191 | +## Configure connection variables in your sample application |
| 192 | + |
| 193 | +1. Open *.env*. Using the values you copied earlier from the AI Foundry portal, configure the following variables: |
| 194 | + |
| 195 | + | Variable | Description | |
| 196 | + |-------------------------------|----------------------------------------------------------| |
| 197 | + | `AZURE_OPENAI_ENDPOINT` | Azure OpenAI endpoint (copied from the Overview page). This is needed by the LangGraph agent. | |
| 198 | + | `AZURE_OPENAI_DEPLOYMENT_NAME` | Model name in the deployment (copied from the Agents setup pane). This is needed by the LangGraph agent. | |
| 199 | + | `AZURE_AI_FOUNDRY_PROJECT_ENDPOINT` | Azure AI Foundry project endpoint (copied from Overview page). This is needed for the Azure AI Foundry Agent Service. | |
| 200 | + | `AZURE_AI_FOUNDRY_AGENT_ID` | Agent ID (copied from the Agents setup pane). This is needed to invoke an existing Azure AI Foundry agent. | |
| 201 | + |
| 202 | + > [!NOTE] |
| 203 | + > To keep the tutorial simple, you'll use these variables in *.env* instead of overwriting them with app settings in App Service. |
| 204 | +
|
| 205 | +1. Sign in to Azure with the Azure CLI: |
| 206 | +
|
| 207 | + ```bash |
| 208 | + az login |
| 209 | + ``` |
| 210 | +
|
| 211 | + This allows the Azure Identity client library in the sample code to receive an authentication token for the logged in user. Remember that you added the required role for this user earlier. |
| 212 | +
|
| 213 | +1. Run the application locally: |
| 214 | +
|
| 215 | + ```bash |
| 216 | + npm run build |
| 217 | + npm start |
| 218 | + ``` |
| 219 | +
|
| 220 | +1. When you see **Your application running on port 3000 is available**, select **Open in Browser**. |
| 221 | +
|
| 222 | +1. Select the **LangGraph Agent** link and the **Foundry Agent** link to try out the chat interface. If you get a response, your application is connecting successfully to the Azure AI Foundry resource. |
| 223 | +
|
| 224 | +1. Back in the GitHub codespace, deploy your app changes. |
| 225 | +
|
| 226 | + ```bash |
| 227 | + azd up |
| 228 | + ``` |
| 229 | +
|
| 230 | +1. Navigate to the deployed application again and test the chat agents. |
| 231 | +
|
| 232 | +### [LangGraph](#tab/langgraph) |
| 233 | +
|
| 234 | +
|
| 235 | +:::image type="content" source="media/tutorial-ai-agent-web-app-langgraph-foundry-node/langgraph-agent.png" alt-text="Screenshot of a chat completion session with a LangGraph agent."::: |
| 236 | +
|
| 237 | +### [Azure AI Foundry Agent Service](#tab/aifoundry) |
| 238 | +
|
| 239 | +:::image type="content" source="media/tutorial-ai-agent-web-app-langgraph-foundry-node/foundry-agent.png" alt-text="Screenshot of a chat completion session with an Azure AI Foundry agent."::: |
| 240 | +
|
| 241 | +----- |
| 242 | +
|
| 243 | +## Clean up resources |
| 244 | +
|
| 245 | +When you're done with the application, you can delete the App Service resources to avoid incurring further costs: |
| 246 | + |
| 247 | +```bash |
| 248 | +azd down --purge |
| 249 | +``` |
| 250 | + |
| 251 | +Since the AZD template doesn't include the Azure AI Foundry resources, you need to delete them manually if you want. |
| 252 | +
|
| 253 | +## More resources |
| 254 | +
|
| 255 | +- [Integrate AI into your Azure App Service applications](overview-ai-integration.md) |
| 256 | +- [What is Azure AI Foundry Agent Service?](/azure/ai-foundry/agents/overview) |
| 257 | +- [LangGraph.js - Quickstart](https://langchain-ai.github.io/langgraphjs/tutorials/quickstart/) |
0 commit comments