Festlegen des Kontexts des Foundry-Projekts für azd-Befehle

Important

Die in diesem Artikel markierten Elemente (Vorschau) sind aktuell als öffentliche Vorschau verfügbar. Diese Vorschauversion wird ohne Vereinbarung zum Servicelevel bereitgestellt und sollte nicht für Produktionsworkloads verwendet werden. Manche Features werden möglicherweise nicht unterstützt oder sind nur eingeschränkt verwendbar. Weitere Informationen finden Sie unter Supplementale Nutzungsbedingungen für Microsoft Azure Previews.

Die Befehle azd ai werden in zwei Kontexten ausgeführt: innerhalb eines azd-Projekts (der typische Arbeitsablauf im Team) und eigenständig (Ad-hoc-Arbeit, einmalige Skripte oder Aufrufe durch Automatisierung, für die kein azure.yaml als Anker vorhanden ist). Beide Modi zielen auf die gleichen Microsoft Foundry-Ressourcen ab. Sie unterscheiden sich nur darin, wie die CLI bestimmt, mit welchem Foundry-Projekt gesprochen werden soll. In diesem Artikel erfahren Sie mehr über die Auflösungsreihenfolge und das Festlegen des eigenständigen Kontexts.

Voraussetzungen

Wann jeder Kontext verwendet werden soll

Kontext Wie es aussieht Verwenden Sie, wenn
In einem azd Projekt Sie führen azd ai ... aus einem Verzeichnis aus, das azure.yaml und eine aktive azd-Umgebung enthält. Sie erstellen oder betreiben einen Agent als Teil eines nachverfolgten Projekts und möchten, dass die Umgebung steuern soll, auf welches Foundry-Projekt Sie abzielen.
Eigenständig Sie führen azd ai ... aus einem beliebigen anderen Verzeichnis aus. Sie führen Ad-hoc-Arbeiten für ein vorhandenes Foundry-Projekt aus, oder Sie erstellen Skripts für einmalige Vorgänge aus einer Automatisierung, die nicht über ein azd-Projekt verfügt.

Die Ressourcenbefehle (azd ai connection, azd ai toolbox, azd ai skillund azd ai routine) werden für ein einzelnes Foundry-Projekt ausgeführt, sodass ein Projektendpunkt aus einem dieser Kontexte aufgelöst werden muss, bevor sie ausgeführt werden können.

Die Befehle azd ai agent (wie z. B. run, invoke und optimize) sind nicht eigenständig verwendbar. Sie erfordern ein azd-Projekt für azure.yaml und die Umgebungsauflösung. Verwenden Sie --agent-endpoint in azd ai agent invoke, um einen bereitgestellten Agenten ohne ein azd-Projekt auf dem Datenträger aufzurufen.

Funktionsweise der Endpunktauflösung

Für jeden Befehl, der auf ein Foundry-Projekt abzielt, löst die CLI den Endpunkt in dieser Reihenfolge auf. Die erste Quelle, die einen Wert zurückgibt, gewinnt, und spätere Quellen werden nicht konsultiert:

  1. Das Flag -p oder --project-endpoint im Befehl. Gewinnt immer, unabhängig vom Kontext.
  2. Die aktive azd Umgebung, wenn Sie sich in einem azd Projektverzeichnis befinden.
  3. Globale Konfiguration, unter extensions.ai-agents.context.endpoint in ~/.azd/config.json. Dies ist das, was azd ai project set schreibt.
  4. Die FOUNDRY_PROJECT_ENDPOINT Umgebungsvariable in der aktuellen Shell.
  5. Fehler. Die CLI wird mit einer strukturierten Empfehlung beendet, azd ai project set auszuführen oder --project-endpoint zu übergeben.

Der Endpunkt ist das einzige, was die CLI benötigt. Die Azure Resource Manager-Ressourcen-ID (Abonnement, Ressourcengruppe, Konto und Projekt) wird zum Zeitpunkt des Aufrufs über den Endpunkt aufgelöst, sodass Befehle unabhängig davon, ob sie den Endpunkt aus Ihrer Umgebung oder Ihrer globalen Konfiguration erhalten haben, auf die gleiche Weise funktionieren.

Festlegen des eigenständigen Kontexts

Der azd ai project set-Befehl schreibt den Endpunkt des aktiven Foundry-Projekts in Ihre globale azd-Konfiguration, sodass nachfolgende Befehle, die von überall aus ausgeführt werden, --project-endpoint weglassen können. Der Befehl übernimmt den Endpunkt als Positionsargument:

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

Der Befehl läuft vollständig ohne Interaktion, wenn Sie den Endpunkt angeben. Fügen Sie --no-prompt in Skripten und in der CI hinzu, damit ein fehlender oder nicht aufgelöster Wert sofort fehlschlägt, statt zu blockieren:

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

Note

Nur der Endpunkt ist kanonisch. Ressourcenbefehle leiten das Abonnement, die Ressourcengruppe, das Konto und das Projekt beim Aufruf erneut aus dem Endpunkt ab.

Löschen des eigenständigen Kontexts

azd ai project unset

Dieser Befehl entfernt den gesamten context-Block aus ~/.azd/config.json. Es verändert keine azd Werte von Umgebungsvariablen.

Aktiven Kontext prüfen

Der azd ai project show Befehl durchläuft die vollständige Auflösungskette und meldet, welche Quelle den aktiven Endpunkt bereitgestellt hat. Verwenden Sie sie, um zu bestätigen, auf welche Ziele Ihr nächster Befehl ausgerichtet ist, bevor Sie ihn ausführen:

azd ai project show

Beispielausgabe, wenn der Endpunkt aus der globalen Konfiguration stammt:

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

Innerhalb eines azd Projekts liest die Source Zeile stattdessen azd env <env-name> , und die angezeigten Werte stammen aus der Datei der Umgebung .env und nicht aus der globalen Konfiguration.

Speicherort

Der eigenständige Kontext befindet sich unter dem extensions.ai-agents Namespace 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"
      }
    }
  }
}

Nur endpoint ist kanonisch. Die anderen Felder dienen dazu, azd ai project show lesbar zu machen. Die CLI liest sie beim Auflösen eines Ziels nie. Sie können die Datei manuell bearbeiten, aber azd ai project set und azd ai project unset sind die unterstützte Methode, sie zu verwalten.

Priorität innerhalb eines azd-Projekts

Innerhalb eines azd-Projekts hat der Projektendpunkt der aktiven Umgebung immer Vorrang vor dem globalen Kontext. Die Ausführung azd ai project set innerhalb eines Projekts aktualisiert weiterhin die globale Konfiguration, aber die CLI gibt eine einzeilige Warnung aus, dass die Umgebung weiterhin Vorrang für Befehle hat, die aus diesem Verzeichnis ausgeführt werden.

Dieses Verhalten ist beabsichtigt. Umgebungswerte auf Projektebene sind Teil des Workflows des Teams, während der globale Kontext eine Einstellung pro Computer ist. Um die Umgebung für einen einzelnen Befehl innerhalb eines Projekts außer Kraft zu setzen, übergeben Sie --project-endpoint, oder setzen Sie FOUNDRY_PROJECT_ENDPOINT in der Shell, anstatt sich auf die globale Konfiguration zu verlassen.

Verwandte Inhalte

  • Last updated on