Konfigurera miljövariabler för en värdbaserad agent

Konfigurera miljövariabler för din värdbaserade agent genom att definiera var värden hör hemma i azure.yaml, vad Microsoft Foundry-plattformen tillhandahåller automatiskt och hur azd-miljöintegrering fungerar. Du får också lära dig hur du lägger till anpassade variabler och hanterar lokala utvecklingshemligheter.

Note

Agentmanifest (agent.manifest.yaml) och fristående agentdefinitioner (agent.yaml) är inaktuella. Från och med Foundry-tilläggen azd (azure.ai.agents 1.0.0-beta.1) finns alla värdbaserade agentkonfigurationer i en enda azure.yaml. Se Skapa azure.yaml för värdbaserade agenter.

Förutsättningar

  • Ett initierat värdbaserat agentprojekt med en azure.yaml fil. Information om hur du skapar eller uppdaterar ett projekt finns i Skapa azure.yaml för värdbaserade agenter.
  • azd Foundry-tilläggen har installerats. Installationssteg finns i Installera azd Foundry-tilläggen.
  • En autentiserad CLI-session för Azure utvecklare. Kör azd auth login om det behövs.
  • En aktiv azd-miljö. Välj eller skapa en med azd env select eller azd env new.

Definiera miljövariabler i azure.yaml

Definiera miljövariabler i env kartan över azure.ai.agent tjänsten i projektet azure.yaml, inte i Dockerfile. Den här metoden håller containeravbildningen portabel och gör att du kan ändra konfigurationen utan att återskapa den.

services:
  my-agent:
    host: azure.ai.agent
    project: src/my-agent
    kind: hosted
    env:
      AZURE_AI_MODEL_DEPLOYMENT_NAME: ${AZURE_AI_MODEL_DEPLOYMENT_NAME}
      MY_CUSTOM_VAR: ${MY_CUSTOM_VAR}

Använd syntaxen ${VAR_NAME} för att referera till azd-miljövariabler. Plattformen löser dessa variabler vid distributionstillfället från .azure/<env>/.env.

Note

Varför inte Dockerfile? Värden som bakas in i en Dockerfile korrigeras vid avbildningens byggtid och visas för alla som har åtkomst till avbildningen. Med hjälp av azure.yaml kan du ändra värden per miljö och hålla hemligheter borta från bildskiktet.

Viktigt

Deklarera inte FOUNDRY_PROJECT_ENDPOINT på kartan azure.yamlenv . Plattformen matar in den automatiskt i värdbaserade containrar och azd ai agent run anger den för lokal utveckling från den aktiva azd env. Att deklarera det explicit är redundant och riskerar att skugga det plattformshanterade värdet.

Ange azd-miljövariabler

  1. Lägg till eller ändra en variabel i din aktuella azd-miljö:

    azd env set MY_CUSTOM_VAR=my-value

  2. Visa alla aktuella värden:

    azd env get-values

    Dessa värden lagras i .azure/<env-name>/.env och ersätts i din azure.yaml vid driftsättning.

Granska plattformsmiljövariabler

Foundry-plattformen matar automatiskt in följande miljövariabler i varje värdbaserad agentcontainer vid start. Dessa variabler är skrivskyddade. Din agentkod bör använda dem men aldrig åsidosätta dem.

Foundry-variabler

Variable Description
FOUNDRY_HOSTING_ENVIRONMENT Plattformen matar in ett icke-giltigt värde när du är värd i Foundry. Sök efter den här variabeln för att avgöra om containern körs i en Foundry-kontext.
FOUNDRY_AGENT_NAME Agentens namn, till exempel my-weather-agent.
FOUNDRY_AGENT_ID ID på agenten.
FOUNDRY_AGENT_VERSION Agentens version.
FOUNDRY_PROJECT_ENDPOINT Slutpunkt för Foundry-projekt, till exempel https://{account}.services.ai.azure.com/api/projects/{project}.
FOUNDRY_AGENT_SESSION_ID Agentens sessions-ID.
FOUNDRY_PROJECT_ARM_ID Projektets fullständiga ARM-resurs-ID.
FOUNDRY_HOSTING_ENVIRONMENT Ange till 1 när agenten distribueras i Foundry. Använd det här värdet för att avgöra om agenten körs i Foundry eller någon annan miljö, till exempel en lokal miljö.

Note

Reserverat prefix: Plattformen reserverar alla AGENT_*FOUNDRY_* och miljövariabler för plattformsanvändning och matar automatiskt in dem i containern.

Vid lokal utveckling med azd ai agent run anger azd FOUNDRY_PROJECT_ENDPOINT automatiskt från din azd-miljö, så att agentkoden fungerar på samma sätt lokalt och när den distribueras.

Nätverksvariabler

Variable Standardinställning Description
PORT 8088 Port för HTTP-lyssning. Ange endast när plattformen kräver en port som inte är standard.
SSE_KEEPALIVE_INTERVAL Inaktiverad SSE keep-alive-kommentarintervall i sekunder.

Observerbarhetsvariabler

Variable Description
APPLICATIONINSIGHTS_CONNECTION_STRING Azure Monitor-anslutningssträng för export av telemetri.
OTEL_EXPORTER_OTLP_ENDPOINT OTLP-slutpunkt för OpenTelemetry-insamlaren.

Variabler för sessionsfil

Variable Standardinställning Description
HOME /home/session Filsystemsökväg till bevarade sessionsdata.

Lägga till en ny miljövariabel

  1. Definiera variabeln i env kartan för azure.ai.agent tjänsten i azure.yaml.

    services:
  my-agent:
    host: azure.ai.agent
    environmentVariables:
      MY_API_URL: ${MY_API_URL}

  2. Ange värdet i din azd-miljö.

    azd env set MY_API_URL=https://api.example.com

  3. Driftsätt om applikationen.

    azd deploy

För lokal utveckling hämtar azd ai agent run även ${VAR} från azd-miljön, så samma konfiguration fungerar lokalt.

Hantera känsliga värden

För hemligheter som API-nycklar och token ska du inte baka värden i din bild eller checka in dem på azure.yaml. Lagra hemligheter i en Foundry-projektanslutning och referera till anslutningsvärden från konfigurationen när plattformen stöder den anslutningstypen.

Använda hemligheter under lokal utveckling

För lokala körningar med azd ai agent run anger du värdena som miljövariablerna azd och refererar till dem i azure.yaml. azd lagrar miljövärden i .azure/<env>/.env, som är gitignored som standard, så att de inte har någon källkontroll.

azd env set OPENAI_KEY <value>

services:
  my-agent:
    host: azure.ai.agent
    env:
      OPENAI_KEY: ${OPENAI_KEY}

För hemligheter som inte ska finnas i en lokal .env fil lagrar du dem i en Foundry-projektanslutning och refererar till dem med en ${{connections.<name>.credentials.<field>}} platshållare. Plattformen löser platshållaren vid körning. Se Kör en värdbaserad agent lokalt med cli:et Azure Developer för det lokala körningsarbetsflödet.

Relaterat innehåll

  • Uppdaterades senast