Creare agenti AI conversazionali con Azure AI Foundry

Azure AI Foundry di Microsoft semplifica lo sviluppo dell'AI grazie a una piattaforma unificata per creare, distribuire e gestire applicazioni intelligenti. È il Suo hub per lo sviluppo dell'AI: riunisce in un unico ambiente modelli linguistici, gestione dei dati e strumenti di deployment. Astrae la complessità dello sviluppo dell'AI senza rinunciare alla flessibilità di cui gli sviluppatori hanno bisogno per realizzare soluzioni sofisticate.

Partiremo da una semplice interazione di chat per comprendere le funzionalità conversazionali di base di un large language model. Esploreremo poi Azure AI Foundry Agent Service, dove è possibile creare agenti specializzati per gestire attività specifiche, mantenere il contesto della conversazione e integrarsi con fonti dati esterne.

Mostrerò come creare rapidamente un agente di base che si affida unicamente ai propri dati di addestramento e, in seguito, una versione più evoluta che integra ulteriori fonti di conoscenza per fornire risposte più accurate. Per concludere, vedremo un esempio pratico di codice Python che illustra come integrare questi agenti direttamente nelle Sue applicazioni per ottenere soluzioni intelligenti e scalabili.

Ecosistema Azure AI Foundry

Componenti dell'AI Agent

In questo esempio eseguiremo una configurazione standard di Azure AI Foundry e di un Agent Service tramite il portale di Azure. Per iniziare bastano poche autorizzazioni, una volta effettuato l'accesso alla Sua sottoscrizione Azure.

• Disponga di una sottoscrizione Azure: può iniziare gratuitamente.
• Si assicuri di disporre dei ruoli Azure AI Account Owner e Azure AI Project Manager a livello di sottoscrizione.
• Se sta configurando una configurazione standard di Azure AI Foundry, verifichi di disporre delle autorizzazioni per assegnare ruoli alle risorse necessarie (Cosmos DB, Azure AI Search, Azure Blob Storage). Per maggiori informazioni sui ruoli RBAC specifici per Azure AI Foundry Agent Service, consulti Azure AI Foundry Agent Service RBAC roles. Il ruolo predefinito necessario è Role Based Access Administrator, che fornisce l'autorizzazione chiave Microsoft.Authorization/roleAssignments/write
• Se incontra errori relativi a registrazioni mancanti o provider non registrati, dovrà registrare il provider indicato nel messaggio di errore.

Distribuire il progetto e l'AI Agent di base

Utilizzi questo template di distribuzione personalizzato per effettuare il provisioning del progetto Azure AI Foundry e dell'agente necessari.

https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2Fazure-ai-foundry%2Ffoundry-samples%2Frefs%2Fheads%2Fmain%2Fsamples%2Fmicrosoft%2Finfrastructure-setup%2F40-basic-agent-setup%2Fbasic-setup.json

Il link si apre nel portale di Azure e crea un progetto Azure AI Foundry in cui può lavorare in un ambiente indipendente per esplorare rapidamente le Sue idee di AI, costruire prototipi e molto altro.

Selezioni la sottoscrizione e il resource group, compili gli altri campi (inclusa la location) e lasci invariati tutti i campi relativi al modello. In questo modo si forniscono i dettagli per creare il progetto e distribuire un modello GPT-4o.

Faccia clic sul pulsante 'Review + create' per distribuire il template. L'operazione richiederà qualche minuto.

Form del template di distribuzione per creare le risorse Azure AI Foundry

Al termine della distribuzione, faccia clic su 'go to resource group' per visualizzare le risorse.

Resource Group con il progetto distribuito

Cliccando sul link del progetto, può accedere al portale Azure AI Foundry.

Link per accedere al progetto

Chattare con il modello

Una volta entrato nel portale Azure AI Foundry, se non viene reindirizzato direttamente al Playground del Suo progetto, selezioni il nome del progetto dalla pagina principale e poi Playgrounds. Verrà selezionato automaticamente il deployment gpt-4o, da cui potrà iniziare a chattare con il modello. Provi qualche prompt e osservi i risultati. Può anche sperimentare istruzioni diverse per il modello, restringere le risposte a un determinato argomento oppure aggiungere una fonte dati per integrare il modello con i Suoi dati.

Ad esempio, ho istruito il modello a fornire risposte solo sui terremoti e poi ho chiesto una ricetta.

Chat playground con istruzioni di esempio per il modello

Distribuire il chatbot come web app

Una funzionalità interessante è la possibilità di distribuire un semplice chatbot come web app. La distribuzione richiederà qualche minuto, dopodiché potrà cliccare sul link per aprire la web app e provarla. Tenga presente che per renderla davvero pronta alla produzione manca ancora molto, ma l'esempio dimostra quanto sia semplice creare una web app di chat di base.

Accanto al pulsante 'View code', in alto nell'interfaccia del Chat playground, selezioni 'Deploy as web app'.

Distribuzione del chatbot come web app

Per avviare la web app dopo la distribuzione, vada in 'My assets/Web apps' e clicchi sul link della web app distribuita.

Avvio della web app

Come avrà notato nel Chat playground, quando ho fornito le istruzioni al modello ne ho limitato le risposte alle sole domande sui terremoti. Come si vede nell'interfaccia di chat della web app, il modello non è riuscito a raccontarmi una barzelletta, ma ha risposto a una domanda sui terremoti. Tuttavia, il modello è stato addestrato solo su dati fino a ottobre 2023; nella prossima sezione Le mostrerò quindi come integrarlo con una fonte dati personalizzata senza doverlo riaddestrare.

Esempio di web app chatbot

Utilizzare un agente per chattare con il modello

Creare un agente semplice

Ora che ha un'idea chiara di come funziona la chat con un modello, potenziamola con un agente che ne incapsuli le funzionalità. Successivamente integreremo la conoscenza del modello con una fonte dati personalizzata e richiameremo l'agente tramite un semplice esempio in Python.

Selezioni 'Agents/New Agent' per creare un nuovo agente. Indichi un nome per l'agente e un set di istruzioni. Le istruzioni sono obbligatorie e devono descrivere in modo specifico ciò che l'agente deve fare; in questo caso si tratterà di un agente in grado di rispondere solo a domande sui terremoti. Può lasciare Deployment sul valore predefinito gpt-4o, mentre i valori di default di Temperature e Top P vanno bene così come sono. Le modifiche alla configurazione dell'agente vengono salvate automaticamente.

Configurazione dell'agente per la chat sui terremoti

Cliccando sul pulsante 'Try in playground' può testare l'agente nello stesso modo in cui prima ha chattato direttamente con il modello.

Integrare l'agente con conoscenze aggiuntive

Azure AI Foundry offre diverse opzioni per integrare dati personalizzati nelle Sue applicazioni e nei Suoi servizi AI. Approfondire questo aspetto va oltre lo scopo dell'articolo, ma può trovare maggiori informazioni qui.

Come semplice esempio, aggiungerò un file PDF come fonte dati per fornire al mio agente maggiori conoscenze sui terremoti. Ho scaricato una copia in PDF della pagina di Wikipedia sul terremoto della Penisola di Kamchatka del 2025, che può scaricare qui se desidera seguire l'esempio e utilizzarlo nel Suo agente.

Una volta ottenuto il file PDF, clicchi sul pulsante '+Add' nella sezione Knowledge della configurazione dell'agente, quindi selezioni 'Files' per caricare il file. Può lasciare le impostazioni predefinite per creare un nuovo vector store e selezionare 'Upload and save'.

File PDF caricato per integrare l'agente con ulteriori conoscenze sui terremoti

Cliccando di nuovo su 'Try in playground', questa volta potrà chiedere informazioni sul terremoto di luglio 2025.

Chat con l'agente dopo l'aggiunta di una fonte dati

Ora che ha un'idea chiara di come funziona un agente di base in Azure AI Foundry, proviamo del codice Python per richiamare direttamente l'endpoint del modello. Prima di tutto, recuperi una copia dell'endpoint del progetto Azure AI Foundry dalla pagina Overview e l'Agent ID dalla pagina dell'agente.

Pagina Overview con l'endpoint del progetto Azure AI Foundry

Pagina dell'agente con l'Agent ID

Copi questo codice sorgente in locale in un file chiamato agent_earthquake_chat.py. È un esempio Python semplice e un po' giocoso, ben lontano dall'essere pronto per la produzione :)

from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
from azure.ai.agents.models import ListSortOrder

import os

endpoint = os.getenv("AZURE_FOUNDRY_ENDPOINT")
agent_id = os.getenv("AZURE_FOUNDRY_AGENT_ID")

if not endpoint or not agent_id:
    raise EnvironmentError("AZURE_FOUNDRY_ENDPOINT and AZURE_FOUNDRY_AGENT_ID must be set in your environment.")

project = AIProjectClient(
    credential=DefaultAzureCredential(),
    endpoint=endpoint)

agent = project.agents.get_agent(agent_id)

thread = project.agents.threads.create()
print(f"Created agent thread, ID: {thread.id}")
print("Type 'quit' to exit the chat.")

# Initial message
message = project.agents.messages.create(
    thread_id=thread.id,
    role="user",
    content="Hi Agent"
)

run = project.agents.runs.create_and_process(
    thread_id=thread.id,
    agent_id=agent.id)

if run.status == "failed":
    print(f"Run failed: {run.last_error}")
else:
    messages = project.agents.messages.list(thread_id=thread.id, order=ListSortOrder.ASCENDING)
    for message in messages:
        if message.text_messages:
            print(f"{message.role}: {message.text_messages[-1].text.value}")

# Chat loop
while True:
    user_input = input("You: ").strip()
    if user_input.lower() == "quit":
        print("Conversation ended. See you next time.")
        break

    # Add user message
    project.agents.messages.create(
        thread_id=thread.id,
        role="user",
        content=user_input
    )

    # Run agent again
    run = project.agents.runs.create_and_process(
        thread_id=thread.id,
        agent_id=agent.id)

    if run.status == "failed":
        print(f"Run failed: {run.last_error}")
        continue

    # Display latest response
    messages = list(project.agents.messages.list(thread_id=thread.id, order=ListSortOrder.ASCENDING))
    for message in reversed(messages):
        if message.role == "assistant" and message.text_messages:
            print(f"Agent: {message.text_messages[-1].text.value}\n")
            break

Di seguito le istruzioni passo passo e i comandi per eseguire lo script in un ambiente Python isolato, in modo da evitare qualsiasi dipendenza dai pacchetti globali.

1. Posizionandosi nella stessa cartella del codice sorgente scaricato, crei un ambiente Python virtuale:

python3 -m venv foundry-env

2. Attivi l'ambiente:

source foundry-env/bin/activate

3. Aggiorni pip (consigliato):

pip install --upgrade pip

4. Installi le dipendenze Azure necessarie:

pip install azure-ai-projects azure-identity

5. Imposti le variabili d'ambiente per l'agente Azure AI Foundry con i Suoi valori specifici:

export AZURE_FOUNDRY_ENDPOINT="https://foundryyizp.services.ai.azure.com/api/projects/foundry-demo-project"
export AZURE_FOUNDRY_AGENT_ID="asst_ABCfRyUC7X4AenJN3wyRY7AJ"

6. Esegua lo script:

python agent_earthquake_chat.py

Esempio di chat tramite Python

(foundry-env) david@Mac azure-ai-foundry % python agent_earthquake_chat.py
Created agent thread, ID: thread_Y9FxpLWwVELeY3wlNoE1K6ez
Type 'quit' to exit the chat.
MessageRole.USER: Hi Agent
MessageRole.AGENT: Hello! How can I assist you with earthquake-related information today?
You: What is Azure AI Foundry?
Agent: I'm here to assist with earthquake-related information only. Let me know if you have any questions about earthquakes!

You: What was the tsunami impact of the July 2025 earthquake not far from Russia?
Agent: The July 2025 earthquake off the coast of Kamchatka, Russia, had widespread tsunami impacts. Tsunami waves reached heights of up to 15 meters in some Russian regions, causing local panic and destruction, particularly in Severo-Kurilsk, Komandorsky Islands, and nearby areas. Coastal regions as far as Hawaii, Alaska, and Japan observed increased wave activity, with localized alerts issued in the Pacific Rim. Evacuations were prompted in Japan and parts of the United States due to concerns of waves exceeding several meters in height【8:0†source】【8:1†source】【8:19†source】.

You: Give me 10 bullet points explaining what happens when an earthquake occurs.
Agent: Here are 10 key points explaining what happens during an earthquake:

1. **Rupture at Fault Line**: Earthquakes begin when stress in Earth's crust surpasses the strength of the rocks, causing a sudden rupture along fault lines.

2. **Release of Energy**: This rupture releases a burst of energy in the form of seismic waves, propagating through the Earth.

3. **Seismic Waves Propagate**:
   - *Primary Waves (P-Waves)*: Travel fastest and move through solids, liquids, and gases.
   - *Secondary Waves (S-Waves)*: Slower than P-waves and cannot travel through liquids.

4. **Ground Shaking**: These seismic waves cause the ground to shake, with the intensity depending on the earthquake's magnitude and depth.

5. **Surface Displacement**: In some cases, visible breaks or shifts appear at the Earth's surface along the fault line.

6. **Aftershocks**: Smaller earthquakes occur as the crust adjusts to the changes caused by the mainquake.

7. **Tsunamis** (if under ocean): Submarine earthquakes displace water, potentially generating tsunamis that radiate outward.

8. **Landslides and Liquefaction**: Ground disturbances can lead to landslides or liquefaction of soils, which compromise stability in affected areas.

9. **Damage and Destruction**: Seismic activity damages buildings, infrastructure, and natural landscapes, depending on proximity and construction standards.

10. **Human Response and Resilience**: People respond with evacuations, rescue operations, and rebuilding efforts, adapting to the earthquake's aftermath.

Let me know if you'd like details on any specific aspect!

You: quit
Conversation ended. See you next time!

Il costo delle risorse create in questo esercizio è davvero contenuto: può prevedere una spesa di 1 o 2 dollari. Dopo aver creato il progetto e sperimentato con qualche decina di prompt tramite il chat playground e l'esempio Python, i miei costi sono rimasti sotto i 3 dollari.

Azure rende molto semplice ripulire tutte le risorse utilizzate durante l'esercizio. Tornando al Portale di Azure, vada su Resource groups, selezioni il resource group creato per questo esercizio e poi 'Delete resource group' per eliminarlo.

Eliminazione del resource group nel portale di Azure