Tutorial: Build an agentic web app in Azure App Service with LangGraph or Foundry Agent Service (Python)

This tutorial demonstrates how to add agentic capability to an existing data-driven FastAPI CRUD application. It does this using two different approaches: LangGraph and Foundry Agent Service.

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 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.

LangGraph

Foundry Agent Service

Both LangGraph and Foundry Agent Service enable you to build agentic web applications with AI-driven capabilities. LangGraph is similar to Microsoft Agent Framework and is an SDK. The following table shows some of the considerations and trade-offs:

Consideration	LangGraph or Microsoft Agent Framework	Foundry Agent Service
Performance	Fast (runs locally)	Slower (managed, remote service)
Development	Full code, maximum control	Low code, rapid integration
Testing	Manual/unit tests in code	Built-in playground for quick testing
Scalability	App-managed	Azure-managed, autoscaled
Security guardrails	Custom implementation required	Built-in content safety and moderation
Identity	Custom implementation required	Built-in agent ID and authentication
Enterprise	Custom integration required	Built-in Microsoft 365/Teams deployment and Microsoft 365 integrated tool calls.

In this tutorial, you learn how to:

• Convert existing app functionality into a plugin for LangGraph.
• Add the plugin to a LangGraph agent and use it in a web app.
• Convert existing app functionality into an OpenAPI endpoint for Foundry Agent Service.
• Call a Foundry agent in a web app.
• Assign the required permissions for managed identity connectivity.

Prerequisites

• An Azure account with an active subscription - Create an account for free.
• GitHub account to use GitHub Codespaces - Learn more about GitHub Codespaces.

Open the sample with Codespaces

The easiest way to get started is by using GitHub Codespaces, which provides a complete development environment with all required tools preinstalled.

1. Navigate to the GitHub repository at https://github.com/Azure-Samples/app-service-agentic-langgraph-foundry-python.

2. Select the Code button, select the Codespaces tab, and select Create codespace on main.

3. Wait a few moments for your Codespace to initialize. When ready, you'll see a fully configured development environment in your browser.

4. Run the application locally:

   python3 -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt
   uvicorn src.app:app --host 0.0.0.0 --port 3000
   

5. When you see Your application running on port 3000 is available, select Open in Browser and add a few tasks.

   The agents aren't fully configured so they don't work yet. You'll configure them later.

Review the agent code

Both approaches use the same implementation pattern, where the agent is initialized on application start, and responds to user messages by POST requests.

LangGraph

The LangGraphTaskAgent is initialized in the constructor in src/agents/langgraph_task_agent.py. The initialization code does the following:

• Configures the AzureChatOpenAI client using environment variables.
• Creates the prebuilt ReAct agent with memory and a set of CRUD tools for task management (see LangGraph quickstart).
• Selects one server-managed conversation thread for the authenticated sample.

self.memory = InMemorySaver()
# App Service authentication protects this sample, which intentionally
# keeps one server-managed conversation thread per worker process.
self.thread_id = "authenticated-conversation"

try:
    endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
    deployment_name = os.getenv("AZURE_OPENAI_DEPLOYMENT_NAME")
    
    if not endpoint or not deployment_name:
        print("Azure OpenAI configuration missing for LangGraph agent")
        return
    
    # Initialize Azure OpenAI client
    credential = DefaultAzureCredential()
    azure_ad_token_provider = get_bearer_token_provider(
        credential, "https://cognitiveservices.azure.com/.default"
    )
    
    self.llm = AzureChatOpenAI(
        azure_endpoint=endpoint,
        azure_deployment=deployment_name,
        azure_ad_token_provider=azure_ad_token_provider,
        api_version="2024-10-21"
    )
    
    # Define tools
    tools = [
        self._create_task_tool(),
        self._get_tasks_tool(),
        self._get_task_tool(),
        self._update_task_tool(),
        self._delete_task_tool()
    ]
    
    # Create the agent
    self.agent = create_react_agent(self.llm, tools, checkpointer=self.memory)

When processing user messages, the agent invokes ainvoke() with the server-managed thread ID:

config = {"configurable": {"thread_id": self.thread_id}}

# Process the message
result = await self.agent.ainvoke(
    {"messages": [("user", message)]},
    config=config
)

The browser request contains only the message. It can't select another thread by supplying a session or conversation identifier.

Foundry Agent Service

The FoundryTaskAgent is initialized in the constructor of src/agents/foundry_task_agent.py. The initialization code does the following:

• Creates an AIProjectClient using Azure credentials.
• Gets an OpenAI client from the project client.
• Retrieves the agent from Foundry by name.
• Creates one authenticated conversation managed on the server.

# Create the project client using Azure credentials
self.project_client = AIProjectClient(
    endpoint=endpoint,
    credential=DefaultAzureCredential()
)

# Get the OpenAI client for conversation operations
self.openai_client = self.project_client.get_openai_client()

# Find the existing agent by name
self.agent = self.project_client.agents.get(agent_name)

if not self.agent:
    print(f"Agent with name '{agent_name}' not found in project.")
    return
            
# App Service authentication protects this sample, which intentionally
# keeps one server-managed conversation per worker process.
conversation = self.openai_client.conversations.create()
self.conversation_id = conversation.id

The Foundry conversation ID stays on the server and isn't returned to or accepted from the browser. Both agent implementations keep conversation state in process memory, so the deployed learning sample runs one Gunicorn worker. If you increase the worker count or scale out the app, use an external conversation store to share state across workers and instances.

This initialization code doesn't define any functionality for the agent, because you would typically build the agent in the 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 Foundry Agent Service (Python), and makes its CRUD functionality available as an OpenAPI endpoint. This lets you add it to the agent later as a callable tool.

The OpenAPI code is defined in src/routes/api.py. For example, the "GET /tasks" route defines a custom operation_id parameter, as required by the OpenAPI spec tool in Microsoft Foundry, and description helps the agent determine how to call the API:

@router.get(
    "/tasks",
    response_model=List[TaskItem],
    operation_id="getAllTasks",
    description="Retrieve all tasks in the task list."
)
async def get_all_tasks():
    """Get all tasks"""
    try:
        tasks = await task_service.get_all_tasks()
        return tasks
    except Exception as e:
        print(f"Error getting tasks: {e}")
        import traceback
        traceback.print_exc()
        raise HTTPException(status_code=500, detail=f"Failed to get tasks: {str(e)}")

When processing user messages, the agent is invoked by adding the user's message to the conversation and calling responses.create() with the agent reference:

# Add user message to the conversation
await asyncio.to_thread(
    self.openai_client.conversations.items.create,
    conversation_id=self.conversation_id,
    items=[{"type": "message", "role": "user", "content": message}],
)

# Create response using the agent
response = await asyncio.to_thread(
    self.openai_client.responses.create,
    conversation=self.conversation_id,
    extra_body={"agent": {"name": self.agent.name, "type": "agent_reference"}},
    input="",
)

Deploy the sample application

The sample repository contains an Azure Developer CLI (AZD) template, which creates an App Service app and deploys your sample application. The App Service system-assigned managed identity is retained for outbound Azure AI calls. A separate user-assigned managed identity and federated identity credential let App Service authentication act as the generated Microsoft Entra application without a client secret.

1. In the terminal, sign in to Azure by using Azure Developer CLI:

   azd auth login
   

   Follow the instructions to complete the authentication process.

2. Deploy the Azure App Service app by using the AZD template:

   azd up
   

3. When prompted, give the following answers:

   Question	Answer
   Enter a new environment name:	Type a unique name.
   Select an Azure Subscription to use:	Select the subscription.
   Pick a resource group to use:	Select Create a new resource group.
   Select a location to create the resource group in:	Select Sweden Central.
   Enter a name for the new resource group:	Type Enter.

4. In the AZD output, find the URL of your app and navigate to it in the browser. Also copy the Foundry OpenAPI managed identity audience value for later. The output looks like this:

    Deploying services (azd deploy)
   
      (✓) Done: Deploying service web
      - Endpoint: <URL>
   
    Foundry OpenAPI managed identity audience:
        api://<generated-client-id>
    

5. When Microsoft prompts you, sign in by using an account in the deployment tenant, and verify that the task list loads.

6. In the same authenticated browser, append /openapi.json to the App Service endpoint. Copy or save the generated OpenAPI schema for later.

   Note

   App Service authentication returns an HTTP 302 redirect for unauthenticated browser requests. This sample contains both a browser UI and APIs, so the redirect provides a usable sign-in experience. API-only apps commonly use HTTP 401 instead.

Create and configure the Microsoft Foundry resource

LangGraph

1. In the Foundry portal, create a project.

2. Deploy a model of your choice (see Microsoft Foundry Quickstart: Create resources).

3. From top of the model playground, copy the model name.

4. On the home page, copy the Azure OpenAI endpoint for later.

Foundry Agent Service

1. In the Foundry portal, create a project.

2. On the home page, copy the Project endpoint for later use.

3. Select Start building and follow the prompt.

4. Select Tools > Add > Add tools > Custom > OpenAPI tool > Create. In the Setup pane, add an action with the OpenAPI spec tool.

5. Paste the OpenAPI schema that you copied from the authenticated App Service app.

6. For Authentication method, select Managed identity.

7. For Audience, paste the Foundry OpenAPI managed identity audience value from the AZD output. It resembles:

   api://<generated-client-id>
   

8. Save the tool and agent.

Allow the parent Foundry resource to call the task API

1. In the Foundry portal, select Manage in the top menu.

2. In Project details, select the Parent resource for your project, and then select Open in Azure portal.

3. Copy the system-assigned identity's Object (principal) ID. Find that identity in Microsoft Entra ID, and copy its Application ID. For detailed steps, see Find the parent Foundry resource identity.

4. In the Codespace terminal, store the application ID in the AZD environment and update the App Service authentication configuration:

   azd env set AZURE_AI_FOUNDRY_ACCOUNT_CLIENT_ID <application-id>
   azd provision
   

Assign required permissions

LangGraph

1. In the Foundry portal, select Manage in the top menu.

2. In Project details, select the Parent resource for your project, and then select Open in Azure portal.

   From the Azure portal, you can assign role-based access for the resource.

3. Add the following role for both the App Service app's managed identity and the user you use with az login:

   Target resource	Required role	Needed for
   Foundry	Cognitive Services OpenAI User	The chat completion service in Microsoft Agent Framework.

   For instructions, see Assign Azure roles using the Azure portal.

Foundry Agent Service

1. In the Foundry portal, select Manage in the top menu.

2. In Project details, select Open in Azure portal.

   From the Azure portal, you can assign role-based access for the project.

3. Add the following role for both the App Service app's managed identity and the user you use with az login:

   Target resource	Required role	Needed for
   Foundry Project	Foundry User	Reading and calling the Foundry agent.

   For instructions, see Assign Azure roles using the Azure portal.

Important

This role assignment controls the outbound call from App Service to the Foundry project. The hosted OpenAPI call uses the parent Foundry resource system-assigned managed identity that you added to the App Service authentication allow list.

Configure connection variables in your sample application

1. Open .env. Using the values you copied earlier from the Foundry portal, configure the following variables:

   LangGraph

   Variable	Description
   AZURE_OPENAI_ENDPOINT	Azure OpenAI endpoint (copied from the Foundry portal home page).
   AZURE_OPENAI_DEPLOYMENT_NAME	Model name in the deployment (copied from the model playground in the new Foundry portal).

   Note

   To keep the tutorial simple, you'll use these variables in .env instead of overwriting them with app settings in App Service.

   Foundry Agent Service

   Variable	Description
   AZURE_AI_FOUNDRY_PROJECT_ENDPOINT	Microsoft Foundry project endpoint from the new Foundry portal.
   AZURE_AI_FOUNDRY_AGENT_NAME	Agent name (from the agent playground in the Foundry portal).

   Note

   To keep the tutorial simple, you'll use these variables in .env instead of overwriting them with app settings in App Service.

   The values in .env configure the app's outbound connection to Foundry. AZURE_AI_FOUNDRY_ACCOUNT_CLIENT_ID configures the separate inbound Foundry-to-App-Service OpenAPI connection and is stored in the AZD environment.

2. Sign in to Azure with the Azure CLI:

   az login
   

   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.

3. Run the application locally:

   source venv/bin/activate
   uvicorn src.app:app --host 0.0.0.0 --port 3000
   

4. When you see Your application running on port 3000 is available, select Open in Browser.

5. Validate both pivots separately:

   • LangGraph: Select LangGraph Agent, and ask the agent to create a task. LangGraph calls the in-process task tool.
   • Foundry Agent Service: Select Foundry Agent, and ask the agent to create a task. The remote Foundry agent calls the deployed, protected /api/tasks endpoint with managed identity.

   The task that the Foundry agent creates appears in the deployed App Service instance, not the local SQLite database. The Foundry OpenAPI tool always uses the server URL embedded in the OpenAPI schema.

6. Back in the GitHub codespace, deploy your app changes.

   azd up
   

7. Navigate to the deployed application again and test both chat agents. The browser sends only message text; it doesn't send a session ID or conversation ID for either agent.

LangGraph

Foundry Agent Service

Frequently asked questions

• How do I add retrieval augmented generation (RAG) to the Foundry agent?

How do I add retrieval augmented generation (RAG) to the Foundry agent?

This guidance applies to the Foundry Agent Service path in this tutorial. It doesn't change the LangGraph, Semantic Kernel, or Microsoft Agent Framework implementations shown in the other tab.

Create or select a Foundry IQ knowledge base, and then connect the knowledge base to the Foundry Agent Service agent. The connection is exposed to the agent as a managed MCP knowledge tool.

The App Service code continues to invoke the same agent by name through its existing Foundry client and agent_reference. The web app doesn't need a direct Azure AI Search integration or its own MCP client. If the UI displays sources, process the citation annotations returned by the agent.

Clean up resources

When you're done with the application, you can delete the App Service resources to avoid incurring further costs:

azd down --purge

The AZD postdown hook also deletes the tenant-level Microsoft Entra application created for App Service authentication.

Then, delete the Foundry resource if you created it separately.

More resources

• Integrate AI into your Azure App Service applications
• What is Foundry Agent Service?
• LangGraph - Quickstart
• Azure AI Projects client library for Python