De context van het Foundry-project instellen voor azd-opdrachten

Important

Items die in dit artikel zijn gemarkeerd (preview) zijn momenteel beschikbaar als openbare preview. Deze preview wordt aangeboden zonder een service level agreement en we raden deze niet aan voor productieworkloads. Bepaalde functies worden mogelijk niet ondersteund of hebben mogelijk beperkte mogelijkheden. Zie Aanvullende gebruiksvoorwaarden voor Microsoft Azure Previews voor meer informatie.

De azd ai opdrachten worden uitgevoerd in twee contexten: binnen een azd project (de typische teamwerkstroom) en zelfstandig (ad-hocwerk, eenmalige scripts of aanroepen van automatisering waarvoor geen azure.yaml anker is ingeschakeld). Beide modi richten zich op dezelfde Microsoft Foundry-resources. Ze verschillen alleen in de wijze waarop de CLI bepaalt met welk Foundry-project moet worden gesproken. In dit artikel leert u de oplossingsvolgorde en hoe u de zelfstandige context instelt.

Prerequisites

Wanneer gebruikt u elke context?

Context Hoe ziet het eruit Wanneer gebruiken
In een azd project U voert azd ai ... uit vanuit een map die azure.yaml en een actieve azd-omgeving bevat. U ontwikkelt of beheert een agent als onderdeel van een geregistreerd project en wilt dat de omgeving bepaalt op welk Foundry-project u zich richt.
Zelfstandig U voert azd ai ... uit vanuit elke andere map. U voert ad-hocwerkzaamheden uit op een bestaand Foundry-project, of u script eenmalige taken vanuit automatisering die geen azd-project beheert.

De resourceopdrachten (azd ai connection, azd ai toolbox, azd ai skillen azd ai routine) werken op één Foundry-project, zodat ze een projecteindpunt nodig hebben dat is opgelost vanuit een van deze contexten voordat ze kunnen worden uitgevoerd.

Voor sommige azd ai agent opdrachten is een azd project vereist omdat ze werken op lokale servicedefinities. Andere opdrachten ondersteunen zelfstandig gebruik. U kunt bijvoorbeeld azd ai agent optimize op een bestaande geïmplementeerde agent richten als u de naam ervan opgeeft en het Foundry-projecteindpunt bepaalt op basis van globale configuratie, een expliciete vlag of een omgevingsvariabele. Gebruik --agent-endpoint op azd ai agent invoke om een gedeployde agent aan te roepen zonder een azd-project op schijf.

Hoe eindpuntresolutie werkt

Voor elke opdracht die is gericht op een Foundry-project, bepaalt de CLI het eindpunt in deze volgorde. De eerste bron die een waarde retourneert, krijgt voorrang en latere bronnen worden niet geraadpleegd:

  1. De -p of --project-endpoint flag bij de opdracht. Wint altijd, ongeacht context.
  2. De actieve azd-omgeving, als u zich in de map van een azd-project bevindt.
  3. Algemene configuratie, onder extensions.ai-agents.context.endpoint in ~/.azd/config.json. Dit is wat azd ai project set schrijft.
  4. De FOUNDRY_PROJECT_ENDPOINT omgevingsvariabele in de huidige shell.
  5. Fout. De CLI wordt afgesloten met een gestructureerde suggestie om uit te voeren azd ai project set of door te geven --project-endpoint.

Het eindpunt is het enige wat de CLI nodig heeft. Hiermee wordt de Azure Resource Manager-resource-ID (abonnement, resourcegroep, account en project) op het moment van aanroepen bepaald op basis van het eindpunt, zodat opdrachten op dezelfde manier werken, ongeacht of ze het eindpunt uit uw omgeving of uw globale configuratie hebben verkregen.

De onafhankelijke context instellen

Met de opdracht azd ai project set wordt het endpoint van het actieve Foundry-project weggeschreven naar je globale azd-configuratie, zodat je bij volgende opdrachten die je vanaf elke locatie uitvoert --project-endpoint kunt weglaten. De opdracht neemt het eindpunt als een positioneel argument:

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

De opdracht is volledig niet-interactief als u het endpoint meegeeft. Voeg --no-prompt toe in scripts en CI, zodat een ontbrekende of onopgeloste waarde direct faalt in plaats van te blokkeren:

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

Opmerking

Alleen het eindpunt is canoniek. Resourceopdrachten leiden het abonnement, de resourcegroep, het account en het project opnieuw af van het eindpunt tijdens het aanroepen.

De afzonderlijke context wissen

azd ai project unset

Met deze opdracht wordt het hele context blok verwijderd uit ~/.azd/config.json. Er worden geen omgevingswaarden azd aangeraakt.

De actieve context controleren

De azd ai project show-opdracht doorloopt de volledige resolutieketen en rapporteert welke bron het actieve eindpunt levert. Gebruik het om te controleren waarop uw volgende opdracht gericht is voordat u deze uitvoert:

azd ai project show

Voorbeelduitvoer wanneer het eindpunt afkomstig is van globale configuratie:

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

Binnen een azd-project wordt in plaats daarvan de Source-regel azd env <env-name> gebruikt, en de weergegeven waarden zijn afkomstig uit het .env-bestand van de omgeving in plaats van uit de globale configuratie.

Opslaglocatie

De zelfstandige context bevindt zich onder de extensions.ai-agents naamruimte 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"
      }
    }
  }
}

Alleen endpoint is de canonieke versie. De andere velden bestaan om leesbaar te maken azd ai project show . De CLI leest ze nooit bij het oplossen van een doel. U kunt het bestand handmatig bewerken, maar azd ai project set en azd ai project unset zijn de ondersteunde manier om het te beheren.

Voorrang binnen een azd-project

Binnen een azd project wint het projecteindpunt van de actieve omgeving altijd over de globale context. Het uitvoeren azd ai project set vanuit een project werkt nog steeds globale configuratie bij, maar de CLI drukt een waarschuwing van één regel af dat de omgeving prioriteit blijft krijgen voor opdrachten die vanuit die map worden uitgevoerd.

Dit gedrag is opzettelijk. Omgevingswaarden op projectniveau maken deel uit van de workflow van het team, terwijl de globale context een instelling per machine is. Als u de omgeving voor één commando binnen een project wilt overschrijven, geeft u --project-endpoint door of stelt u FOUNDRY_PROJECT_ENDPOINT in de shell in, in plaats van te vertrouwen op de globale configuratie.

Verwante inhoud

  • Last updated on