Définir le contexte du projet Foundry pour les commandes azd

Les azd ai commandes s’exécutent dans deux contextes : à l’intérieur d’un azd projet (workflow d’équipe classique) et autonome (travail ad hoc, scripts ponctuels ou appels d’automatisation sans azure.yaml ancrage). Les deux modes ciblent les mêmes ressources Microsoft Foundry. Ils diffèrent uniquement par la manière dont l’interface en ligne de commande (CLI) détermine avec quel projet Foundry interagir. Dans cet article, vous allez découvrir l’ordre de résolution et comment définir le contexte autonome.

Prerequisites

• Les extensions Azure Developer CLI Foundry ont été installées.
• Session Azure authentifiée (azd auth login).
• Point de terminaison de projet Foundry existant pour une utilisation autonome.

Quand utiliser chaque contexte

Les commandes de ressource (azd ai connection, , azd ai toolboxazd ai skillet azd ai routine) fonctionnent sur un projet Foundry unique. Ils ont donc besoin d’un point de terminaison de projet résolu à partir de l’un de ces contextes avant de pouvoir s’exécuter.

Certaines azd ai agent commandes nécessitent un azd projet, car elles fonctionnent sur des définitions de service local. D’autres commandes prennent en charge l’utilisation autonome. Par exemple, azd ai agent optimize vous pouvez cibler un agent déployé existant lorsque vous fournissez son nom et résolvez le point de terminaison du projet Foundry à partir de la configuration globale, d’un indicateur explicite ou d’une variable d’environnement. Utilisez --agent-endpoint sur azd ai agent invoke pour appeler un agent déployé sans projet azd sur le disque.

Fonctionnement de la résolution des points de terminaison

Pour chaque commande qui cible un projet Foundry, l’interface CLI résout le point de terminaison dans cet ordre. La première source qui retourne une valeur gagne, et les sources ultérieures ne sont pas consultées :

1. L’option -p ou --project-endpoint de la commande. Gagne toujours, quel que soit le contexte.
2. L’environnement azd actif, si vous vous trouvez dans un répertoire de projet azd.
3. Configuration globale, sous extensions.ai-agents.context.endpoint dans ~/.azd/config.json. Voici ce que azd ai project set écrit.
4. La variable d’environnement FOUNDRY_PROJECT_ENDPOINT dans le shell actuel.
5. Erreur. L’interface CLI se termine par une suggestion structurée pour exécuter azd ai project set ou passer --project-endpoint.

Le point de terminaison est la seule chose dont l’interface CLI a besoin. Il résout l’ID de ressource Azure Resource Manager (abonnement, groupe de ressources, compte et projet) depuis le point de terminaison au moment de l’invocation, de sorte que les commandes fonctionnent de la même manière, que le point de terminaison provienne de votre environnement ou de votre configuration globale.

Définir le contexte autonome

La commande azd ai project set enregistre l’endpoint du projet Foundry actif dans votre fichier de configuration global azd, de sorte que les commandes suivantes, exécutées depuis n’importe où, puissent omettre --project-endpoint. La commande prend le point de terminaison comme argument positionnel :

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

La commande n’est pas interactive lorsque vous passez le point de terminaison. Ajoutez --no-prompt dans les scripts et la CI afin qu’une valeur manquante ou non résolue provoque immédiatement un échec, plutôt que de bloquer :

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

Supprimer le contexte autonome

azd ai project unset

Cette commande supprime l’intégralité du bloc context de ~/.azd/config.json. Cela ne modifie aucune valeur d’environnement azd.

Examiner le contexte actif

La azd ai project show commande guide la chaîne de résolution complète et signale quelle source a fourni le point de terminaison actif. Utilisez-la pour confirmer les cibles de votre commande suivante avant de l’exécuter :

azd ai project show

Exemple de sortie lorsque le point de terminaison provient de la configuration 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

Dans un projet azd, la ligne Source affiche azd env <env-name> à la place, et les valeurs affichées proviennent du fichier .env de l’environnement plutôt que de la configuration globale.

Emplacement de stockage

Le contexte autonome se situe dans l’espace de noms extensions.ai-agents de ~/.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"
      }
    }
  }
}

Seul endpoint est canonique. Les autres champs existent pour rendre azd ai project show lisibles. L’interface CLI ne les lit jamais lors de la résolution d’une cible. Vous pouvez modifier le fichier manuellement, mais azd ai project setazd ai project unset sont la méthode prise en charge pour la gérer.

Ordre de priorité dans un projet azd

Dans un projet azd, le point de terminaison du projet de l’environnement actif prévaut toujours sur le contexte global. L’exécution azd ai project set à partir d’un projet met toujours à jour la configuration globale, mais l’interface CLI imprime un avertissement d’une ligne indiquant que l’environnement continue à être prioritaire pour les commandes exécutées à partir de ce répertoire.

Ce comportement est intentionnel. Les valeurs d’environnement au niveau du projet font partie du flux de travail de l’équipe, tandis que le contexte global est une préférence propre à chaque machine. Pour redéfinir l’environnement pour une seule commande depuis un projet, transmettez --project-endpoint, ou définissez FOUNDRY_PROJECT_ENDPOINT dans l’interpréteur de commandes, au lieu de vous fier à la configuration globale.

Contenu connexe

• Démarrage rapide : Déployer votre premier agent hébergé
• Installer les extensions Foundry pour Azure Developer CLI
• Initialiser un projet d’agent hébergé avec l’interface CLI Azure développeur
• Optimiser un agent existant sans fichiers projet AZD