Zelfstudie: Een agentische web-app bouwen in Azure App Service met LangGraph of Foundry Agent Service (Python)

In deze zelfstudie ziet u hoe u agentische mogelijkheden toevoegt aan een bestaande FastAPI CRUD-toepassing op basis van gegevens. Dit doet u met behulp van twee verschillende benaderingen: LangGraph en Foundry Agent Service.

Als uw webtoepassing al nuttige functies heeft, zoals winkelen, hotelreservering of gegevensbeheer, is het relatief eenvoudig om agentfunctionaliteit toe te voegen aan uw webtoepassing door deze functies in een invoegtoepassing (voor LangGraph) of als een OpenAPI-eindpunt (voor Foundry Agent Service) te verpakken. In deze zelfstudie begint u met een eenvoudige to-do lijst-app. Aan het einde kunt u taken maken, bijwerken en beheren met een agent in een App Service-app.

LangGraph
Gieterijagentendienst

Schermopname van een chatsessie met een LangGraph-agent.

Met zowel LangGraph als Foundry Agent Service kunt u agentische webtoepassingen bouwen met AI-gestuurde mogelijkheden. LangGraph is vergelijkbaar met Microsoft Agent Framework en is een SDK. De volgende tabel toont enkele overwegingen en afwegingen:

Overweging	LangGraph of Microsoft Agent Framework	Foundry Agentendienst
Performance	Snel (lokaal uitgevoerd)	Trager (beheerde, externe service)
Ontwikkeling	Volledige code, maximaal beheer	Low-code, snelle integratie
Testing	Handmatige/eenheidstests in code	Ingebouwde speeltuin voor snel testen
Schaalbaarheid	Beheerd door app	Door Azure beheerd, automatisch geschaald
Veiligheidsrails	Aangepaste implementatie vereist	Ingebouwde inhoudsveiligheid en toezicht
Identiteit	Aangepaste implementatie vereist	Ingebouwde agent-id en verificatie
Enterprise	Aangepaste integratie vereist	Ingebouwde microsoft 365/Teams-implementatie en geïntegreerde hulpprogramma-aanroepen van Microsoft 365.

In deze handleiding leer je hoe je:

Bestaande app-functionaliteit converteren naar een invoegtoepassing voor LangGraph.
Voeg de invoegtoepassing toe aan een LangGraph-agent en gebruik deze in een web-app.
Bestaande app-functionaliteit converteren naar een OpenAPI-eindpunt voor Foundry Agent Service.
Roep een Foundry-agent aan in een web-app.
Wijs de vereiste machtigingen toe voor connectiviteit met beheerde identiteiten.

Vereiste voorwaarden

Een Azure-account met een actief abonnement: maak gratis een account.
GitHub-account voor het gebruik van GitHub Codespaces - Meer informatie over GitHub Codespaces.

Het voorbeeld openen met Codespaces

De eenvoudigste manier om aan de slag te gaan is door GitHub Codespaces te gebruiken. Dit biedt een volledige ontwikkelomgeving met alle vereiste hulpprogramma's die vooraf zijn geïnstalleerd.

Navigeer naar de GitHub-opslagplaats op https://github.com/Azure-Samples/app-service-agentic-langgraph-foundry-python.
Selecteer de knop Code, selecteer het tabblad Codespaces en selecteer Codespace maken op main.
Wacht even totdat uw Codespace is geïnitialiseerd. Wanneer u klaar bent, ziet u een volledig geconfigureerde ontwikkelomgeving in uw browser.

Voer de toepassing lokaal uit:

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

Wanneer u ziet dat uw toepassing wordt uitgevoerd op poort 3000 beschikbaar is, selecteert u Openen in browser en voegt u enkele taken toe.

De agents zijn niet volledig geconfigureerd, zodat ze nog niet werken. U gaat ze later configureren.

De agentcode controleren

Beide benaderingen gebruiken hetzelfde implementatiepatroon, waarbij de agent wordt geïnitialiseerd bij het starten van de toepassing en reageert op gebruikersberichten door POST-aanvragen.

LangGraph
Gieterijagentendienst

De LangGraphTaskAgent wordt geïnitialiseerd in de constructor in src/agents/langgraph_task_agent.py. De initialisatiecode doet het volgende:

Hiermee configureert u de AzureChatOpenAI-client met behulp van omgevingsvariabelen.
Hiermee maakt u de voorgebouwde ReAct-agent met geheugen en een set CRUD-hulpprogramma's voor taakbeheer (zie LangGraph-snelstartgids).
Selecteert één serverbeheerde conversatiethread voor het geauthenticeerde voorbeeld.

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)

Bij het verwerken van gebruikersberichten roept ainvoke() de agent aan met de serverbeheerde thread-ID:

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

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

Het browserverzoek bevat alleen het bericht. Het kan geen andere thread selecteren door een sessie- of conversatie-identificatie te geven.

De FoundryTaskAgent wordt geïnitialiseerd in de constructor van src/agents/foundry_task_agent.py. De initialisatiecode doet het volgende:

Hiermee maakt u een AIProjectClient met behulp van Azure-referenties.
Hiermee haal je een OpenAI-client op van de projectclient.
Haalt de agent op naam op uit Foundry.
Maakt één geauthenticeerd gesprek aan dat op de server wordt beheerd.

# 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

De Foundry conversation ID blijft op de server staan en wordt niet teruggestuurd naar of geaccepteerd door de browser. Beide agentimplementaties houden de conversatietoestand in het procesgeheugen, zodat het gedeployeerde leervoorbeeld één Gunicorn-worker draait. Als je het aantal werknemers verhoogt of de app uitbreidt, gebruik dan een externe conversation store om de status tussen werknemers en instanties te delen.

Deze initialisatiecode definieert geen functionaliteit voor de agent, omdat u doorgaans de agent zou bouwen in de Foundry-portal. Als onderdeel van het voorbeeldscenario volgt dit ook het OpenAPI-patroon dat wordt weergegeven in Een App Service-app toevoegen als een hulpprogramma in Foundry Agent Service (Python) en maakt de CRUD-functionaliteit beschikbaar als een OpenAPI-eindpunt. Hiermee kunt u deze later als aanroepbaar hulpprogramma toevoegen aan de agent.

De OpenAPI-code wordt gedefinieerd in src/routes/api.py. De route GET /tasks definieert bijvoorbeeld een aangepaste operation_id parameter, zoals vereist door het hulpprogramma OpenAPI-specificatie in Microsoft Foundry, en description helpt de agent te bepalen hoe de API moet worden aangeroepen:

@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)}")

Bij het verwerken van gebruikersberichten wordt de agent aangeroepen door het bericht van de gebruiker toe te voegen aan het gesprek en te bellen responses.create() met de agentreferentie:

# 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="",
)

De voorbeeldtoepassing implementeren

De voorbeeldrepository bevat een Azure Developer CLI (AZD) sjabloon, die een App Service-app maakt en je voorbeeldapplicatie uitrolt. De door het App Service toegewezen beheerde identiteit wordt behouden voor uitgaande Azure AI-aanroepen. Een aparte, door de gebruiker toegewezen beheerde identiteit en gefedereerd identiteitsbewijs laten App Service-authenticatie fungeren als de gegenereerde Microsoft Entra-applicatie zonder een clientgeheim.

Log in de terminal in bij Azure met behulp van Azure Developer CLI:
```
azd auth login
```
Volg de instructies om het verificatieproces te voltooien.
Deploy de Azure App Service app met behulp van de AZD-template:
```
azd up
```

Geef de volgende antwoorden wanneer u hierom wordt gevraagd:

Question	Antwoord
Voer een nieuwe omgevingsnaam in:	Typ een unieke naam.
Selecteer een Azure-abonnement dat u wilt gebruiken:	Selecteer het abonnement.
Kies een resourcegroep die u wilt gebruiken:	Selecteer Een nieuwe resourcegroep maken.
Selecteer een locatie waar u de resourcegroep wilt maken:	Selecteer Zweden - centraal.
Voer een naam in voor de nieuwe resourcegroep:	Typ Enter.

Zoek in de AZD-uitvoer de URL van uw app en navigeer ernaar in de browser. Kopieer ook de Foundry OpenAPI managed identity audience waarde voor later. De uitvoer ziet er als volgt uit:
```
 Deploying services (azd deploy)

   (✓) Done: Deploying service web
   - Endpoint: <URL>

 Foundry OpenAPI managed identity audience:
     api://<generated-client-id>
 
```
Wanneer Microsoft je ernaar vraagt, log dan in met een account in de deployment tenant en controleer of de takenlijst geladen is.
Voeg in dezelfde geauthenticeerde browser /openapi.json toe aan het App Service-eindpunt. Kopieer of sla het gegenereerde OpenAPI-schema op voor later.

Opmerking

App Service-authenticatie geeft een HTTP 302-redirect terug voor niet-geauthenticeerde browserverzoeken. Dit voorbeeld bevat zowel een browserinterface als API's, waardoor de redirect een bruikbare aanmeldervaring biedt. API-only apps gebruiken vaak HTTP 401.

De Microsoft Foundry-resource maken en configureren

LangGraph
Gieterijagentendienst

Maak in het Foundry-portaal een project.
Een model van uw keuze implementeren (zie Snelstartgids voor Microsoft Foundry: Resources maken).
Kopieer de naam van het model vanaf de bovenkant van de modelspeelplaats.
Kopieer op de startpagina het Azure OpenAI-eindpunt voor later.

Maak in het Foundry-portaal een project.
Kopieer op de startpagina het Project-eindpunt voor later gebruik.
Selecteer Start bouwen en volg de prompt.
Selecteer Tools>Toevoegen>Hulpmiddelen>Aangepaste>OpenAPI-tool>Aanmaken. Voeg in het deelvenster Setup een actie toe met het hulpprogramma OpenAPI-specificatie.
Plak het OpenAPI-schema dat je hebt gekopieerd uit de geauthenticeerde App Service-app.
Selecteer beheerde identiteit voor verificatiemethode.
Voor Audience plak je de Foundry OpenAPI managed identity audience waarde uit de AZD-uitvoer. Het lijkt op:
```
api://<generated-client-id>
```
Bewaar het gereedschap en de agent.

Laat de ouder Foundry-resource de taak-API aanroepen

Selecteer in het Foundry-portaal Beheren in het bovenste menu.
Selecteer in Project details de Ouderresource van je project en selecteer vervolgens Open in Azure portal.
Kopieer de Object-id (principal-id) van de door het systeem toegewezen beheerde identiteit. Zoek die identiteit in de Microsoft Entra ID en kopieer de applicatie-ID. Voor gedetailleerde stappen, zie Find the parent Foundry resource identity.
Sla in de Codespace-terminal de applicatie-ID op in de AZD-omgeving en werk de App Service-authenticatieconfiguratie bij:
```
azd env set AZURE_AI_FOUNDRY_ACCOUNT_CLIENT_ID <application-id>
azd provision
```

Selecteer in het Foundry-portaal Beheren in het bovenste menu.
Selecteer in Project details de Ouderresource van je project en selecteer vervolgens Open in Azure portal.

Vanuit het Azure-portaal kun je rolgebaseerde toegang voor de resource toewijzen.
Voeg de volgende rol toe voor zowel de beheerde identiteit van de App Service-app als de gebruiker waarmee je werkt az login:

Doelresource Vereiste rol Vereist voor

Gieterij Cognitive Services OpenAI-gebruiker De voltooiingsservice voor chats in Microsoft Agent Framework.

Zie Azure-rollen toewijzen met behulp van Azure Portal voor instructies.

Doelresource	Vereiste rol	Vereist voor
Gieterij	Cognitive Services OpenAI-gebruiker	De voltooiingsservice voor chats in Microsoft Agent Framework.

Selecteer in het Foundry-portaal Beheren in het bovenste menu.
Selecteer in Project detailsOpen in Azure portal.

Vanuit het Azure-portaal kun je rolgebaseerde toegang toewijzen voor het project.
Voeg de volgende rol toe voor zowel de beheerde identiteit van de App Service-app als de gebruiker waarmee je werkt az login:

Doelresource Vereiste rol Vereist voor

Foundryproject Foundry-gebruiker De Foundry-agent lezen en aanroepen.

Zie Azure-rollen toewijzen met behulp van Azure Portal voor instructies.

Doelresource	Vereiste rol	Vereist voor
Foundryproject	Foundry-gebruiker	De Foundry-agent lezen en aanroepen.

Important

Deze roltoewijzing beheert de uitgaande aanroep van App Service naar het Foundry-project. De gehoste OpenAPI-aanroep maakt gebruik van de door het systeem toegewezen beheerde identiteit van de bovenliggende Foundry-resource die je hebt toegevoegd aan de toestaanlijst voor App Service-authenticatie.

Verbindingsvariabelen configureren in uw voorbeeldtoepassing

Open .env. Configureer de volgende variabelen met behulp van de waarden die u eerder hebt gekopieerd uit de Foundry-portal:

LangGraph
Gieterijagentendienst

Variable	Description
`AZURE_OPENAI_ENDPOINT`	Azure OpenAI endpoint (gekopieerd van de Foundry portal homepage).
`AZURE_OPENAI_DEPLOYMENT_NAME`	Modelnaam in de implementatie (gekopieerd uit de modelspeeltuin in de nieuwe Foundry-portal).

Opmerking

Als u de zelfstudie eenvoudig wilt houden, gebruikt u deze variabelen in .env in plaats van ze te overschrijven met app-instellingen in App Service.

Variable	Description
`AZURE_AI_FOUNDRY_PROJECT_ENDPOINT`	Microsoft Foundry-projecteindpunt vanuit de nieuwe Foundry-portal.
`AZURE_AI_FOUNDRY_AGENT_NAME`	Agentnaam (van de agentspeelplaats in de Foundry-portal).

Opmerking

Als u de zelfstudie eenvoudig wilt houden, gebruikt u deze variabelen in .env in plaats van ze te overschrijven met app-instellingen in App Service.

De waarden in .env configureren de uitgaande verbinding van de app met Foundry. AZURE_AI_FOUNDRY_ACCOUNT_CLIENT_ID configureert de afzonderlijke inkomende Foundry-to-App-Service OpenAPI-verbinding en wordt opgeslagen in de AZD-omgeving.

Meld u aan bij Azure met de Azure CLI:
```
az login
```
Hierdoor kan de Azure Identity-clientbibliotheek in de voorbeeldcode een verificatietoken ontvangen voor de aangemelde gebruiker. Houd er rekening mee dat u de vereiste rol voor deze gebruiker eerder hebt toegevoegd.

Voer de toepassing lokaal uit:

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

Wanneer u Uw toepassing die wordt uitgevoerd op poort 3000 is beschikbaar ziet, selecteert u Openen in browser.
Controleer beide draaipunten afzonderlijk:
- LangGraph: Selecteer LangGraph Agent en vraag de agent om een taak aan te maken. LangGraph roept de in-process tasktool aan.
- Foundry Agent Service: Selecteer Foundry Agent en vraag de agent om een taak te maken. De externe Foundry-agent roept het uitgerolde, beschermde /api/tasks endpoint met beheerde identiteit aan.
De taak die de Foundry-agent aanmaakt, verschijnt in de gedeployeerde App Service-instantie, niet in de lokale SQLite-database. De Foundry OpenAPI-tool gebruikt altijd de server-URL die is ingebed in het OpenAPI-schema.
Voer terug in de GitHub-codespace de wijzigingen in je app door.
```
azd up
```
Navigeer opnieuw naar de geïnstalleerde applicatie en test beide chatagenten. De browser stuurt alleen berichttekst; het stuurt geen sessie-ID of gespreks-ID voor een van beide agenten.

LangGraph
Gieterijagentendienst

Schermopname van een chatsessie met een LangGraph-agent.

Veelgestelde vragen

Hoe voeg ik retrieval augmented generation (RAG) toe aan de Foundry-agent?

Hoe voeg ik retrieval augmented generation (RAG) toe aan de Foundry-agent?

Deze richtlijn geldt voor het Foundry Agent Service-pad in deze tutorial. Het verandert niet de implementaties van LangGraph, Semantic Kernel of Microsoft Agent Framework die in het andere tabblad worden getoond.

Maak of selecteer een kennisbank van Foundry IQ, en verbind deze vervolgens met de Foundry Agent Service-agent. De verbinding wordt aan de agent beschikbaar gesteld als een beheerd MCP-kennistool.

De App Service-code blijft dezelfde agent bij naam aanroepen via zijn bestaande Foundry-client en agent_reference. De webapp heeft geen directe integratie met Azure AI Zoeken of een eigen MCP-client nodig. Als de gebruikersinterface bronnen toont, verwerk dan de citatie-annotaties die door de agent zijn teruggegeven.

De hulpbronnen opschonen

Wanneer u klaar bent met de toepassing, kunt u de App Service-resources verwijderen om verdere kosten te voorkomen:

azd down --purge

De AZD-hook postdown verwijdert ook de tenant-level Microsoft Entra-applicatie die is gemaakt voor App Service-authenticatie.

Verwijder vervolgens de Foundry-bron als je die apart hebt aangemaakt.

Meer middelen

Feedback

Is deze pagina nuttig?

Last updated on 2026-08-27