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.

LangGraph

Servizio Agente Fonderia

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:

Considerazione	LangGraph o Microsoft Agent Framework	Servizio Agente Fonderia
Performance	Veloce (eseguito localmente)	Più lento (gestito, servizio remoto)
Sviluppo	Codice completo, massimo controllo	Poco codice, integrazione rapida
Testing	Test manuali/unit test nel codice	Playground predefinito per i test rapidi
Scalabilità	Gestito dall'app	Gestito da Azure, con scalabilità automatica
Protezioni di sicurezza	Implementazione personalizzata richiesta	Sicurezza e moderazione dei contenuti predefiniti
Identità	Implementazione personalizzata richiesta	ID e autenticazione predefiniti dell'agente
Enterprise	Integrazione personalizzata richiesta	Distribuzione predefinita di Microsoft 365/Teams e chiamate agli strumenti integrati di Microsoft 365.

In questa esercitazione si apprenderà come:

• Convertire le funzionalità dell'app esistenti in un plug-in per LangGraph.
• Aggiungere il plug-in a un agente LangGraph e usarlo in un'app Web.
• Convertire le funzionalità dell'app esistenti in un endpoint OpenAPI per il servizio agente Foundry.
• Chiamare un agente Foundry in un'applicazione web.
• Assegnare le autorizzazioni necessarie per la connettività dell'identità gestita.

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.

LangGraph

LangGraphTaskAgent viene inizializzato nel costruttore in src/agents/langgraph_task_agent.py. Il codice di inizializzazione effettua le operazioni seguenti:

• Configura il client AzureChatOpenAI usando variabili di ambiente.
• Crea l'agente ReAct predefinito con memoria e un set di strumenti CRUD per la gestione delle attività (vedere Guida introduttiva a LangGraph).

# 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)
print("LangGraph Task Agent initialized successfully")

Durante l'elaborazione dei messaggi utente, l'agente viene richiamato usando ainvoke() con il messaggio dell'utente e un ID thread per la continuità della conversazione:

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

Servizio Agente Fonderia

FoundryTaskAgent viene inizializzato nel costruttore di src/agents/foundry_task_agent.py. Il codice di inizializzazione effettua le operazioni seguenti:

• Crea un oggetto AIProjectClient usando le credenziali di Azure.
• Ottiene un client OpenAI dal client del progetto.
• Trova l'agente da Foundry per nome.
• Crea una nuova conversazione per la sessione.

# 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
            
# Create a conversation for this session
conversation = self.openai_client.conversations.create()
self.conversation_id = conversation.id
print("Foundry agent initialized successfully")

Questo codice di inizializzazione non definisce alcuna funzionalità per l'agente, perché in genere si compila l'agente nel portale foundry. Come parte dello scenario di esempio, segue anche il modello OpenAPI illustrato in Aggiungere un'app del servizio app come strumento in Foundry Agent Service (Python) e rende disponibile la funzionalità CRUD come endpoint OpenAPI. Ciò consente di aggiungerlo all'agente in un secondo momento come strumento chiamabile.

Il codice OpenAPI è definito in src/routes/api.py. Ad esempio, la route "GET /tasks" definisce un parametro personalizzato operation_id , come richiesto dallo strumento della specifica OpenAPI in Microsoft Foundry e description aiuta l'agente a determinare come chiamare l'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)}")

Durante l'elaborazione dei messaggi utente, l'agente viene richiamato aggiungendo il messaggio dell'utente alla conversazione e chiamando responses.create() con il riferimento all'agente:

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

# Create response using the agent
response = 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 modello di Azure Developer CLI (AZD) che crea un'app di Servizio app con identità gestita e distribuisce l'applicazione di esempio.

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

   azd auth login
   

   Seguire le istruzioni per completare il processo di autenticazione.

2. Distribuire l'app di Servizio app di Azure con 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. L'URL è simile al seguente nell'output AZD:

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

5. Aprire lo schema OpenAPI generato automaticamente nel https://....azurewebsites.net/openapi.json percorso. Questo schema sarà necessario in un secondo momento.

   Ora è disponibile un'app di Servizio app con un'identità gestita assegnata dal sistema.

Creare e configurare la risorsa Microsoft Foundry

LangGraph

1. Nel portale di Foundry verificare che il pulsante di opzione New Foundry in alto sia impostato su attivo e creare un progetto.

2. Distribuire un modello preferito (vedere Avvio rapido di Microsoft Foundry: Creare risorse).

3. Nella parte superiore del playground del modello copiare il nome del modello.

4. Il modo più semplice per ottenere l'endpoint OpenAI di Azure è ancora dal portale classico. Selezionare il pulsante di opzione New Foundry, quindi Azure OpenAI, e quindi copiare l'URL nell'Azure OpenAI endpoint per un secondo momento.

   

Servizio Agente Fonderia

1. Nel portale di Foundry verificare che il pulsante di opzione New Foundry in alto sia impostato su attivo e creare un progetto.

2. Nella home page, copiare l'endpoint di Project per uso futuro.

3. Selezionare Avvia creazione>Crea agente e seguire la richiesta.

4. Nel playground del nuovo agente, crea uno strumento OpenAPI personalizzato per chiamare l'app web selezionando Strumenti>Aggiungi>strumento>personalizzato>Crea. Nel riquadro Installazione, aggiungere un'azione con lo strumento specifica OpenAPI. Usare lo schema OpenAPI ottenuto dall'app Web distribuita e dall'autenticazione anonima. Per i passaggi dettagliati, vedere Come usare lo strumento specifica OpenAPI.

   Il codice dell'applicazione è già configurato per includere gli url e operationId del server, che sono necessari per l'agente. Per altre informazioni, vedere Connettersi alla specifica OpenAPI.

5. Assicurarsi di selezionare Salva.

6. Selezionare Prova in playground e testare l'agente Foundry con richieste come "Mostra tutte le attività" e "Aggiungi un'attività".

   Se si ottiene una risposta valida, l'agente effettua chiamate di strumenti all'endpoint OpenAPI nell'app Web distribuita.

Assegnare le autorizzazioni necessarie

LangGraph

1. Nel menu in alto del nuovo portale Foundry, selezionare Opera, quindi Amministrazione. Nella riga del progetto Foundry, dovrebbero essere visualizzati due collegamenti. Quello nella colonna Nome è la risorsa del progetto Foundry e quella nella colonna Risorsa padre è la risorsa Foundry.

   

2. Selezionare la risorsa Foundry nella risorsa padre e quindi selezionare Gestisci questa risorsa nel portale di Azure. Dal portale di Azure è possibile assegnare l'accesso in base al ruolo per la risorsa all'app Web distribuita.

3. Aggiungi il ruolo seguente per l'identità gestita dell'app di App Service:

   Risorsa di destinazione	Ruolo obbligatorio	Necessario per
   Fonderia	Utente di Servizi Cognitivi OpenAI	Servizio di completamento della chat in Microsoft Agent Framework.

   Per istruzioni, vedere Assegnare ruoli di Azure usando il portale di Azure.

Servizio Agente Fonderia

1. Nel menu in alto del nuovo portale Foundry, selezionare Opera, quindi Amministrazione. Nella riga del progetto Foundry, dovrebbero essere visualizzati due collegamenti. Quello nella colonna Nome è la risorsa del progetto Foundry e quella nella colonna Risorsa padre è la risorsa Foundry.

   

2. Selezionare la risorsa del progetto Foundry nella colonna Nome e quindi selezionare Gestisci questa risorsa nel portale di Azure. Dal portale di Azure è possibile assegnare l'accesso in base al ruolo per la risorsa all'app Web distribuita.

3. Aggiungi il ruolo seguente per l'identità gestita dell'app di App Service:

   Risorsa di destinazione	Ruolo obbligatorio	Necessario per
   Progetto Foundry	Utente di Intelligenza artificiale di Azure	Lettura e chiamata dell'agente Foundry.

   Per istruzioni, vedere Assegnare ruoli di Azure usando il portale di Azure.

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

   Variable	Description
   AZURE_OPENAI_ENDPOINT	Endpoint OpenAI di Azure (copiato dal portale di Foundry classico).
   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.

   Servizio Agente Fonderia

   Variable	Description
   AZURE_AI_FOUNDRY_PROJECT_ENDPOINT	Endpoint del progetto Microsoft Foundry dal nuovo portale Foundry.
   AZURE_AI_FOUNDRY_AGENT_NAME	Nome agente (dal playground dell'agente nel portale Foundry).

   Annotazioni

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

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:

   npm run build
   npm start
   

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

5. Selezionare il collegamento Agente LangGraph e il collegamento Agente Fonderia per provare l'interfaccia di chat. Se si riceve una risposta, l'applicazione si connette correttamente alla risorsa Microsoft Foundry.

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

   azd up
   

7. Passare di nuovo all'applicazione distribuita e testare gli agenti di chat.

LangGraph

Servizio Agente Fonderia

Pulire le risorse

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

azd down --purge

Poiché il modello AZD non include le risorse di Microsoft Foundry, è necessario eliminarle manualmente, se necessario.

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