Guida introduttiva: Eseguire il deployment del tuo primo agente ospitato

• Azure Developer CLI (AZD) 1.25.3 o versione successiva.

• Estensione azd microsoft.foundry . Installare e verificare l'estensione dopo l'installazione di AZD:

  azd ext install microsoft.foundry
  

• Codice di Visual Studio.
• Microsoft Foundry Toolkit per Visual Studio Code.

Passaggio 1: Inizializzare l'agente di esempio

Inizializzare un nuovo agente ospitato usando l'esempio di base di Agent Framework in una directory vuota:

azd ai agent init -m "https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/agent-framework/responses/01-basic/agent.manifest.yaml" --deploy-mode code

Il flusso interattivo richiede:

• Nome dell'agente: Personalizza il nome o accetta l'impostazione predefinita, agent-framework-agent-basic-responses
• Foundry Project: selezionare Crea un nuovo project Foundry o Usa un project foundry esistente
• Tenant: selezionare il tenant Azure
• Sottoscrizione: selezionare la sottoscrizione Azure
• Location: Selezionare un'area Azure
• Modello: selezionare il modello predefinito, gpt-4.1-mini o un altro modello a cui è possibile accedere.
• Versione modello: selezionare l'opzione predefinita .
• SKU del modello: selezionare un'opzione con quota disponibile che non è Batch, in genere Standard o GlobalStandard
• Capacità di distribuzione: selezionare il valore predefinito10
• Nome distribuzione: selezionare il valore predefinitogpt-4.1-mini

Al termine, dovresti visualizzare La definizione dell'agente di IA è stata aggiunta correttamente al progetto azd. Modificare la directory nella cartella dell'agente appena creata.

cd agent-framework-agent-basic-responses

Passaggio 2: Effettuare il provisioning delle risorse di Azure

Effettuare il provisioning delle risorse definite in azure.yaml:

azd provision

Passaggio 3: Testare l'agente in locale

azd ai agent run

Questo comando crea un ambiente virtuale, installa le dipendenze, avvia l'agente usando il startupCommand definito in azure.yaml e apre il controllo agente nel browser in modo da poter chattare con l'agente.

Passaggio 4. Eseguire la distribuzione in Servizio Agente Fonderia

Compilare e distribuire il contenitore dell'agente:

azd deploy

Al termine dell'esecuzione del comando, l'output mostra i collegamenti al playground dell'agente e all'endpoint dell'agente:

Deploying services (azd deploy)

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

Passaggio 5: Richiamare l'agente

1. Inviare la stessa richiesta all'agente distribuito:

   azd ai agent invoke "Write a haiku about deploying cloud applications."
   

   Dovrebbe essere visualizzata una risposta haiku entro pochi secondi.

2. (Facoltativo) Trasmettere i log dei contenitori durante l'interazione con l'agente:

   azd ai agent monitor --follow
   

Passaggio 1: Creare un progetto Foundry

1. Aprire il riquadro comandi (Ctrl+MAIUSC+P) e selezionare Foundry Toolkit: Create Project.
2. Selezionare la sottoscrizione Azure.
3. Creare un nuovo gruppo di risorse o selezionarne uno esistente.
4. Immettere un nome per il progetto Foundry.

Passaggio 2: Distribuire un modello

1. Aprire il riquadro comandi e selezionare Foundry Toolkit: Apri catalogo modelli.
2. Cerca gpt-4.1 e seleziona Distribuisci.
3. Nella pagina di distribuzione del modello selezionare Deploy per Microsoft Foundry.

Passaggio 3: Creare un progetto agente ospitato

1. Aprire il riquadro comandi e selezionare Foundry Toolkit: Crea nuovo agente ospitato.
2. Selezionare il Python come lingua.
3. Per "Framework", seleziona Agent Framework.
4. Selezionare Responses API come tipo di protocollo.
5. Selezionare Basic come codice di esempio.
6. Selezionare il pulsante "Avanti".
7. Scegliere una cartella per i file di progetto e immettere un nome per l'agente.
8. Per "Configurazione dell'ambiente", scegliere Configura con Microsoft Foundry, il contenuto deve essere popolato automaticamente con il progetto e il modello creati nel passaggio 1 e 2.
9. Selezionare il pulsante "Crea".

Viene visualizzata una nuova finestra di VS Code con il progetto come area di lavoro attiva.

Passaggio 4: Installare le dipendenze

Creare un ambiente virtuale e installare i requisiti.

Per macOS o Linux:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Per Windows (PowerShell):

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

Passaggio 5: Testare l'agente in locale

Premere F5 per avviare il server HTTP locale con il debug abilitato. Foundry Toolkit Agent Inspector si apre per i test interattivi ed è possibile impostare punti di interruzione nel codice.

Per eseguire il server senza eseguire il debug:

python main.py

L'agente ascolta su http://localhost:8088/. Inviare un prompt di test con curl (o qualsiasi client HTTP):

curl -sS -H "Content-Type: application/json" -X POST http://localhost:8088/responses \
    -d '{"input": "Write a haiku about deploying cloud applications.", "stream": false}'

Passaggio 6. Eseguire la distribuzione in Servizio Agente Fonderia

1. Apri la tavolozza dei comandi e seleziona Foundry Toolkit: Deploy Hosted Agent. Verrà aperta una visualizzazione Web di distribuzione.
2. Per "Metodo di distribuzione", selezionare Codice.
3. Selezionare Remote come modalità del pacchetto.
4. Il "Nome agente" dovrebbe compilarsi automaticamente.
5. Selezionare il pulsante "Avanti".
6. Questa pagina "Rivedi e distribuisci" deve essere popolata automaticamente.
7. Selezionare il pulsante "Distribuisci".

Al termine della distribuzione, l'agente viene visualizzato in Agenti ospitati (anteprima) in Foundry Toolkit Explorer.

Passaggio 7: Richiamare l'agente

1. In Esplora risorse di Foundry Toolkit, espandi Agenti ospitati (anteprima) e seleziona il tuo agente. La pagina dei dettagli mostra lo stato nella sezione Dettagli della distribuzione.
2. Seleziona la scheda Playground e invia un prompt di prova come Write a haiku about deploying cloud applications..

azd down

azd elenca le risorse eliminate e richiede la conferma. La pulizia richiede circa 2-5 minuti.

1. Apri il portale di Azure e passa al gruppo di risorse che contiene l'agente.
2. Selezionare Elimina gruppo di risorse, digitare il nome del gruppo di risorse da confermare e selezionare Elimina.