Ange foundry-projektkontexten för azd-kommandon

Kommandona azd ai körs i två kontexter: i ett azd projekt (det typiska teamarbetsflödet) och fristående (ad hoc-arbete, engångsskript eller anrop från automatisering som inte har något azure.yaml att förankra på). Båda lägena är inriktade på samma Microsoft Foundry-resurser. De skiljer sig bara åt i hur CLI avgör vilket Foundry-projekt som ska kommunicera med. I den här artikeln får du lära dig lösningsordningen och hur du ställer in den fristående kontexten.

Förutsättningar

• Azure Developer CLI Foundry-tilläggen installerades.
• En autentiserad Azure session (azd auth login).
• En befintlig Slutpunkt för Foundry-projekt för fristående användning.

När du ska använda varje kontext

Resurskommandona (azd ai connection, azd ai toolbox, azd ai skilloch azd ai routine) fungerar på ett enda Foundry-projekt, så de behöver en projektslutpunkt som löses från någon av dessa kontexter innan de kan köras.

Agentkommandon har olika kontextkrav. Lokal utveckling kräver ett azd-projekt. Använd --agent-endpoint på azd ai agent invoke för anrop utan projekt. azd ai agent monitor <name> --session-id <id> fungerar även utanför ett projekt med en global projektkontext. Utvärderings- och optimeringskommandon stöder explicita agentnamn och --project-endpoint; kontrollera hjälpen för det enskilda kommandot.

Så här fungerar slutpunktsupplösning

Kärnprojektet, agenten, anslutningen, verktygslådan, kompetensen och rutinresolveraren använder följande källor. Enskilda kommandon exponerar olika väljare; valfria modell- och finjusteringstillägg har egna konfigurationskommandon.

1. Flaggan --project-endpoint, på de kommandon som har den. Kortformen -p är kommandospecifik; till exempel betyder den --protocol på agent invoke.
2. FOUNDRY_PROJECT_ENDPOINT från den aktiva azd miljön. Det sparade värdet gäller. Om nyckeln saknas kan azd-hosten returnera skalvärdet i det här skedet.
3. Global konfiguration, under extensions.ai-projects.context.endpoint i ~/.azd/config.json. Det här är vad azd ai project set skriver.
4. Miljövariabeln FOUNDRY_PROJECT_ENDPOINT i det aktuella skalet.
5. Fel. CLI avslutas med ett strukturerat förslag om att köra azd ai project set eller skicka --project-endpoint.

Ett uttryckligen tomt beständigt miljövärde förhindrar återfall till skalet i miljöfasen. Om ingen slutpunkt upplöses där, kontrollerar CLI fortfarande global konfiguration och sedan shellvariabeln. Ogiltiga värden för slutpunkter ger ett valideringsfel i stället för att falla igenom.

azd ai project show använder den miljö som valts av azd env select; dess sökning efter slutpunkt använder inte --environment som ett åsidosättande värde. Använd azd env select <name> innan du inspekterar en annan miljö.

Ange den fristående kontexten

Kommandot azd ai project set skriver ändpunkten för det aktiva Foundry-projektet till din globala azd-konfiguration, så att efterföljande kommandon som körs var som helst kan utelämna --project-endpoint. Kommandot tar slutpunkten som ett positionsargument:

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

Kommandot körs helt utan användarinteraktion när du anger ändpunkten. Lägg till --no-prompt i skript och CI så att det snabbt uppstår ett fel om ett värde saknas eller inte kan lösas, i stället för att blockera:

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

Rensa den fristående kontexten

azd ai project unset

Det här kommandot rensar projektkontexten från global konfiguration, inklusive den äldre agent-projektkontexten när den finns. Det berör inte några azd miljövärden. Att köra den när ingen kontext är angiven lyckas.

Granska den aktiva kontexten

Kommandot azd ai project show vägleder hela lösningskedjan och rapporterar vilken källa som tillhandahöll den aktiva slutpunkten. Använd den för att bekräfta vad nästa kommando har som mål innan du kör det:

azd ai project show

Exempelutdata när slutpunkten kommer från global konfiguration:

Project endpoint:  https://my-project.services.ai.azure.com/api/projects/my-project
Source:            global config (~/.azd/config.json)
Set at:            <timestamp-recorded-by-project-set>

Utdata innehåller ändpunkten, källan och, för global konfiguration, tidpunkten då den angavs. Den rapporterar inte tenant- eller prenumerationsinformation. I ett azd projekt visas azd env (<env-name>) en endpoint från miljön. Använd --output json för strukturerad utdata.

Lagringsplats

Den fristående kontexten extensions.ai-projects finns under namnområdet i ~/.azd/config.json:

{
  "extensions": {
    "ai-projects": {
      "context": {
        "endpoint": "https://my-project.services.ai.azure.com/api/projects/my-project",
        "setAt": "2026-01-15T10:23:00Z"
      }
    }
  }
}

Kontexten lagrar endpoint och setAt. Projekttillägget kan migrera den äldre extensions.ai-agents.project.context posten. Använd azd ai project set och azd ai project unset för att hantera kontexten.

Prioritetsordning i ett azd-projekt

I ett azd-projekt har en icke-tom ändpunkt som hämtas från den aktiva miljön företräde framför den globala kontexten. Om du kör azd ai project set inifrån ett projekt uppdateras den globala konfigurationen, inte den aktiva miljön.

Miljövärden på projektnivå är en del av teamets arbetsflöde, medan global kontext är en inställning per dator. Om du vill åsidosätta körmiljön för ett enda resurskommando anger du --project-endpoint där detta stöds. Om du anger en skalvariabel åsidosätts inte ett beständigt miljövärde.

Konfigurera ett projekt för provisionering

project set väljer en global ändpunkt; den deklarerar inte infrastruktur. Använd project add för att lägga till eller uppdatera azure.ai.project tjänsten i azure.yaml:

azd ai project add --project-id "<project-resource-id>"

Du kan också använda --project-endpoint <endpoint> för en referens endast för slutpunkter eller --new-project för att konfigurera ett nytt projekt. --project-id registrerar både slutpunkten och AZURE_AI_PROJECT_ID; en referens som endast gäller slutpunkten registrerar inte något ARM-resurs-ID. Använd --force för att ersätta ett annat konfigurerat projekt.

Lägg till en driftsättning för en hanterad modell

Innan du exporterar infrastrukturen lägger du till en modelldriftsättning i projektets infogade deklaration:

azd ai project deployment add --model OpenAI/gpt-4.1 --name chat
azd provision

Använd --version, --sku, --capacityoch --location för att välja distributionsinställningar. --force tillåter att ersätta en konflikterande infogad deklaration. Kommandot add ändrar deklarationen, azd provision tillämpar den.

Om du vill ta över ägarskapet för infrastrukturfiler använder du azd ai project add --infra=bicep eller --infra=terraform. Utan befintlig programinfrastruktur är utmatning standardvärdet infra. När du bevarar befintlig programinfrastruktur läggs ett Foundry-lager till under infra/foundry. Befintliga lagerkonfigurationer behåller sina deklarerade sökvägar.

Granska konfigurationen av det lokala projektet

Använd azd ai project context för att granska azd-projekt- och miljökontexten. Till skillnad från project show, som rapporterar slutpunktsupplösning, kan kontextutdata innehålla miljövärden och hemligheter. Dela den inte eller checka in .azure i versionshanteringen.

Relaterat innehåll

• Snabbstart: Distribuera din första värdbaserade agent
• Installera CLI Foundry-tilläggen för Azure Developer
• Initiera ett värdbaserat agentprojekt med CLI för Azure Developer
• Optimera en befintlig agent utan AZD-projektfiler