Inizializzare un progetto agente ospitato con l'interfaccia della riga di comando per sviluppatori di Azure

Importante

Gli elementi contrassegnati (anteprima) in questo articolo sono attualmente in anteprima pubblica. Questa anteprima viene fornita senza un contratto di servizio e non è consigliabile per i carichi di lavoro di produzione. Alcune funzionalità potrebbero non essere supportate o potrebbero avere funzionalità limitate. Per ulteriori informazioni, vedere Condizioni supplementari per l'uso delle versioni di anteprima di Microsoft Azure.

Usare azd ai agent init per eseguire lo scaffolding di un progetto agente ospitato con i file necessari per compilare, testare e distribuire un agente di intelligenza artificiale in Microsoft Foundry. In questo articolo si sceglie un punto di partenza e si inizializza il progetto da un modello, dal proprio codice o rispetto a un progetto Foundry esistente.

Se si usa un agente di codifica come GitHub Copilot, la competenza Microsoft Foundry consente di scegliere un modello iniziale, eseguire lo scaffolding del progetto e interpretare la configurazione generataazd.

Prerequisiti

Scegliere un punto di partenza

Esistono tre modi per iniziare un progetto. Selezionare il percorso corrispondente alla situazione.

Consideration Inizia da un modello Usare un codice personalizzato Connettere un progetto esistente
Ideale per Nuovi agenti, apprendimento degli strumenti. Codice agente esistente che si vuole ospitare in Foundry. Agenti già in esecuzione in un progetto Foundry.
Comando azd ai agent init in una directory vuota. azd ai agent init in una cartella contenente codice esistente. azd ai agent init, quindi selezionare un progetto esistente.
Cosa ottieni Un progetto completo con scaffolding: un solo azure.yaml, il codice sorgente dell'agente in src/<agent-name>/ e un Dockerfile per la distribuzione in container. L'infrastruttura è senza Bicep per impostazione predefinita e può essere rimossa in un secondo momento. Una voce di servizio generata azure.yaml e, per la distribuzione in container, un Dockerfile che incapsula il codice. L'infrastruttura è senza Bicep per impostazione predefinita e può essere rimossa in un secondo momento. Un azure.yaml collegato al progetto Foundry esistente. L'infrastruttura è senza Bicep per impostazione predefinita e può essere rimossa in un secondo momento.
Modifiche al codice Nessuno. Pronte per l’esecuzione. Potrebbe essere necessario un adattatore di protocollo. Nessuno.

Inizializzare da un modello

Esegui la procedura guidata interattiva in una directory vuota e seleziona Inizia da un modello:

azd ai agent init

La procedura guidata offre all'utente le scelte seguenti.

Prompt Descrizione
Modello di agente Scegliere tra modelli organizzati per framework e linguaggio (Python o .NET).
Sottoscrizione di Azure Sottoscrizione utilizzata per trovare o creare un progetto Foundry.
Progetto Fonderia Selezionare un progetto esistente o crearne uno nuovo. Se ne crei uno, scegli anche un'area.
Implementazione del modello Selezionare una distribuzione del modello esistente oppure crearne una dalle impostazioni predefinite del modello.

Il nome dell'agente deriva dal modello. L'interfaccia della riga di comando crea un azd ambiente denominato <directory>-dev e lo configura con i dettagli del progetto Foundry selezionato. Ogni modello include il codice sorgente dell'agente, un Dockerfilee un azure.yaml file che funge da manifesto del progetto unificato per il progetto e la azd configurazione dell'agente ospitato.

Inizializzare da un URL di Azure.yaml

Se si ha un esempio specifico di agente, indirizzare -m al azure.yaml dell'esempio. Il CLI utilizza quel file come manifest del progetto e scarica il codice sorgente dell'agente a cui fa riferimento.

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

Note

I manifesti dell'agente (agent.manifest.yaml) e le definizioni degli agenti autonomi (agent.yaml) sono deprecati. A partire dalle estensioni Foundry azd (azure.ai.agents 1.0.0-beta.1), tutta la configurazione dell'agente ospitato si trova in un singolo oggetto azure.yaml. Vedere Creare Azure.yaml per gli agenti ospitati

L'opzione -m accetta ancora un URL manifesto dell'agente legacy, ma gli esempi correnti pubblicano un oggetto unificato azure.yaml.

Specificare un modello

Scegli un modello all'inizializzazione:

azd ai agent init --model gpt-4.1

In alternativa, usare una distribuzione di modelli esistente nel progetto Foundry:

azd ai agent init --model-deployment my-deployment

Scegliere una modalità di distribuzione

Per impostazione predefinita, azd ai agent init usa la distribuzione del codice per i progetti Python e .NET. La distribuzione del codice carica il codice sorgente in un pacchetto ZIP. Per creare invece lo scaffolding di un progetto basato su container, specifica --deploy-mode container:

azd ai agent init --deploy-mode container

Per distribuire un'immagine container precompilata, specificare --image e --agent-name. Questa opzione salta la selezione del template e della lingua, lo scaffolding del codice, la generazione del Dockerfile e la configurazione di Registro Azure Container.

azd ai agent init --agent-name my-agent --image myregistry.azurecr.io/my-agent:v1

Esplorare i modelli in modo non interattivo

Per esaminare il catalogo prima di eseguire lo scaffolding oppure per eseguire azd ai agent init da uno script, elencare il catalogo:

# Everything in the catalog
azd ai agent sample list

# Just the featured Python agent samples
azd ai agent sample list --featured-only --language python --type agent

# Full azd templates only, as JSON for scripting
azd ai agent sample list --type azd --output json

Ogni voce include un comando initCommand pronto per l'esecuzione, che è possibile copiare ed eseguire nella directory in cui si desidera effettuare la scaffolding.

Tip

Quando si riutilizza un esempio con un'altra identità dell'agente Foundry, passare --agent-name <new-name> su azd ai agent init in modo che il nome scritto in azure.yaml non entri in conflitto con il nome predefinito dell'esempio.

Inizializza dal codice esistente

Se disponi già di codice dell'agente Python o .NET, esegui azd ai agent init all'interno della directory che contiene già il codice:

cd my-agent/
azd ai agent init

La CLI rileva i file esistenti e genera una azure.yaml voce di servizio attorno a essi senza sovrascrivere il tuo codice. Per la distribuzione di contenitori, aggiunge anche un Dockerfile. Per impostazione predefinita, l'infrastruttura rimane senza Bicep, a meno che non si esporti successivamente l'infrastruttura come codice.

Il codice dell'agente deve soddisfare il contratto di runtime dell'agente ospitato:

  • Ascolta sulla porta 8088.
  • Esporre una probe di integrità in GET /readiness.
  • Gestire uno dei protocolli supportati (responses o invocations).

Se il tuo codice non supporta già uno di questi protocolli, aggiungi un adattatore di protocollo, un wrapper SDK leggero che traduce tra il protocollo Foundry e la logica del tuo agente.

Per aggiungere un agente a un progetto esistente azd , init rileva il progetto e aggiunge una nuova voce di servizio all'oggetto esistente azure.yaml. Usare --src per specificare una sottodirectory:

azd ai agent init --src src/my-agent

Connettersi a un progetto Foundry esistente

Per gestire un progetto Foundry esistente tramite azd, eseguire la procedura guidata e selezionare l'opzione per connettersi a un progetto esistente. È anche possibile ignorare la selezione interattiva specificando direttamente l'ID risorsa Azure del progetto:

azd ai agent init --project-id /subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.CognitiveServices/accounts/{account}/projects/{project}

Per trovare l'ID del progetto, apri il portale Foundry, vai a Gestisci>Dettagli progetto e copia il valore di ID risorsa.

Avvertimento

Quando si inizializza su un progetto esistente con --project-id, gli strumenti ignorano le assegnazioni di ruolo automatiche eseguite quando crea un nuovo progetto. Assicurarsi che i ruoli richiesti siano già assegnati. Per la matrice completa, vedi Riferimento delle autorizzazioni dell'agente ospitato.

Esaminare gli elementi creati

Una volta completato init, la cartella del progetto presenta la seguente struttura:

.
|-- azure.yaml                  # Unified azd project and hosted agent configuration
|-- src/
|   \-- <agent-name>/
|       |-- Dockerfile          # Container build definition
|       \-- ...                 # Agent source code
|-- .azure/                     # Environment configuration
\-- infra/                      # Optional IaC, created only after you eject infrastructure

I modelli e gli esempi pubblicano un oggetto unificato azure.yaml nella radice del progetto. Durante l'init, azd adotta o genera tale file. D'ora in poi, lavori con azure.yaml. L'infrastruttura non usa Bicep per impostazione predefinita. Esporta l'infrastruttura solo quando devi gestire direttamente i file IaC generati.

Contenuti correlati

  • Last updated on