Esercitazione: Creare un'app Web agentic nel servizio app di Azure con LangGraph o Foundry Agent Service (Python)

Questa esercitazione illustra come aggiungere funzionalità agentiche a un'applicazione CRUD FastAPI basata sui dati esistente. A tale scopo, si usano due approcci diversi: LangGraph e Foundry Agent Service.

Se l'applicazione Web ha già funzionalità utili, ad esempio acquisti, prenotazioni di hotel o gestione dei dati, è relativamente semplice aggiungere funzionalità dell'agente all'applicazione Web eseguendo il wrapping di tali funzionalità in un plug-in (per LangGraph) o come endpoint OpenAPI (per il servizio agente Foundry). In questa esercitazione, si inizia con una semplice app di elenco attività. Al termine, si sarà in grado di creare, aggiornare e gestire attività con un agente in un'app di Servizio app.

Sia LangGraph che il servizio agente Foundry consentono di creare applicazioni Web agentic con funzionalità basate su intelligenza artificiale. LangGraph è simile a Microsoft Agent Framework ed è un SDK. La tabella seguente illustra alcune considerazioni e compromessi:

In questa esercitazione si apprenderà come:

Prerequisiti

• Un account Azure con un abbonamento attivo - Creare gratuitamente un account.
• Account GitHub per l'uso di GitHub Codespaces - Altre informazioni su GitHub Codespaces.

Aprire l'esempio con Codespaces

Il modo più semplice per iniziare consiste nell'usare GitHub Codespaces, che offre un ambiente di sviluppo completo con tutti gli strumenti necessari preinstallati.

1. Passare al repository GitHub su https://github.com/Azure-Samples/app-service-agentic-langgraph-foundry-python.

2. Selezionare il pulsante Codice, selezionare la scheda Codespaces, quindi selezionare Crea codespace in main.

3. Attendere per alcuni istanti l'inizializzazione di Codespace. Quando si è pronti, nel browser si vedrà un ambiente di sviluppo completamente configurato.

4. Eseguire l'applicazione in locale:

   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. Quando viene visualizzato L'applicazione in esecuzione sulla porta 3000 è disponibile, selezionare Apri nel browser e aggiungere alcune attività.

   Gli agenti non sono completamente configurati, per cui non funzionano ancora. Verranno configurati in un secondo momento.

Esaminare il codice dell'agente

Entrambi gli approcci usano lo stesso modello di implementazione, in cui l'agente viene inizializzato all'avvio dell'applicazione e risponde ai messaggi dell'utente tramite richieste POST.

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)

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

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

# 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

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

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

Distribuire l'applicazione di esempio

Il repository di esempio contiene un template Azure Developer CLI (AZD), che crea un'app di App Service e distribuisce la tua applicazione di esempio. L'identità gestita assegnata al sistema App Service viene mantenuta per le chiamate AI Azure in uscita. Un'identità gestita separata assegnata dall'utente e una credenziale di identità federata permettevano all'autenticazione App Service di agire come l'applicazione Microsoft Entra generata senza un segreto client.

1. Nel terminale, accedi ad Azure usando Azure Developer CLI:

   azd auth login
   

   Seguire le istruzioni per completare il processo di autenticazione.

2. Distribuisci l'app Servizio app di Azure utilizzando il modello AZD:

   azd up
   

3. Quando richiesto, fornire le risposte seguenti:

   Domanda	Risposta
   Immettere un nuovo nome ambiente:	Digitare un nome univoco.
   Selezionare un abbonamento di Azure da usare:	Selezionare la sottoscrizione.
   Selezionare un gruppo di risorse da usare:	Selezionare Crea un nuovo gruppo di risorse.
   Selezionare un percorso in cui creare il gruppo di risorse:	Selezionare Svezia centrale.
   Immettere un nome per il nuovo gruppo di risorse:	Immettere INVIO.

4. Nell'output AZD, trova l'URL dell'app e accedi ad esso tramite il browser. Copia anche il valore dell'audience di identità gestita da Foundry OpenAPI per più avanti. L'output è simile al seguente:

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

5. Quando Microsoft ti chiede, accedi usando un account nel tenant di distribuzione e verifica che la lista delle attività si carichi.

6. Nello stesso browser già autenticato, aggiungi /openapi.json all'endpoint di App Service. Copia o salva lo schema OpenAPI generato per dopo.

   Annotazioni

   L'autenticazione tramite App Service restituisce un reindirizzamento HTTP 302 per le richieste del browser non autenticate. Questo esempio contiene sia un'interfaccia utente del browser che API, quindi il redirect offre un'esperienza di accesso utilizzabile. Le app basate esclusivamente su API usano comunemente invece HTTP 401.

Creare e configurare la risorsa Microsoft Foundry

Assegnare le autorizzazioni necessarie

Configurare le variabili di connessione nell'applicazione di esempio

1. Aprire il file con estensione env. Usando i valori copiati in precedenza dal portale foundry, configurare le variabili seguenti:

   • LangGraph
   • Servizio Agente Fonderia

   Variable	Description
   AZURE_OPENAI_ENDPOINT	Azure OpenAI endpoint (copiato dalla homepage del portale Foundry).
   AZURE_OPENAI_DEPLOYMENT_NAME	Nome del modello nella distribuzione (copiato dall'area di sperimentazione del modello nel nuovo portale Foundry).

   Annotazioni

   Per semplificare l'esercitazione, queste variabili verranno usate in .env invece di sovrascriverle con le impostazioni dell'app nel servizio app.

   Annotazioni

   Per semplificare l'esercitazione, queste variabili verranno usate in .env invece di sovrascriverle con le impostazioni dell'app nel servizio app.

   I valori in .env configurano la connessione in uscita dell'app a Foundry. AZURE_AI_FOUNDRY_ACCOUNT_CLIENT_ID configura la connessione OpenAPI separata in ingresso da Foundry ad App Service e viene memorizzata nell'ambiente AZD.

2. Accedere ad Azure con l'interfaccia della riga di comando di Azure:

   az login
   

   Ciò consente alla libreria client di Identità di Azure nel codice di esempio di ricevere un token di autenticazione per l'utente connesso. Tenere presente che è stato aggiunto il ruolo necessario per questo utente in precedenza.

3. Eseguire l'applicazione in locale:

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

4. Quando viene visualizzato L'applicazione in esecuzione sulla porta 3000 è disponibile, selezionare Apri nel browser.

5. Valida entrambi i pivot separatamente:

   • LangGraph: Seleziona LangGraph Agent e chiedi all'agente di creare un compito. LangGraph chiama lo strumento di task in processo.
   • Servizio Foundry Agent: Seleziona Foundry Agent, e chiedi all'agente di creare un'attività. L'agente remoto di Foundry invoca l'endpoint /api/tasks distribuito e protetto usando l'identità gestita.

   Il compito creato dall'agente Foundry appare nell'istanza dell'App Service distribuito, non nel database SQLite locale. Lo strumento Foundry OpenAPI utilizza sempre l'URL del server incorporato nello schema OpenAPI.

6. Tornare nel codespace di GitHub, distribuire le modifiche dell'app.

   azd up
   

7. Naviga di nuovo sull'applicazione distribuita e testa entrambi gli agenti di chat. Il browser invia solo messaggi di testo; non invia un ID sessione o un ID conversazione per nessuno dei due agenti.

Domande frequenti

• Come posso aggiungere Retrieval Augmented Generation (RAG) all'agente Foundry?

Come posso aggiungere la generazione aumentata di recupero (RAG) all'agente Foundry?

Queste indicazioni si applicano al percorso Foundry Agent Service in questo tutorial. Non cambia le implementazioni di LangGraph, Kernel semantico o Microsoft Agent Framework mostrate nell'altra scheda.

Crea o seleziona una knowledge base di Foundry IQ, e poi collega la knowledge base all'agente di Foundry Agent Service. La connessione viene esposta all'agente come uno strumento di conoscenza MCP gestito.

Il codice di App Service continua a richiamare lo stesso agente per nome tramite il client Foundry esistente e agent_reference. L'app web non ha bisogno di un'integrazione diretta con Azure AI Search né di un proprio client MCP. Se l'interfaccia mostra le fonti, elabora le annotazioni di citazione restituite dall'agente.

Pulire le risorse

Al termine dell'applicazione, è possibile eliminare le risorse del servizio app per evitare di sostenere ulteriori costi:

azd down --purge

L'hook AZD postdown elimina anche l'applicazione Microsoft Entra a livello di tenant creata per l'autenticazione degli App Service.

Poi, elimina la risorsa Foundry se l'hai creata separatamente.

Altre risorse

• Integrare l'intelligenza artificiale nelle applicazioni di Servizio app di Azure
• Che cos'è il Servizio Agente Fonderia?
• LangGraph - Avvio rapido
• Libreria client di Progetti di intelligenza artificiale di Azure per Python