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.

Passaggio 1: Configurare l'project di esempio

Inizializzare un nuovo project con il modello di avvio Foundry e configurarlo con l'esempio agent-with-foundry-tools.

  1. Inizializzare il modello di avvio in una directory vuota:

    azd init -t https://github.com/Azure-Samples/azd-ai-starter-basic

    Questo comando interattivo richiede un nome di ambiente , ad esempio my-hosted-agent. Il nome dell'ambiente determina il nome del gruppo di risorse (rg-my-hosted-agent).

    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.

  2. Inizializzare l'esempio di agente:

    azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/agent-framework/agent-with-foundry-tools/agent.yaml

    Questo comando interattivo richiede i valori di configurazione seguenti:

    • Azure sottoscrizione: selezionare la sottoscrizione Azure in cui si desidera creare le risorse Foundry.
    • Località : selezionare un'area per le risorse
    • SKU del modello - selezionare lo SKU disponibile per la vostra regione e abbonamento
    • Nome distribuzione : immettere un nome per la distribuzione del modello
    • Memoria del contenitore : immettere un valore per l'allocazione di memoria del contenitore o accettare le impostazioni predefinite
    • CPU del contenitore: immettere un valore per l'allocazione della CPU del contenitore o accettare le impostazioni predefinite
    • Repliche minime : immettere un valore per le repliche minime del contenitore
    • Numero massimo di repliche : immettere un valore per le repliche massime del contenitore

    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>

  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
    Area di lavoro Log Analytics Gestire tutti i dati di log in un'unica posizione Nessun costo diretto. Vedere costo di Log Analytics
    Approfondimenti sulle Applicazioni Monitora le prestazioni e i log dell'agente Pagamento in base al 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. Creare e attivare un ambiente virtuale Python:

    Bash:

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

    PowerShell:

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

  2. Installare le dipendenze:

    pip install -r ./src/af-agent-with-foundry-tools/requirements.txt

  3. Copiare le variabili di ambiente necessarie usate nel codice dell'agente in un file con estensione env locale:

    Bash:

    azd env get-values > .env

    PowerShell:

    azd env get-values > .env

  4. Aggiungere la AZURE_OPENAI_CHAT_DEPLOYMENT_NAME variabile al .env file con il nome della distribuzione del modello:

    AZURE_OPENAI_CHAT_DEPLOYMENT_NAME="gpt-4.1"

  5. Eseguire l'agente in locale:

    python ./src/af-agent-with-foundry-tools/main.py

    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.

  6. Eseguire il test con un client REST. L'agente viene eseguito in localhost:8088

    Bash:

    curl -X POST http://localhost:8088/responses \
    -H "Content-Type: application/json" \
    -d '{"input": "What is Microsoft Foundry?"}'

    PowerShell:

    Invoke-RestMethod -Method Post `
    -Uri "http://localhost:8088/responses" `
    -ContentType "application/json" `
    -Body '{"input":"What is Microsoft Foundry?"}'

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

  7. Arrestare il server locale con CTRL+C.

Passaggio 3: Eseguire la distribuzione nel servizio Foundry Agent

Il comando azd up combina tre passaggi in uno: infrastruttura di provisioning, creazione di pacchetti dell'applicazione e distribuzione in Azure. Equivale all'esecuzione di azd provision, azd package e azd deploy separatamente.

Prima di iniziare, verificare che Docker Desktop sia in esecuzione:

docker info

Se questo comando non riesce, avviare Docker Desktop e attendere che venga inizializzato prima di continuare.

Distribuisci il tuo agente

azd up

La prima distribuzione richiederà più tempo perché Docker deve compilare l'immagine.

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, verrà visualizzato un collegamento a Agent Playground e all'endpoint per l'agente che può essere usato 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

Passaggio 1: Creare un progetto Foundry

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

  1. Aprire la Palette dei comandi (CTRL+MAIUSC+P) e selezionare Microsoft Foundry: Crea progetto.

  2. Seleziona la tua sottoscrizione di Azure.

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

  4. Immettere un nome per la risorsa 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 in VS Code per distribuire un modello in Foundry.

  1. Aprire la Palette dei comandi (Ctrl+Shift+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 Distribuisci in 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 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 (Microsoft Foundry: Crea nuovo agente ospitato).

  2. Selezionare il modello Single Agent o Multi-Agent Workflow

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

  4. Scegliere il modello gpt-4.1 esistente distribuito nel passaggio precedente.

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

  6. 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 Python necessarie usando pip:

pip install -r requirements.txt

I pacchetti necessari sono:

  • azure-ai-agentserver-agentframework - Agent Framework e AgentServer SDK

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 AI 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 (Microsoft Foundry: Distribuisci agente ospitato).

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

  3. Nella finestra di dialogo visualizzata selezionare il pulsante Conferma e distribuisci.

Passare allo strumento di esplorazione di Microsoft Foundry 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 una versione (v1) per aprire la pagina dei dettagli.

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

Eseguire test nel playground con VS Code

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

  1. Selezionare l'agente ospitato nella visualizzazione ad albero degli Agenti Ospitati (Anteprima).

  2. Selezionare una versione (v1) per aprire la pagina dei dettagli.

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

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 di Azure create in questo avvio rapido, tra cui il progetto Foundry, il Container Registry, l'Application Insights e l'agente ospitato. Non è possibile annullare questa azione.

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 di risorse rimuove definitivamente tutte le risorse di Azure create in questa guida introduttiva, tra cui il progetto Foundry, Registro Container, Application Insights e l'agente ospitato. Non è possibile annullare questa azione.

Per eliminare le risorse, aprire il portale di 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 di 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
Errori di compilazione di Docker Verificare che Docker Desktop sia in esecuzione. Eseguire docker info per verificare.
Errore SubscriptionNotRegistered Registrare i fornitori: 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.
Problema Soluzione
azd 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).
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 visualizzazione ad albero degli agenti ospitati (anteprima).

  2. Selezionare una versione (v1) per aprire la pagina dei dettagli.

  3. Selezionare il pulsante Log a destra per aprire il visualizzatore log.

Problema Soluzione
Estensione non trovata Installare l'estensione Microsoft Foundry per 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