Impostare il contesto del progetto Foundry per i comandi azd

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.

I comandi azd ai vengono eseguiti in due contesti: all'interno di un progetto azd (il tipico flusso di lavoro del team) e in modo autonomo (lavoro ad hoc, script una tantum o invocazioni provenienti da processi di automazione che non hanno alcun azure.yaml a cui ancorarsi). Entrambe le modalità hanno come destinazione le stesse risorse Microsoft Foundry. Differiscono solo in che modo l'interfaccia della riga di comando determina il progetto Foundry a cui comunicare. Questo articolo illustra l'ordine di risoluzione e come impostare il contesto autonomo.

Prerequisiti

Quando usare ogni contesto

Contesto Che aspetto ha Usa quando
In un azd progetto Esegui azd ai ... da una directory che contiene azure.yaml e un ambiente azd attivo. Sviluppi o gestisci un agente nell’ambito di un progetto monitorato e vuoi che l’ambiente determini a quale progetto Foundry fare riferimento.
Autonomo Si esegue azd ai ... da un'altra directory. Si svolgono attività ad hoc su un progetto Foundry esistente oppure si creano script per operazioni una tantum tramite un’automazione che non gestisce un progetto azd.

I comandi delle risorse (azd ai connection, azd ai toolbox, azd ai skille azd ai routine) operano su un singolo progetto Foundry, quindi è necessario che un endpoint di progetto venga risolto da uno di questi contesti prima di poter essere eseguiti.

Alcuni azd ai agent comandi richiedono un azd progetto perché operano sulle definizioni del servizio locale. Altri comandi supportano l'uso autonomo. Ad esempio, azd ai agent optimize può puntare a un agente già distribuito quando se ne fornisce il nome e si ricava l'endpoint del progetto Foundry dalla configurazione globale, da un flag esplicito o da una variabile di ambiente. Usare --agent-endpoint su azd ai agent invoke per chiamare un agente distribuito senza un azd progetto su disco.

Come funziona la risoluzione degli endpoint

Per ogni comando che si riferisce a un progetto Foundry, la CLI risolve l'endpoint in questo ordine. La prima origine che restituisce un valore vince e le origini successive non vengono consultate:

  1. Il flag -p o --project-endpoint del comando. Vince sempre, indipendentemente dal contesto.
  2. L'ambiente azd attivo, se all'interno di una directory di progetto azd.
  3. Configurazione globale, sotto extensions.ai-agents.context.endpoint in ~/.azd/config.json. Questo è ciò che azd ai project set scrive.
  4. La variabile di ambiente FOUNDRY_PROJECT_ENDPOINT nella shell corrente.
  5. Errore. L'interfaccia della riga di comando termina con il suggerimento strutturato di eseguire azd ai project set o passare --project-endpoint.

L'endpoint è l'unico elemento di cui la CLI ha bisogno. Risolve l'ID della risorsa di Azure Resource Manager (sottoscrizione, gruppo di risorse, account e progetto) dall'endpoint al momento dell'invocazione, quindi i comandi funzionano allo stesso modo sia che ricavino l'endpoint dal tuo ambiente sia dalla configurazione globale.

Impostare il contesto autonomo

Il comando azd ai project set salva l'endpoint del progetto Foundry attivo nella configurazione globale azd, così che i comandi successivi eseguiti da qualsiasi posizione possano omettere --project-endpoint. Il comando accetta l'endpoint come argomento posizionale:

azd ai project set https://my-project.services.ai.azure.com/api/projects/my-project

Il comando è completamente non interattivo quando si passa l'endpoint. Aggiungi --no-prompt negli script e nella CI in modo che un valore mancante o non risolto fallisca subito invece di bloccarsi:

azd ai project set https://my-project.services.ai.azure.com/api/projects/my-project --no-prompt

Annotazioni

Solo l'endpoint è canonico. I comandi delle risorse ricalcolano la sottoscrizione, il gruppo di risorse, l'account e il progetto dall'endpoint al momento della chiamata.

Cancellare il contesto autonomo

azd ai project unset

Questo comando rimuove l'intero context blocco da ~/.azd/config.json. Non tocca alcun azd valore di ambiente.

Esaminare il contesto attivo

Il comando azd ai project show percorre l'intera catena di risoluzione e indica quale origine ha fornito l'endpoint attivo. Usarlo per confermare le destinazioni del comando successivo prima di eseguirlo:

azd ai project show

Output di esempio quando l'endpoint proviene dalla configurazione globale:

Project endpoint:  https://my-project.services.ai.azure.com/api/projects/my-project
Source:            global config (~/.azd/config.json)
Tenant:            contoso.onmicrosoft.com
Subscription:      Contoso Dev (00000000-0000-0000-0000-000000000000)
Foundry project:   my-project

All'interno di un progetto azd, la riga Source riporta invece azd env <env-name>, e i valori visualizzati provengono dal file .env dell'ambiente anziché dalla configurazione globale.

Posizione di archiviazione

Il contesto autonomo si trova nel namespace extensions.ai-agents in ~/.azd/config.json:

{
  "extensions": {
    "ai-agents": {
      "context": {
        "endpoint": "https://my-project.services.ai.azure.com/api/projects/my-project",
        "subscription": "00000000-0000-0000-0000-000000000000",
        "tenant": "contoso.onmicrosoft.com",
        "foundryProject": "my-project",
        "setAt": "2026-01-15T10:23:00Z"
      }
    }
  }
}

Solo endpoint è canonico. Gli altri campi esistono per rendere azd ai project show leggibili. La CLI non li legge mai durante la risoluzione di un target. È possibile modificare il file a mano, ma azd ai project set e azd ai project unset sono il modo supportato per gestirlo.

Ordine di precedenza all'interno di un progetto azd

All'interno di un progetto azd, l'endpoint del progetto dell'ambiente attivo prevale sempre sul contesto globale. L'esecuzione azd ai project set da un progetto aggiorna ancora la configurazione globale, ma l'interfaccia della riga di comando visualizza un avviso di una riga che indica che l'ambiente continua a avere la precedenza per i comandi eseguiti da tale directory.

Questo comportamento è intenzionale. Le variabili d’ambiente a livello di progetto fanno parte del flusso di lavoro del team, mentre il contesto globale è una preferenza per ciascun computer. Per eseguire l'override dell'ambiente per un singolo comando dall'interno di un progetto, passare --project-endpointo impostare FOUNDRY_PROJECT_ENDPOINT nella shell, anziché basarsi sulla configurazione globale.

Contenuti correlati

  • Last updated on