Guida introduttiva: Distribuire il primo agente ospitato

In questa guida introduttiva viene distribuito un agente AI containerizzato che chiama i modelli Foundry e usa gli strumenti Foundry nel Foundry Agent Service. L'agente di esempio usa la ricerca Web e, facoltativamente, gli strumenti MCP (Model Context Protocol) per rispondere alle domande. Alla fine, avrai un agente ospitato funzionante con cui puoi interagire tramite il Playground Foundry. Scegliere il metodo di distribuzione preferito per iniziare.

In questa guida di avvio rapido:

  • Configurare un progetto di esempio di agente con gli strumenti Foundry
  • Testare l'agente in locale
  • Eseguire la distribuzione nel servizio agente di Foundry
  • Interagisci con il tuo agente nell'ambiente di prova
  • Pulire le risorse

Prerequisiti

Prima di iniziare, è necessario:

Nota

Gli agenti ospitati sono attualmente in fase di anteprima.

Autorizzazione richiesta

È necessario Azure AI Project Manager nell'ambito del progetto per creare e implementare agenti hostati. Questo ruolo include sia le autorizzazioni del piano dati per creare agenti che la possibilità di assegnare il ruolo utente di intelligenza artificiale Azure all'identità dell'agente creata dalla piattaforma. L'identità dell'agente deve avere "Utente Azure AI" nel progetto per accedere ai modelli e agli artefatti a runtime.

Se si usa azd o l'estensione VS Code, gli strumenti gestiscono automaticamente la maggior parte delle assegnazioni di controllo degli accessi in base al ruolo, tra cui:

Assicurarsi che l'identità gestita del Foundry Project abbia il ruolo di pull su Registro Azure Container usato. Se preferisci e hai accesso come "Proprietario" o "Amministratore dell'accesso utente", azd/vscode può inoltre eseguire questa assegnazione per te. Utente di Azure AI per l'identità dell'agente creata dalla piattaforma (modello runtime e accesso agli strumenti)

Passaggio 1: Configurare il progetto di esempio

Avviso

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

Installare l'estensione dell'agente CLI per sviluppatori Azure 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. Avvia un nuovo progetto di agente ospitato in una directory vuota:

    azd ai agent init

    Il flusso interattivo illustra la configurazione seguente:

    • Language: selezionare il linguaggio di programmazione per il quale si vuole usare il codice di esempio C# o Python.
    • Modello di agente : selezionare un esempio da cui iniziare.
    • Model Configuration : selezionare questa opzione per distribuire un nuovo modello in Foundry o usarne una esistente da un Project Foundry esistente.
    • Sottoscrizione di Azure: selezionare la sottoscrizione in cui desideri creare le risorse Foundry.
    • Località : selezionare un'area per le risorse.
    • SKU del modello — selezionare lo SKU disponibile per la regione 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.

    Importante

    Se hai selezionato un campione con strumenti e non stai usando un server MCP, commenta o rimuovi le righe seguenti nel file agent.yaml.

    - name: AZURE_AI_PROJECT_TOOL_CONNECTION_ID
  value: <CONNECTION_ID_PLACEHOLDER>

    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:

    Nota

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

    azd provision

    Questo comando richiede alcuni minuti e crea le risorse seguenti:

    Risorsa Scopo Costo
    Gruppo di risorse Organizza tutte le risorse correlate nella stessa area Nessun costo
    Distribuzione del modello Modello usato dall'agente Consulta Tariffe di Foundry
    Progetto Foundry Ospita l'agente e offre funzionalità di intelligenza artificiale In base al consumo; consulta Tariffe di Foundry
    Registro Azure Container Archivia le immagini del contenitore dell'agente Piano Base; vedere Prezzi di Azure Container Registry
    spazio di lavoro Log Analytics Gestire tutti i dati di log in un'unica posizione Nessun costo diretto. Vedere Log Analytics costo
    Application Insights Monitora le prestazioni e i log dell'agente Pagamento in base al consumo; consulta prezzi di Monitoraggio di Azure
    Identità gestita Autentica l'agente per i servizi di Azure Nessun costo

    Suggerimento

    Eseguire azd down al termine di questa guida introduttiva 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. Usa il startupCommand definito in azure.yaml per avviare l'agente.

    Nota

    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:

    Errore Soluzione
    AuthenticationError o DefaultAzureCredential guasto Eseguire azd auth logout e quindi azd auth login 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.

    Per gli agenti che usano l'API Risposte, è possibile inviare una stringa come payload:

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

    Per gli agenti che usano l'API Invocazioni, controllare il README.md per il payload previsto. Gli esempi richiedono in genere un payload JSON, ma esaminate ciò che è in README.md per un esempio specifico:

    Verrà visualizzata una risposta dall'agente.

Passaggio 3: Eseguire la distribuzione nel servizio agente Foundry

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.

Nota

Il comando azd deploy assegna i ruoli Azure RBAC all'identità dell'agente. Questa assegnazione di ruolo richiede le autorizzazioni Proprietario o Amministratore accesso utenti per la sottoscrizione, oltre al ruolo Collaboratore necessario per il provisioning.

Avviso

L'agente ospitato genera costi mentre è in funzione. Al termine del test, completare La pulizia delle risorse per eliminare le risorse e arrestare gli addebiti.

Al termine, l'output mostra un collegamento a Agent Playground e all'endpoint per richiamare l'agente a livello di codice:

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 Foundry Project Microsoft.

  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 Foundry Project.

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 modello, selezionare il pulsante Distribuisci 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 della distribuzione.

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 del server HTTP del 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

"Ciò avvierà l'agente ospitato localmente su 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: Distribuire al servizio agente Foundry

Distribuisci 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 all'Microsoft Foundry Toolkit Explorer selezionando l'icona a sinistra. L'agente viene visualizzato nella barra degli strumenti della visualizzazione ad albero Agenti ospitati (Anteprima) al termine della distribuzione.

Verificare e testare l'agente

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

Controllare lo stato dell'agente

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

  1. Selezionare l'agente ospitato nella visualizzazione ad albero di Hosted Agents (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. Selezionare l'agente ospitato nella visualizzazione ad albero di Hosted Agents (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 sotto la sezione services:.

Testare l'agente distribuito

Inviare un messaggio di test all'agente distribuito usando lo stesso invoke comando usato in precedenza, ma senza il --local flag :

Per gli agenti che usano l'API Risposte, è possibile inviare una stringa come payload:

azd ai agent invoke <payload>

Verrà visualizzata una risposta dall'agente dopo alcuni secondi.

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 all'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, individua il tuo agente distribuito (questo corrisponde al nome dell'agente della tua 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 origini esterne.

Suggerimento

Se il playground non viene caricato o l'agente non risponde, verificare lo stato dell'agente utilizzando Started la 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. Questa azione non può essere annullata. Se si usa un gruppo di risorse esistente che contiene altre risorse, fare attenzione — azd down rimuove tutti gli elementi nel gruppo, non solo le risorse create da questa procedura rapida.

Per visualizzare in anteprima ciò che verrà eliminato, eseguire il down comando :

azd down

Al termine, azd mostra tutte le risorse che verranno eliminate e chiede di confermare. Selezionare questa opzione yes per continuare o no annullarla.

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. Questa azione non può essere annullata.

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
SubscriptionNotRegistered Errore Registrare i fornitori: az provider register --namespace Microsoft.CognitiveServices
AuthorizationFailed durante la fornitura Richiedere il ruolo Collaboratore nella sottoscrizione o nel gruppo di risorse.
Agent non viene avviato in locale Verificare che le variabili di ambiente siano impostate ed eseguite az login per aggiornare le credenziali.
AcrPullUnauthorized Errore Concedere il ruolo AcrPull all'identità gestita del progetto nel registro dei container.

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 Ha esito negativo Eseguire azd version per verificare la versione 1.24.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. Assicurarsi di avere la versione più recente dell'estensione con azd ext upgrade azure.ai.agents, versione 0.1.27-preview o successiva.

Visualizzare i log dei contenitori dell'agente

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

  1. Selezionare l'agente ospitato nella visualizzazione ad albero di Hosted Agents (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 il tuo Agente Ospitato dalla visualizzazione ad albero degli 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 per VS Code da VS Code Marketplace.

Cosa si è appreso

In questa guida rapida:

  • Configurare un esempio di agente ospitato con gli strumenti Foundry (ricerca Web e MCP)
  • Test dell'agente eseguito localmente
  • Distribuito al servizio Agente di Foundry
  • Verificato il tuo agente nell'ambiente di test di Foundry

Passaggi successivi

Dopo aver distribuito il primo agente ospitato, impara 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 .

Contenuto correlato

  • Last updated on