Condividi tramite

Guida introduttiva: Eseguire il deployment del tuo primo agente ospitato

In questa guida introduttiva, distribuisci un agente di intelligenza artificiale containerizzato utilizzando gli strumenti Foundry nel servizio Foundry Agent. L'agente di esempio usa la ricerca Web e, facoltativamente, gli strumenti MCP per rispondere alle domande. Entro la fine, sarà presente un agente ospitato in esecuzione con cui è possibile interagire attraverso il playground Foundry. Scegliere il metodo di distribuzione preferito per iniziare.

In questo avvio rapido, tu:

  • Configurare un progetto campione di agenti con gli strumenti Foundry
  • Testare l'agente localmente
  • Distribuire il Servizio agente Fonderia
  • Interagire con l'agente nel playground
  • Pulire le risorse

Prerequisiti

Prima di iniziare, è necessario disporre di quanto segue:

Annotazioni

Gli agenti ospitati sono attualmente in anteprima.

Autorizzazione richiesta

È necessario Azure AI Project Manager nell'ambito del progetto per creare e distribuire agenti ospitati. Questo ruolo include sia le autorizzazioni del piano dati per creare agenti che la possibilità di assegnare il ruolo utente di Intelligenza artificiale di Azure all'identità dell'agente creata dalla piattaforma. L'identità dell'agente richiede all'utente di Intelligenza artificiale di Azure nel progetto di accedere ai modelli e agli artefatti in fase di esecuzione.

Se si utilizza azd o l'estensione di VS Code, gli strumenti gestiscono automaticamente la maggior parte delle assegnazioni di controllo degli accessi basate sui ruoli, tra cui:

Assicurarsi che l'identità gestita del progetto Foundry abbia il ruolo di pull sul Registro Container di Azure che si utilizza. se si preferisce e si ha accesso proprietario o "Amministratore accesso utenti", gli strumenti azd/vscode possono anche eseguire questa assegnazione. Utente di Intelligenza artificiale di Azure per l'identità dell'agente creata dalla piattaforma (modello di runtime e accesso agli strumenti)

Passaggio 1: Configurare l'project di esempio

Avviso

Questo documento riguarda gli agenti ospitati nel nuovo back-end e richiede azd ai agent versione 0.1.26-preview o successiva. Per l'esperienza legacy che usa Azure Container Apps, si prega di continuare a usare 0.1.25-preview.

Installare l'estensione dell'agente CLI di Azure Developer e inizializzare un nuovo progetto di agente ospitato.

  1. Installare l'estensione ai agent per l'interfaccia della riga di comando per sviluppatori di Azure:

    azd ext install azure.ai.agents

    Per verificare che l'estensione sia installata, eseguire:

    azd ext list

  2. Inizializzare un nuovo progetto di agente ospitato:

    azd ai agent init

    Quando richiesto, selezionare Avvia nuovo da un modello. Il flusso interattivo illustra la configurazione seguente:

    • Nome ambiente : determina il nome del gruppo di risorse, ad esempio my-hosted-agent crea rg-my-hosted-agent.
    • Selezionare la sottoscrizione Azure nella quale si vogliono creare le risorse Foundry.
    • Località : selezionare un'area per le risorse.
    • SKU del modello : selezionare lo SKU disponibile per l'area e la sottoscrizione.
    • Nome distribuzione : immettere un nome per la distribuzione del modello.
    • Dimensioni del contenitore : selezionare l'allocazione di CPU e memoria o accettare le impostazioni predefinite.

    Annotazioni

    Se esiste già un gruppo di risorse con lo stesso nome, azd provision usa il gruppo esistente. Per evitare conflitti, scegliere prima un nome di ambiente univoco o eliminare il gruppo di risorse esistente.

    Importante

    Se non si utilizza un server MCP, commentare o rimuovere le righe seguenti nel file agent.yaml:

    - name: AZURE_AI_PROJECT_TOOL_CONNECTION_ID
  value: <CONNECTION_ID_PLACEHOLDER>

    In alternativa, è anche possibile usare questo cmd:

    azd init -t Azure-Samples/azd-ai-starter-basic

    Il flag -t indica il modello.

    Stai dicendo a azd di usare questo modello specifico:

    Azure-Samples/azd-ai-starter-basic - Un progetto iniziale dal repository di esempio di Microsoft

    Il modello di base per l'intelligenza artificiale starter configura un'app minima basata sull'intelligenza artificiale usando i servizi di Azure. In genere, esso include:

    • Un back-end semplice (spesso Python o Node.js)
    • Integrazione con il servizio Azure OpenAI
    • Infrastruttura da distribuire:
      • App Web (Servizio app di Azure)
      • Risorse di intelligenza artificiale
    • Ambiente preconfigurato per la distribuzione rapida

    Suggerimento

    Se si esegue in un ambiente non interattivo, ad esempio una pipeline CI/CD o una sessione SSH, usare il --no-prompt flag con azd ai agent init. È inoltre necessario specificare tutti i valori obbligatori come flag della riga di comando anziché rispondere ai prompt interattivi.

  3. Effettuare il provisioning delle risorse di Azure necessarie:

    Annotazioni

    È necessario l'accesso Collaboratore alla sottoscrizione di Azure per il provisioning delle risorse.

    azd provision

    Questo comando richiede circa 5 minuti e crea le risorse seguenti:

    Risorsa Scopo Costo
    Gruppo di risorse Organizza tutte le risorse correlate nella stessa area Nessun costo
    Implementazione del modello Modello usato dall'agente Vedere prezzi di Foundry
    Progetto Fonderia Ospita l'agente e offre funzionalità di intelligenza artificiale In base al consumo; vedere i prezzi di Foundry
    Azure Container Registry Archivia le immagini del contenitore dell'agente Livello Basic; vedere prezzi di ACR
    spazio di lavoro Log Analytics Gestire tutti i dati di log in un'unica posizione Nessun costo diretto. Visualizza il costo di Log Analytics
    Approfondimenti sulle Applicazioni Monitora le prestazioni e i log dell'agente Pagamento a consumo; vedere prezzi di Azure Monitor
    Identità gestita Autentica l'agente per i servizi di Azure Nessun costo

    Suggerimento

    Eseguire azd down al termine di questo quickstart per eliminare le risorse e interrompere gli addebiti.

Passaggio 2: Testare l'agente in locale

Prima di eseguire la distribuzione, verificare che l'agente funzioni in locale.

  1. Avviare l'agente localmente:

    azd ai agent run

    Questo comando configura automaticamente l'ambiente, installa le dipendenze e avvia l'agente. Per avviare l'agente, utilizza startupCommand definito in azure.yaml.

    Annotazioni

    I pacchetti di anteprima possono generare avvisi di conflitto di versione delle dipendenze pip durante l'installazione. Questi avvisi non bloccano: l'agente viene avviato e risponde correttamente nonostante tali avvisi.

    Se l'agente non si avvia, verificare questi problemi comuni:

    Error Soluzione
    Errore AuthenticationError o DefaultAzureCredential Eseguire azd auth login di nuovo per aggiornare la sessione.
    ResourceNotFound Verificare che gli URL dell'endpoint corrispondano ai valori nel portale Foundry.
    DeploymentNotFound Controllare il nome della distribuzione in Compilazioni>distribuzioni.
    Connection refused Verificare che nessun altro processo usi la porta 8088.

  2. In un terminale separato inviare un messaggio di test all'agente locale:

    azd ai agent invoke --local "What is Microsoft Foundry?"

    Verrà visualizzata una risposta con i risultati della ricerca Web su Microsoft Foundry.

Passaggio 3: Eseguire la distribuzione nel servizio Foundry Agent

Poiché è già stato effettuato il provisioning dell'infrastruttura nel passaggio 1, distribuire il codice dell'agente in Azure:

azd deploy

Il contenitore dell'agente viene compilato in modalità remota, quindi Docker Desktop non è necessario nel computer.

Annotazioni

Il azd deploy comando assegna i ruoli di controllo degli accessi basati su ruoli di Azure all'identità dell'agente. Questa assegnazione di ruolo richiede le autorizzazioni Proprietario o Amministratore dell'accesso utente per la sottoscrizione, oltre a quello di Collaboratore necessario per il provisioning.

Avviso

L'agente ospitato comporta addebiti in fase di distribuzione. Al termine del test, completare La pulizia delle risorse per eliminare le risorse e arrestare gli addebiti.

Al termine, l'output mostrerà un collegamento ad Agent Playground e l'endpoint per richiamare l'agente a livello programmatico:

Deploying services (azd deploy)

  (✓) Done: Deploying service af-agent-with-foundry-tools
  - Agent playground (portal): https://ai.azure.com/nextgen/.../build/agents/af-agent-with-foundry-tools/build?version=1 
  - Agent endpoint: https://ai-account-<name>.services.ai.azure.com/api/projects/<project>/agents/af-agent-with-foundry-tools/versions/1

Importante

Assicurarsi di usare la versione prelease dell'estensione Microsoft Foundry Toolkit e l'estensione Foundry in VS Code.

Nella pagina delle estensioni di VS Code scegliere l'estensione Foundry Toolkit e l'estensione Foundry e passare alla versione non definitiva.

Passaggio 1: Creare un progetto Foundry

Usare l'estensione Microsoft Foundry Toolkit in VS Code per creare una nuova risorsa di Microsoft Foundry Project.

  1. Aprire il riquadro comandi (Ctrl+MAIUSC+P) e selezionare Microsoft Foundry: Create Project.

  2. Selezionare la sottoscrizione Azure.

  3. Creare un nuovo gruppo di risorse o selezionarne uno esistente.

  4. Immettere un nome per la risorsa del progetto Foundry.

Al termine della creazione del progetto, continuare con il passaggio successivo e distribuire un modello.

Passaggio 2: Distribuire un modello

Usare l'estensione Microsoft Foundry Toolkit in VS Code per distribuire un modello in Foundry.

  1. Aprire il riquadro comandi (Ctrl+MAIUSC+P) e selezionare Microsoft Foundry: Open Model Catalog.

  2. Esplorare il catalogo dei modelli o cercare gpt-4.1 e selezionare il pulsante Distribuisci .

  3. Nella pagina Distribuzione del modello, selezionare il pulsante Deploy su Microsoft Foundry.

Dopo aver distribuito correttamente il modello, passare al passaggio successivo e creare un progetto dell'agente ospitato

Passaggio 3: Creare un progetto dell'agente ospitato

Usare l'estensione Microsoft Foundry Toolkit in VS Code per eseguire lo scaffolding di un nuovo progetto agente ospitato.

  1. Aprire il riquadro comandi (Ctrl+MAIUSC+P) e selezionare Microsoft Foundry: Create new Hosted Agent.

  2. Selezionare il framework da usare.

  3. Selezionare un linguaggio di programmazione, Python o C#.

  4. Selezionare l'API Risposte o l'API Invoke.

  5. Selezionare il codice di esempio da usare.

  6. Scegliere la cartella in cui salvare i file di progetto.

  7. Immettere un nome per l'agente ospitato.

Verrà avviata una nuova finestra di VS Code con la nuova cartella del progetto agente come area di lavoro attiva.

Passaggio 4: Installare le dipendenze

È consigliabile usare un ambiente virtuale per isolare le dipendenze del progetto:

macOS/Linux:

python -m venv .venv
source .venv/bin/activate

Windows (PowerShell):

python -m venv .venv
.\.venv\Scripts\Activate.ps1

Installazione delle dipendenze

Installare le dipendenze necessarie Python usando pip:

pip install -r requirements.txt

Per un elenco dei pacchetti necessari, vedere il requirement.txt.

Passaggio 5: Testare l'agente in locale

Esegui e testa l'agente prima di distribuirlo.

Premere F5 in VS Code per avviare il debug. In alternativa, è possibile usare il menu di debug di VS Code:

  1. Aprire la visualizzazione Esegui e Debug (CTRL+MAIUSC+D/CMD+MAIUSC+D)
  2. Selezionare "Debug server HTTP flusso di lavoro locale" nell'elenco a discesa
  3. Fare clic sul pulsante verde Avvia debug (o premere F5)

In questo modo:

  1. Avviare il server HTTP con il debug abilitato
  2. Aprire Foundry Toolkit Agent Inspector per i test interattivi
  3. Consente di impostare punti di interruzione ed esaminare il flusso di lavoro

Opzione 2: Eseguire nel terminale

Esegui come server HTTP (impostazione predefinita):

python main.py

L'agente ospitato verrà avviato localmente in http://localhost:8088/.

PowerShell (Windows):

$body = @{
   input = "I need a hotel in Seattle from 2025-03-15 to 2025-03-18, budget under `$200 per night"
    stream = $false
} | ConvertTo-Json

Invoke-RestMethod -Uri http://localhost:8088/responses -Method Post -Body $body -ContentType "application/json"

Bash/curl (Linux/macOS):

curl -sS -H "Content-Type: application/json" -X POST http://localhost:8088/responses \
   -d '{"input": "Find me hotels in Seattle for March 20-23, 2025 under $200 per night","stream":false}'

L'agente userà lo get_available_hotels strumento per cercare gli hotel disponibili corrispondenti ai criteri.

Passaggio 6. Eseguire la distribuzione in Servizio Agente Fonderia

Distribuire il tuo agente direttamente da VS Code.

  1. Aprire il riquadro comandi (Ctrl+MAIUSC+P) e selezionare Microsoft Foundry: Deploy Hosted Agent.

  2. Selezionare "ACR predefinito"

  3. Selezionare la configurazione della CPU e della memoria per il contenitore dell'agente ospitato.

Passare allo strumento di esplorazione di Microsoft Foundry Toolkit selezionando l'icona a sinistra. L'agente compare nella barra laterale della vista ad albero Agenti ospitati (anteprima) una volta completata la distribuzione.

Verificare e testare il proprio agente

Al termine della distribuzione, verificare che l'agente sia in esecuzione.

Controllare lo stato dell'agente

Controllare lo stato dell'agente per confermare che sia in esecuzione.

  1. Seleziona il tuo agente ospitato dalla struttura ad albero degli agenti ospitati (Anteprima).

  2. Selezionare l'agente appena distribuito

La pagina dei dettagli mostra lo stato nella sezione Dettagli contenitore.

Eseguire test nel playground con VS Code

Microsoft Foundry Toolkit per VS Code include un playground integrato per chattare e interagire con l'agente.

  1. Seleziona il tuo agente ospitato dalla struttura ad albero degli agenti ospitati (Anteprima).

  2. Selezionare l'opzione Playground e digitare un messaggio e inviare per testare l'agente.

Verificare lo stato dell'agente

Controllare lo stato dell'agente distribuito:

azd ai agent show

Per visualizzare l'output in formato tabella:

azd ai agent show --output table

Se il progetto dispone di più servizi agente, specificare il nome dell'agente come argomento posizionale:

azd ai agent show <agent-name>

Suggerimento

Trova <agent-name> nel file azure.yaml nella sezione services:.

Testare l'agente distribuito

Inviare un messaggio di test all'agente distribuito:

azd ai agent invoke "What is Microsoft Foundry?"

Verrà visualizzata una risposta con i risultati della ricerca Web su Microsoft Foundry. La risposta potrebbe richiedere alcuni secondi perché l'agente interroga fonti esterne.

Visualizzare i log dell'agente

Monitorare i log live dell'agente:

# Fetch recent container console logs
azd ai agent monitor

# Fetch the last N lines of console logs
azd ai agent monitor --tail 20

# Fetch system event logs (container start and stop events)
azd ai agent monitor --type system

# Stream session logs in real time
azd ai agent monitor --session <session-id> --follow

Se il progetto dispone di più servizi agente, specificare il nome dell'agente come argomento posizionale:

azd ai agent monitor <agent-name> --follow

Test nel parco giochi Foundry

Navigare verso l'agente nel portale Foundry:

  1. Aprire il portale di Foundry e accedere con l'account Azure.

  2. Selezionare il progetto dall'elenco Progetti recenti oppure selezionare Tutti i progetti per trovarlo.

  3. Nel riquadro di spostamento a sinistra selezionare Compila per espandere il menu e quindi selezionare Agenti.

  4. Nell'elenco degli agenti trovare l'agente distribuito (corrisponde al nome dell'agente dalla distribuzione).

  5. Selezionare il nome dell'agente per aprire la relativa pagina dei dettagli, quindi selezionare Apri nel playground nella barra degli strumenti superiore.

  6. Nell'interfaccia della chat digitare un messaggio di test come "Che cos'è Microsoft Foundry?" e premere Invio.

  7. Verificare che l'agente risponda con informazioni dai risultati della ricerca Web. La risposta potrebbe richiedere alcuni secondi perché l'agente interroga fonti esterne.

Suggerimento

Se il playground non viene caricato o l'agente non risponde, verificare che lo stato dell'agente sia Started nella pagina Dettagli contenitore descritta in precedenza.

Pulire le risorse

Per evitare addebiti, eliminare le risorse al termine.

Avviso

Questo comando elimina definitivamente tutte le risorse Azure nel gruppo di risorse, incluso il progetto Foundry, le distribuzioni di modelli, registro contenitori, Application Insights e l'agente ospitato. Non è possibile annullare questa azione. Se si utilizza un gruppo di risorse esistente che contiene altre risorse, fare attenzione: azd down rimuove tutto nel gruppo, non solo le risorse create da questa guida di avvio rapido.

Per visualizzare in anteprima gli elementi che verranno eliminati prima di confermare:

azd down --preview

Quando si è pronti per l'eliminazione, eseguire:

azd down

Il processo di pulizia richiede circa 2-5 minuti.

Avviso

L'eliminazione delle risorse rimuove definitivamente tutte le risorse Azure create in questa guida introduttiva, tra cui il progetto Foundry, registro contenitori, Application Insights e l'agente ospitato. Non è possibile annullare questa azione.

Per eliminare le risorse, aprire il portale Azure, passare al gruppo di risorse ed eliminarlo insieme a tutte le risorse contenute.

Per verificare che le risorse siano state eliminate, aprire il portale Azure, passare al gruppo di risorse e verificare che le risorse non vengano più visualizzate. Se il gruppo di risorse è vuoto, è anche possibile eliminarlo.

Risoluzione dei problemi

Se si verificano problemi, provare queste soluzioni per problemi comuni:

Problema Soluzione
Errore SubscriptionNotRegistered Registrare i provider:az provider register --namespace Microsoft.CognitiveServices
AuthorizationFailed durante il provisioning Richiedere il ruolo Collaboratore nella sottoscrizione o nel gruppo di risorse.
L'agente non viene avviato in locale Verificare che le variabili di ambiente siano impostate ed eseguite az login per aggiornare le credenziali.
Errore AcrPullUnauthorized Concedere il ruolo AcrPull all'identità gestita del progetto nel registro dei contenitori.

Per informazioni dettagliate su tutte le autorizzazioni e le assegnazioni di ruolo coinvolte nella distribuzione dell'agente ospitato, vedere Informazioni di riferimento sulle autorizzazioni dell'agente ospitato.

Problema Soluzione
azd ai agent init Fallisce Eseguire azd version per verificare la versione 1.23.0+. Eseguire l'aggiornamento con winget upgrade Microsoft.Azd (Windows) o brew upgrade azd (macOS). Verificare che l'estensione dell'agente sia installata con azd ext list.
Modello non trovato nel catalogo Creare una copia tramite fork del file agent.yaml di esempio e modificare la distribuzione del modello in una versione disponibile nella sottoscrizione, ad esempio gpt-4.1. Rimuovere quindi il valore AZURE_LOCATION nel file .azure/<environment name>/.env. Esegui di nuovo il comando azd ai agent init con il file forkato agent.yaml.

Visualizzare i log dei contenitori dell'agente

È possibile controllare la console e i log di sistema del contenitore per risolvere i problemi.

  1. Seleziona il tuo agente ospitato dalla struttura ad albero degli agenti ospitati (Anteprima).

  2. Selezionare la scheda "Playground" dell'agente ospitato

  3. Selezionare la sezione "Log" nei dettagli della sessione.

Visualizzare i file di sessione dell'agente

È possibile visualizzare tutti i file archiviati nella home directory dell'agente basato su ADC

  1. Selezionare l'agente ospitato dalla visualizzazione ad albero Agenti ospitati (Anteprima).

  2. Selezionare la scheda "Playground" dell'agente ospitato

  3. Selezionare la sezione "files" nei dettagli della sessione.

È possibile scaricare, caricare e creare cartelle all'interno della cartella corrente, facendo clic su una cartella si eseguirà l'istruzione nella cartella e facendo clic sulla barra di spostamento superiore verrà eseguito un passaggio indietro in tale cartella.

Problema Soluzione
Estensione non trovata Installare l'estensione Microsoft Foundry Toolkit for VS Code da VS Code Marketplace.

Che cosa si è appreso

Questa guida introduttiva spiega come:

  • Configurare un esempio di agente ospitato con gli strumenti Foundry (ricerca Web e MCP)
  • Testato l'agente localmente
  • Distribuito nel Servizio Agente Fonderia
  • Agente verificato nel playground Foundry

Passaggi successivi

Dopo aver distribuito il tuo primo agente ospitato, scopri come:

Gestire il ciclo di vita dell'agente ospitato

Personalizzare l'agente con funzionalità aggiuntive:

È possibile visualizzare un elenco completo degli strumenti disponibili nell'articolo del catalogo degli strumenti .

Contenuti correlati

  • Last updated on