Guida introduttiva: Eseguire il deployment del tuo primo agente ospitato

• Interfaccia della riga di comando per sviluppatori di Azure versione 1.24.0 o successiva

• Visual Studio Code
• Estensione Microsoft Foundry Toolkit per Visual Studio Code

Autorizzazione richiesta

È necessario disporre di Azure AI Project Manager a livello di 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 usa azd o l'estensione VS Code, gli strumenti gestiscono automaticamente la maggior parte delle assegnazioni del controllo degli accessi in base al ruolo, tra cui:

Verificare che l'identità gestita del Foundry Project abbia il ruolo ACRPull sul Registro Azure Container in uso. Se preferisci e hai accesso Proprietario o "Amministratore accesso utenti", gli strumenti azd/vscode possono anche eseguire questa configurazione per te. 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

Installare l'estensione agente di Azure Developer CLI 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. Inizializza un nuovo progetto con agente ospitato in una directory vuota:

   azd ai agent init
   

   Il flusso interattivo illustra la configurazione seguente:

   • Language - Selezionare Python.
   • Agent Template - Selezionare 'Agente di base (risposte, Framework agente, Python)'
   • Configurazione del modello : selezionare per distribuire un nuovo modello in Foundry o usarne uno esistente da un progetto Foundry esistente.
   • 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.

   Importante

   Se è stato selezionato un esempio con gli strumenti e non si sta utilizzando un server MCP, commentare o rimuovere 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:

   Annotazioni

   È necessario l'accesso Collaboratore 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
   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
   Registro Azure Container	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 Monitoraggio di Azure
   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 sono di blocco: l'agente viene avviato e risponde in modo corretto nonostante tali avvisi.

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

   Error	Soluzione
   Errore AuthenticationError o DefaultAzureCredential	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 utilizzano invocazioni API, controllare il payload previsto di README.md. Gli esempi richiedono in genere un payload JSON, ma controlla cosa c'è in README.md per un esempio specifico.

   Dovresti vedere una risposta dall'agente.

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.

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

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

Usa l'estensione Microsoft Foundry Toolkit in VS Code per creare la struttura di base di un nuovo progetto di 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.

Opzione 1: premere F5 (scelta consigliata)

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

Verrà avviato localmente l'agente ospitato 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. 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.

Controllare lo stato dell'agente

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

1. Seleziona il tuo agente ospitato nella visualizzazione ad albero Hosted Agents (Preview).

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 l'agente ospitato nella visualizzazione ad albero di 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]

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 "Hello"

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

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.

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

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 nella visualizzazione ad albero 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. Seleziona il tuo agente ospitato nella 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.