azure.yaml reference for hosted agents (Dokumentacja pliku azure.yaml dla hostowanych agentów)

Ważna

Elementy oznaczone podglądem w tym artykule są obecnie w wersji zapoznawczej. Ta wersja zapoznawcza jest udostępniana bez umowy dotyczącej poziomu usług, a Microsoft nie zaleca korzystania z niej w przypadku obciążeń produkcyjnych. Niektóre funkcje mogą nie być obsługiwane lub mogą mieć ograniczone możliwości. Aby uzyskać więcej informacji, zobacz Warunki dodatkowe korzystania z testowych wersji Microsoft Azure.

Plik to pojedyncza azure.yaml konfiguracja projektu interfejsu wiersza polecenia dewelopera (azd) Azure dla projektu hostowanego agenta. Deklaruje zasoby rozwiązania Foundry — projekt, wdrożenia modelu, połączenia, przyborniki, umiejętności, procedury i same agenty — jako zestaw usług i informuje azd o tym, jak aprowizować i wdrażać je. Ten ujednolicony plik zastępuje wcześniejszy model dwóch plików, który dzieli konfigurację między agent.manifest.yaml i agent.yaml.

Aby dowiedzieć się, jak utworzyć i utworzyć ten plik krok po kroku, zobacz Tworzenie pliku azure.yaml dla hostowanych agentów.

Jak azd używa pliku azure.yaml

Interfejs wiersza polecenia dewelopera Azure usprawnia przepływ pracy typu deweloper-chmura. Obsługuje ona dwie rzeczy: aprowizowanie zasobów Azure, takich jak projekty foundry, wdrożenia modelu i rejestry kontenerów oraz wdrażanie kodu w tych zasobach. W przypadku hostowanych agentów rozszerzenie dodaje polecenia specyficzne dla agenta, azure.ai.agents takie jak azd ai agent init i azd ai agent run.

Każdy azd projekt ma azure.yaml plik w katalogu głównym. W przypadku projektów agentów ten plik jest źródłem prawdy zarówno dla konfiguracji agenta, jak i konfiguracji wdrożenia.

Environments

Środowisko jest nazwaną konfiguracją, taką jak dev, staginglub prod, która przechowuje ustawienia dla określonego wdrożenia. Każde środowisko śledzi Azure subskrypcji i lokalizacji, grupę zasobów i nazwy zasobów oraz wszelkie ustawione zmienne niestandardowe. Ustawienia są przechowywane lokalnie w programie .azure/<env-name>/.env. Możesz mieć wiele środowisk dla tego samego projektu.

Podstawowe polecenia

Polecenie Do czego służy
azd provision Tworzy Azure zasobów, takich jak projekt Foundry, wdrożenia modelu i rejestr kontenerów.
azd deploy Pakietuje i przekazuje źródło dla kompilacji zdalnej, kompiluje i publikuje obraz kontenera lub wdraża wstępnie utworzony obraz, a następnie tworzy hostowaną wersję agenta.
azd up Łączy provision i deploy w jednym poleceniu.
azd down Usuwa wszystkie zaaprowizowane zasoby.
azd env set Ustawia zmienną środowiskową, na przykład azd env set MICROSOFT_FOUNDRY_MODEL_DEPLOYMENT_NAME=gpt-5.4-mini.

Zgodność rozszerzeń

Rozszerzenie azure.ai.agents udostępnia azure.ai.agent hosta. Rozszerzenie azure.ai.projects udostępnia azure.ai.project hosta i dostawcę microsoft.foundry infrastruktury. Użyj wersji 1.36.0 azd lub nowszej, azure.ai.agents wersji lub nowszej 1.0.0-beta.20 oraz azure.ai.projects wersji lub nowszej 1.0.0-beta.14 . Aby uzyskać instrukcje dotyczące instalacji i uaktualniania, zobacz Instalowanie rozszerzeń interfejsu wiersza polecenia dewelopera Azure Developer Foundry.

Publiczne usługi głosowe w wersji zapoznawczej wymagają interfejsu wiersza polecenia dewelopera Azure w wersji 1.32.0 lub nowszej oraz rozszerzenia agenta, które uwidacznia opcje interfejsu wiersza polecenia głosowego. Poniższe wersje ogólne nie ustanawiają obsługi funkcji głosowych. Sprawdź wymagania wstępne agenta głosowego.

Minimalną zgodną wersję można zadeklarować w pliku azure.yaml:

requiredVersions:
    azd: ">=1.36.0"
    extensions:
        azure.ai.agents: ">=1.0.0-beta.20"
        azure.ai.projects: ">=1.0.0-beta.14"

Cykl życia dostawcy usług

microsoft.foundry Zainstaluj metapakiet, gdy projekt zawiera połączenia, przyborniki, umiejętności lub procedury. Instaluje rozszerzenia dostawcy, które implementują odpowiednie azure.ai.* hosty.

Host usługi Rozszerzenie dostawcy Zastosowane podczas
azure.ai.project azure.ai.projects azd provision
azure.ai.connection azure.ai.connections azd provision
azure.ai.toolbox azure.ai.toolboxes azd deploy
azure.ai.agent azure.ai.agents azd deploy
azure.ai.skill azure.ai.skills azd deploy
azure.ai.routine azure.ai.routines azd deploy

Dostawcy projektu i połączenia stosują konfigurację podczas .azd provision Agenci, przybornik, umiejętności i rutynowi dostawcy stosują konfigurację podczas .azd deploy Uruchom polecenie azd up , aby ukończyć obie fazy. Usunięcie usługi płaszczyzny danych uniemożliwia azure.yamlazd zarządzanie nim; usuń zasób zdalny oddzielnie, gdy nie jest już potrzebny.

  • azd down — Usuwa grupę zasobów, gdy bieżące środowisko utworzyło projekt Foundry. Pozostawia istniejący projekt i jego zasoby. |
  • azd env set - Ustawia zmienną środowiskową, na przykład azd env set FOUNDRY_MODEL_NAME=gpt-5.4-mini. |

Model usługi podzielonej

W obszarze serviceskażdy wpis jest nazwaną usługą z polem host identyfikującym rodzaj zadeklarowanego zasobu znaleziono. Usługi odwołują się do siebie za pośrednictwem uses pola, które tworzy graf zależności, który azd jest rozpoznawany w czasie aprowizacji i wdrażania. Typowy projekt ma jedną azure.ai.project usługę, która jest właścicielem wdrożeń modelu i jednej azure.ai.agent usługi, która jest od niej zależna.

Host Resource Purpose
azure.ai.project Projekt odlewni Jest właścicielem wdrożeń modelu i opcjonalnej sieci prywatnej.
azure.ai.agent Hostowany, monit lub agent głosowy Przenosi definicję agenta oraz jego ustawienia kompilacji i wdrażania.
azure.ai.connection Połączenie projektu Łączy projekt z zasobem zewnętrznym, takim jak serwer MCP lub indeks wyszukiwania.
azure.ai.toolbox Przybornik (zestaw narzędzi znaleziono) Nazwany pakiet narzędzi opartych na połączeniu, do których odwołują się agenci.
azure.ai.skill Kwalifikacje Wytyczne dotyczące zachowania wielokrotnego użytku udostępniane między agentami.
azure.ai.routine Procedura Wyzwalacz oraz akcja, która wywołuje agenta.

Minimalny przykład

# yaml-language-server: $schema=https://raw.githubusercontent.com/Azure/azure-dev/main/schemas/v1.0/azure.yaml.json
name: my-agent-project

services:
    ai-project:
        host: azure.ai.project
        deployments:
            - name: gpt-5.4-mini
              model:
                format: OpenAI
                name: gpt-5.4-mini
                version: "2026-03-17"
              sku:
                name: GlobalStandard
                capacity: 10

    my-agent:
        host: azure.ai.agent
        project: src/my-agent
        language: docker
        uses:
            - ai-project
        kind: hosted
        name: my-agent
        description: A hosted agent built from source.
        protocols:
            - protocol: responses
              version: 2.0.0
        env:
            MICROSOFT_FOUNDRY_MODEL_DEPLOYMENT_NAME: ${MICROSOFT_FOUNDRY_MODEL_DEPLOYMENT_NAME}
            PYTHONNOUSERSITE: "1"
        container:
            resources:
                cpu: "0.25"
                memory: 0.5Gi

Pełny przykład

Poniższy projekt dodaje połączenie, przybornik i sieć prywatną. Przykłady Python ustawione PYTHONNOUSERSITE: "1" w celu wyłączenia ładowania pakietu witryny użytkownika. Aby uzyskać informacje o zgodności zależności i istniejących wdrożeniach, zobacz Konfigurowanie uruchamiania Python.

# yaml-language-server: $schema=https://raw.githubusercontent.com/Azure/azure-dev/main/schemas/v1.0/azure.yaml.json
requiredVersions:
    extensions:
        azure.ai.agents: '>=0.1.0-preview'

name: research-agent-project

services:
    ai-project:
        host: azure.ai.project
        deployments:
            - name: gpt-5.4-mini
              model:
                format: OpenAI
                name: gpt-5.4-mini
                version: "2026-03-17"
              sku:
                name: GlobalStandard
                capacity: 50

    search-conn:
        host: azure.ai.connection
        uses:
            - ai-project
        category: CognitiveSearch
        target: https://my-search.search.windows.net
        authType: ApiKey
        credentials:
            key: ${SEARCH_API_KEY}

    research-tools:
        host: azure.ai.toolbox
        uses:
            - ai-project
            - search-conn
        description: Tools used by the research agent.
        tools:
            - type: azure_ai_search
              connection: search-conn
            - type: code_interpreter

    researcher:
        host: azure.ai.agent
        project: src/researcher
        language: docker
        uses:
            - ai-project
            - search-conn
            - research-tools
        kind: hosted
        name: researcher
        description: Hosted research agent built from source.
        startupCommand: python main.py
        toolboxes:
            - research-tools
        env:
            LOG_LEVEL: info
            PYTHONNOUSERSITE: "1"
        protocols:
            - protocol: responses
              version: 2.0.0
        container:
            resources:
                cpu: "1.0"
                memory: 2Gi

infra:
    provider: bicep
    path: ./infra

Pola najwyższego poziomu

(No changes needed) Wymagane Opis
name Yes nazwa Project.
requiredVersions.extensions No Minimalne ograniczenia wersji rozszerzenia, na przykład azure.ai.agents: '>=0.1.0-preview'.
metadata No Project metadanych, takich jak template identyfikator.
services Yes Mapuj nazwy usług na konfiguracje usług.
infra No Ustawienia infrastruktury jako kodu. Występuje podczas wysuwania IaC.

azure.ai.project service

Usługa projektu aprowizuje projekt foundry lub łączy się z nim i jest właścicielem wdrożeń modelu.

(No changes needed) Opis
host Musi mieć wartość azure.ai.project.
endpoint Adres URL punktu końcowego istniejącego projektu Foundry. Po ustawieniu azd program łączy się z tym projektem zamiast aprowizować nowy. Po pominięciu azd aprowizuje nowy projekt.
deployments Tablica wdrożeń modelu do utworzenia w projekcie.
network Opcjonalna sieć prywatna dla konta, które wspiera projekt.

deployments

(No changes needed) Opis
name Nazwa wdrożenia.
model.format Format modelu, na przykład OpenAI.
model.name Nazwa modelu, na przykład gpt-5.4-mini.
model.version Ciąg wersji modelu.
sku.name Nazwa jednostki SKU, na przykład GlobalStandard, Standardlub GlobalBatch.
sku.capacity Pojemność jednostki SKU w jednostkach tokenów na minutę.

Wpis wdrożenia może być również plikiem zewnętrznym: - $ref: ./deployments/embeddings.yaml.

sieć

Ustaw network wartość na aprowizację konta zabezpieczonego przez sieć. Pole peSubnet jest wymagane i ustanawia prywatny punkt końcowy konta. Dodaj agentSubnet polecenie , aby wstrzyknąć środowisko uruchomieniowe agenta do własnej podsieci (przynieś własną sieć wirtualną) lub pominąć go w celu użycia sieci zarządzanej Microsoft. Aby zapoznać się z pełnym przewodnikiem, zobacz Hostowana sieć prywatna agenta.

Konfiguracja sieci prywatnej

Użyj network polecenia w usłudze azure.ai.project , aby skonfigurować prywatny punkt końcowy konta i ruch wychodzący agenta. W poniższym przykładzie użyto podsieci zarządzanej przez klienta dla środowiska uruchomieniowego agenta:

services:
    ai-project:
        host: azure.ai.project
        network:
            peSubnet:
                vnet: ${VNET_RESOURCE_ID}
                name: private-endpoint-subnet
            agentSubnet:
                vnet: ${VNET_RESOURCE_ID}
                name: agent-subnet
            dns:
                resourceGroup: ${PRIVATE_DNS_RESOURCE_GROUP}
                subscription: ${PRIVATE_DNS_SUBSCRIPTION_ID}
(No changes needed) Wymagane Opis
peSubnet Yes Podsieć prywatnego punktu końcowego konta foundry. vnet Wymaga to elementów i name. Dodaj prefix , kiedy azd należy utworzyć podsieć.
agentSubnet No Podsieć zarządzana przez klienta dla ruchu wychodzącego hostowanego agenta. vnet nameWymaga i i musi być inną podsiecią w tej samej sieci wirtualnej co peSubnet.
isolationMode No Stan ruchu wychodzącego dla Microsoft zarządzanego ruchu wychodzącego. Użyj go tylko wtedy, gdy pominięto agentSubnet. Prawidłowe wartości to AllowInternetOutbound i AllowOnlyApprovedOutbound.
dns.resourceGroup No Grupa zasobów zawierająca istniejące prywatne strefy DNS. Pomiń go, aby utworzyć azd i połączyć wymagane strefy.
dns.subscription No Subskrypcja zawierająca istniejące prywatne strefy DNS. Domyślnie jest to subskrypcja wdrożenia.

Sieć prywatna wyłącza publiczny dostęp do płaszczyzny danych dla konta. Automatycznie utworzony Azure Container Registry nie jest obsługiwany w tej konfiguracji. Użyj wdrożenia kodu źródłowego lub określ wstępnie skompilowany imageelement .

azure.ai.agent service

Usługa agenta zawiera definicję agenta oraz jej ustawienia kompilacji i wdrażania. Zadeklaruj go w tekście lub użyj jawnego katalogu głównego $ref do bezpośredniej definicji YAML lub JSON. azd ai agent add <service> --file <path> tworzy deklarację z kopią pliku; sparametryzowana AgentManifest otoka nie jest obsługiwaną definicją.

(No changes needed) Opis
host Musi mieć wartość azure.ai.agent.
kind Rodzaj agenta: hosted, promptlub voice. Hostowani agenci mogą używać kodu źródłowego lub wdrożenia kontenera.
name Nazwisko agenta. Ponowne użycie nazwy powoduje utworzenie nowej wersji istniejącego agenta.
displayName Opcjonalna przyjazna dla człowieka nazwa wyświetlana.
description Opcjonalny opis agenta.
project Ścieżka do katalogu źródłowego agenta, na przykład src/my-agent.
language Język kompilacji dla hostowanych agentów. Użyj docker.
uses Lista usług, od których zależy ten agent, na przykład projekt, połączenia i przyborniki.
protocols Protokoły wywołania implementują agenta.
env Mapa zmiennych środowiskowych przekazanych do kontenera.
container Ustawienia procesora CPU i pamięci kontenera.
startupCommand Polecenie uruchamiające serwer agenta, na przykład python main.py. Używany przez azd ai agent run program do programowania lokalnego i uruchamiania kontenera.
toolboxes Lista nazw usług używanych azure.ai.toolbox przez agenta w czasie wykonywania.
codeConfiguration Ustawienia wdrażania źródłowego (ZIP). Zobacz Wdrażanie trybów.
image Adres URL wstępnie utworzonego obrazu kontenera. Po ustawieniu azd obraz jest wdrażany bezpośrednio i pomija kompilację dockerfile.
metadata Opcjonalne pary klucz-wartość metadanych.
agentCard Metadane odnajdywania na poziomie agenta, w tym skills.

Usługi głosowe

Służy kind: voice do deklaratywnej usługi głosowej. Interfejs wiersza polecenia akceptuje kind: prompt-voice również i nadal generuje ten alias podczas inicjowania głosu monitu. Usługi głosowe używają tego samego azure.ai.agent hosta co hostowani i monituj agentów.

(No changes needed) Purpose
modelType W przypadku usług managed głosowych opartych na modelu używa modelu hostowanego przez usługę i self_deployed używa własnego wdrożenia modelu.
model.id Nazwa modelu zarządzanego lub dla modelu BYOM istniejąca nazwa wdrożenia. Deklarowanie nazwy BYOM nie powoduje utworzenia wdrożenia.
voice Nazwa głosu wyjściowego. Służy audio.output do szczegółowej konfiguracji danych wyjściowych audio.
audio, outputModalities, greeting, store Konfigurowanie środowiska głosowego.
conversationEngine W przypadku hostowanej otoki głosowej odwołuje się do hostowanego obiektu docelowego zamiast wybierania modelu w otoce.
telephony.bindings Powiązania dostawcy telefonów dla usługi głosowej monitu.

Aby zapoznać się z przykładami modelu i audio, zobacz Konfigurowanie agenta głosowego.

Hostowany aparat konwersacji

Ustaw te pola w otoce głosowej, a nie w hostowanym obiekcie docelowym:

conversationEngine:
  type: hosted_agent
  name: voice-live-bridge-basic-python
  version: deployed
(No changes needed) Wymagane Opis
type Yes Musi mieć wartość hosted_agent.
name Yes Nazwa usługi hostowanego obiektu docelowego w programie w azure.yamltym samym projekcie Foundry.
version No Jedyną obsługiwaną wartością jest deployed, która jest również wartością domyślną. Przypina otokę do wersji docelowej wdrożonej przez bieżące azd środowisko.

Uwzględnij hostowany element docelowy na liście otoki uses , aby zamówić wdrożenie. Element docelowy musi być aktywny i zadeklarować invocations_ws wersję 1.0.0, z metadanymi voiceLiveCompatible: "true" i bridgeProtocolVersion: "1.0" .

Wywołania modelu, instrukcje i narzędzia należą do obiektu docelowego. Ustawienia audio i powitania należą do otoki. Starsze modelType: hosted_agent i targetAgent ustawienia nie są obsługiwane; użyj polecenia conversationEngine.

Aby zapoznać się z kompletnym przykładem dwóch usług, zobacz Używanie hostowanego agenta jako aparatu konwersacji w agencie opartym na głosie.

Powiązania telefonii

Każdy wpis w pliku telephony.bindings wymaga provider, identifieri connection. connection to nazwa istniejącego połączenia projektu Foundry, a nie poświadczenia dostawcy.

provider format identifier
twilio Numer telefonu E.164, taki jak +14255550123.
acs 28:orgid:<resource-account-guid> dla rozszerzalności telefonu w aplikacji Teams.

Interfejs wiersza polecenia mapuje acs wartość dostawcy azure-communication-serviceusług . Użyj tych identyfikatorów w pliku azure.yaml; nie kopiuj ich do właściwości REST, które oczekują innej reprezentacji.

Powiązania są tworzone tylko. Wdrożenie akceptuje zgodne istniejące powiązanie, ale kończy się niepowodzeniem, jeśli jego konfiguracja się różni. Wywołania zwrotne po stronie dostawcy i zasoby telefoniczne nie są tworzone przez tę deklarację. Aby zapoznać się z przykładami i wskazówkami dotyczącymi cyklu życia, zobacz Dodawanie powiązania telefonii.

agentCard.skills i azure.ai.skill

agentCard.skills Opisuje możliwości agenta na karcie odnajdywania. Udostępnia metadane dla klientów i nie tworzy ani nie dołącza umiejętności odnajdowania wielokrotnego użytku. Każda umiejętność karty wymaga idelementu , namei description.

Usługa azure.ai.skill tworzy umiejętności w wersji na podstawie instrukcji i opcjonalnych dozwolonych narzędzi. Zadeklaruj go oddzielnie w obszarze services; jego uses lista kontroluje kolejność zależności, ale nie wypełnia agentCard.skills ani nie dołącza umiejętności do agenta. Służy agentCard.skills do odnajdywania metadanych i azure.ai.skill instrukcji wielokrotnego użytku.

agentCard:
    description: Research agent discovery card.
    skills:
        - id: research
          name: Research
          description: Researches a requested subject.
services:
    code-review:
        host: azure.ai.skill
        uses:
            - ai-project
        instructions: ./skills/code-review.md

Ukończ kartę odnajdywania

Dodaj versionelement , tagsi examples , gdy klienci potrzebują bogatszych metadanych odnajdywania. Karta wymaga description co najmniej jednej umiejętności. Każda umiejętność wymaga idelementu , namei description.

agentCard:
    description: Research agent discovery card.
    version: "1.0"
    skills:
        - id: research
          name: Research
          description: Researches a requested subject.
          tags:
              - research
          examples:
              - Research current product guidance.

Zasady odpowiedzialnej sztucznej inteligencji

Użyj policies polecenia , aby skojarzyć zasady odpowiedzialnej sztucznej inteligencji z hostowanym agentem. Ustaw raiPolicyName pełny identyfikator zasobu usługi ARM zasad:

policies:
    - type: rai_policy
      raiPolicyName: ${RAI_POLICY_RESOURCE_ID}

Typ rai_policy i raiPolicyName są wymagane. Rozszerzenie stosuje pierwsze prawidłowe zasady na liście do konfiguracji odpowiedzialnej sztucznej inteligencji hostowanego agenta. Aby uzyskać wskazówki dotyczące tworzenia zasad i zarządzania nimi, zobacz Dodawanie barier zabezpieczających do hostowanych agentów.

Magazyny pamięci

Użyj memoryStores polecenia , aby utworzyć lub ponownie użyć magazynów pamięci programu Foundry przed wdrożeniem. Każdy magazyn wymaga istniejących nazw wdrożeń modelu rozmów i osadzania modelu.

memoryStores:
    - name: customer-memory
      description: Stores durable customer context.
      chatModel: gpt-5.4-mini
      embeddingModel: text-embedding-3-large
      options:
          chatSummaryEnabled: true
          userProfileEnabled: true
          proceduralMemoryEnabled: false
          defaultTtlSeconds: 0
(No changes needed) Wymagane Opis
name Yes Nazwa magazynu pamięci.
description No Opis magazynu pamięci.
chatModel Yes Wdrożenie modelu rozmów używane do przetwarzania zawartości pamięci.
embeddingModel Yes Wdrożenie modelu osadzania używane do przetwarzania zawartości pamięci.
options.chatSummaryEnabled No Włącza pamięć podsumowania czatów.
options.userProfileEnabled No Włącza pamięć profilu użytkownika.
options.proceduralMemoryEnabled No Włącza pamięć proceduralną.
options.defaultTtlSeconds No Ustawia domyślny okres przechowywania w sekundach. Ustaw 0 wartość bez wygaśnięcia.
options.userProfileDetails No Zawiera wskazówki dotyczące danych profilu do zachowania.

Istniejące magazyny nie są aktualizowane podczas wdrażania. Jeśli zadeklarowana definicja różni się od istniejącego magazynu, azd zgłasza różnicę. Deklarowanie magazynu pamięci nie powoduje zmiany kodu agenta ani automatycznego dołączania narzędzia pamięci. Połącz aplikację z magazynem pamięci przy użyciu narzędzia do wyszukiwania pamięci lub interfejsów API magazynu pamięci. Aby uzyskać szczegółowe informacje, zobacz Używanie pamięci z agentami.

Konfigurowanie punktu końcowego agenta

Służy agentEndpoint do konfigurowania protokołów i schematów autoryzacji publikowanych przez punkt końcowy agenta. Użyj karty agenta z punktem końcowym A2A, aby inni agenci mogli odnaleźć dostępne możliwości.

agentEndpoint:
    protocols:
        - responses
        - a2a
    authorizationSchemes:
        - type: Entra

Bieżąca azd konfiguracja reprezentuje AzureRbac schemat autoryzacji przy użyciu aliasu Entra . Aby uzyskać informacje o wszystkich opcjach autoryzacji punktu końcowego, zobacz Autoryzacja punktu końcowego agenta.

Możesz również określić versionSelector.versionSelectionRules , kiedy trzeba kontrolować, która wersja agenta odbiera ruch punktów końcowych. Usługa agenta weryfikuje protokół punktu końcowego i wartości autoryzacji podczas wdrażania.

protocols

protocols:
    - protocol: responses
      version: 2.0.0
Protocol Opis
responses Interfejs API odpowiedzi openAI. Obejmuje zarządzanie historią konwersacji.
invocations Niestandardowy protokół ładunku. Brak wbudowanego zarządzania konwersacjami.
a2a Protokół agenta do agenta na potrzeby orkiestracji agenta.

Aby uzyskać pełną specyfikację protokołu, zobacz Hostowany kontrakt czasu wykonywania agenta.

Dodatkowe protokoły środowiska uruchomieniowego i punkty końcowe działania

Oprócz responsesinvocationsa2aobsługi wywołań protokołu WebSocket oraz activity scenariuszy działań Microsoft 365 i Teams, oprócz agentów hostowanych oraz hostowanych agentów.invocations_ws

protocols:
    - protocol: invocations_ws
      version: 2.0.0
    - protocol: activity
      version: 2.0.0

W przypadku agenta działania dodaj activity do konfiguracji publicznego punktu końcowego i użyj wymaganego schematu autoryzacji Bot Service:

agentEndpoint:
    protocols:
        - activity
    authorizationSchemes:
        - type: BotServiceRbac

Protokół działania może współistnieć z innymi protokołami w tym samym punkcie końcowym agenta. Aby uzyskać informacje o zachowaniu protokołu środowiska uruchomieniowego, zobacz Co to są hostowani agenci?.

środowisko

env:
    MICROSOFT_FOUNDRY_MODEL_DEPLOYMENT_NAME: ${MICROSOFT_FOUNDRY_MODEL_DEPLOYMENT_NAME}
    LOG_LEVEL: info

Składnia ${ } odwołuje się azd do zmiennych środowiskowych z elementu .azure/<env>/.env.

Uwaga / Notatka

Nie deklaruj FOUNDRY_PROJECT_ENDPOINT w pliku env. Platforma automatycznie wprowadza ją do hostowanych kontenerów i azd ai agent run ustawia ją na potrzeby programowania lokalnego. Deklarowanie go w tym miejscu jest nadmiarowe i ryzyko zaciemniania wartości platformy.

Środowisko platformy, tożsamość i punkty końcowe

Platforma rezerwuje FOUNDRY_ prefiksy i AGENT_ . Odczytaj zmienne platformy, takie jak FOUNDRY_PROJECT_ENDPOINT, z kodu aplikacji, ale nie definiują ani nie zastępują ich w pliku env. Wartości środowiska zdefiniowane przez agenta to ciągi.

Każdy wdrożony hostowany agent otrzymuje dedykowaną tożsamość i punkt końcowy agenta Microsoft Entra ID. Nie dodawaj identity bloku do usługi agenta. Tożsamość agenta może domyślnie używać punktu końcowego projektu i magazynu sesji. Przypisz dodatkowe role tożsamości, gdy agent musi uzyskać dostęp do zasobów zewnętrznych. Aby uzyskać szczegółowe informacje, zobacz Dokumentacja uprawnień hostowanego agenta.

Zadeklarowane protokoły określają punkty końcowe, które są aktywne po wdrożeniu. Uruchom polecenie azd ai agent show , aby sprawdzić wdrożonego agenta i jego adresy URL punktów końcowych.

Po wdrożeniu azd zapisuje następujące wartości w aktywnym środowisku przy użyciu znormalizowanej nazwy usługi zamiast <SERVICE>:

  • AGENT_<SERVICE>_NAME
  • AGENT_<SERVICE>_VERSION
  • AGENT_<SERVICE>_ENDPOINT
  • AGENT_<SERVICE>_<PROTOCOL>_ENDPOINTdla włączonych responsesprotokołów , invocationsi invocations_ws

Użyj danych wyjściowych specyficznych dla protokołu, gdy aplikacja lub automatyzacja potrzebuje adresu URL wywołania. Podstawowy punkt końcowy identyfikuje wdrożoną wersję agenta dla operacji zarządzania sesjami.

kontener

container:
    resources:
        cpu: "0.25"
        memory: 0.5Gi

Skonfiguruj cpu z "0.25" maksymalnie do "4.0", i memory z 0.5Gi maksymalnie 8.0Gi.

Wdrażanie kodu źródłowego

W przypadku Python wdrożenia kodu źródłowego ustaw również na PYTHONNOUSERSITE: "1" mapie usługi agenta env obok codeConfigurationelementu . Zobacz Konfigurowanie uruchamiania Python.

Ustaw codeConfiguration wartość , aby wdrożyć kod źródłowy jako plik ZIP zamiast obrazu kontenera. Określ jedną nazwę pliku punktu wejścia lub nazwę zestawu. azd łączy go z wybranym środowiskiem uruchomieniowym podczas tworzenia wersji hostowanego agenta.

codeConfiguration:
    runtime: python_3_13
    entryPoint: main.py
    dependencyResolution: remote_build

Użyj remote_build polecenia , aby przywrócić zależności ze źródeł projektu lub użyć bundled pliku ZIP zawierającego zależności zgodne z systemem Linux. Nie należy łączyć się codeConfiguration z konfiguracją kontenera opartą na obrazach. Aby uzyskać wskazówki dotyczące tworzenia pakietów i zależności, zobacz Wdrażanie hostowanego agenta z kodu źródłowego.

Kompilowanie kontenerów i wstępnie utworzone obrazy

Użyj elementu Dockerfile w obszarze project , aby utworzyć obraz kontenera lub ustawić go image w celu wdrożenia wstępnie utworzonego obrazu:

image: myregistry.azurecr.io/agents/researcher:1.2.3

Gdy element i Dockerfileimage są dostępne, wybierz wstępnie utworzony obraz w interakcyjnym monicie wdrożenia. W przypadku wdrożenia nienadzorowanego ustaw wartość na AZD_AGENT_SKIP_ACRtrue w aktywnym azd środowisku, aby wybrać skonfigurowany obraz. Aby uzyskać uprawnienia rejestru i wdrożenie rejestru prywatnego, zobacz Wdrażanie hostowanego agenta z prywatnym Azure Container Registry.

Ograniczenia dotyczące metadanych i schematów

Użyj wartości ciągu dla wdrożonych metadanych agenta. Wartość authors metadanych może być listą ciągów. Nie należy polegać na displayNamesystemie , inputSchemaani outputSchema w celu skonfigurowania wdrożonego hostowanego agenta; ujednolicona konfiguracja akceptuje te pola, ale żądanie tworzenia hostowanego agenta nie korzysta z nich.

azure.ai.connection service

Połączenie łączy projekt z zasobem zewnętrznym. Klucz usługi to nazwa połączenia, a usługa zależy od projektu za pośrednictwem .uses

(No changes needed) Opis
host Musi mieć wartość azure.ai.connection.
category Kategoria połączenia, na przykład CustomKeys, ApiKey, AzureOpenAI, CognitiveSearchlub RemoteTool.
target Docelowy adres URL punktu końcowego lub identyfikator zasobu usługi ARM.
authType Typ uwierzytelniania, na przykład ApiKey, CustomKeys, AAD, ManagedIdentitylub OAuth2.
credentials Poświadczenia połączenia. Wartości mogą zawierać ${VAR} odwołania.
metadata Dodatkowe metadane jako pary klucz-wartość.
github-conn:
    host: azure.ai.connection
    uses:
        - ai-project
    category: RemoteTool
    target: https://api.githubcopilot.com/mcp
    authType: CustomKeys
    credentials:
        Authorization: ${GITHUB_PAT}

Zmiany połączenia mają zastosowanie w czasie azd provision, a nie azd deploy. Przechowuj wartości poświadczeń w azd środowisku i odwołuj się do nich ${VAR} zamiast umieszczać wpisy tajne w pliku azure.yaml.

usługa azure.ai.toolbox

Przybornik to nazwany pakiet narzędzi, do których odwołują się agenci. Narzędzia oparte na połączeniu azure.ai.connection nazywają usługę connection za pośrednictwem pola.

(No changes needed) Opis
host Musi mieć wartość azure.ai.toolbox.
description Opis przybornika.
tools Lista narzędzi. Każdy wpis ma element type i , dla narzędzi opartych na połączeniu, .connection
research-tools:
    host: azure.ai.toolbox
    uses:
        - ai-project
        - search-conn
    tools:
        - type: azure_ai_search
          connection: search-conn
        - type: code_interpreter

Agent odwołuje się do przybornika, dodając nazwę usługi przybornika do listy i uses do jej toolboxes listy.

Korzystanie z punktu końcowego przybornika

W projekcie uses podzielonej usługi kontroluje kolejność wdrażania. Aplikacja łączy się z punktem końcowym MCP przybornika w czasie wykonywania. Przekaż nazwę przybornika lub punkt końcowy do aplikacji za pośrednictwem envmetody , a następnie skonstruuj punkt końcowy odbiorcy z FOUNDRY_PROJECT_ENDPOINT kodu agenta. Aby zapoznać się z przykładem kompleksowego, zobacz Używanie przybornika z hostowanym agentem.

azure.ai.skill i azure.ai.routine services

azure.ai.skill Usługa definiuje wytyczne behawioralne wielokrotnego użytku, do których agenci odwołują się według nazwy. azure.ai.routine Usługa definiuje wyzwalacz (harmonogram lub zdarzenie) i akcję, która wywołuje agenta. Obie te elementy zależą od zasobów, których używają za pośrednictwem usługi uses. Aby dowiedzieć się więcej na temat dodawania narzędzi do użycia agenta, zobacz Co to jest przybornik w narzędziu Foundry? i Używanie procedur.

Umiejętności i procedury są oddzielnymi zasobami. Deklarowanie usługi kontroluje jej cykl życia, ale nie dołącza automatycznie umiejętności do agenta lub wnioskowanie rutynowego celu akcji. Jawnie skonfiguruj korzystanie z aplikacji lub rutynowej akcji.

Zależności z użyciem

Pole uses deklaruje usługi, od których zależy dana usługa. azd Używa tego grafu do zamawiania aprowizacji i odwołań do przewodów, takich jak połączenia i przyborniki agenta.

uses:
    - ai-project
    - search-conn
    - research-tools

Plik zawiera $ref

Usługi i wpisy listy mogą używać odwołań do lokalnych plików YAML lub JSON. azure.ai.toolbox definicje usług są wyjątkiem: zachowaj je w tekście. Wdrożenie przybornika nie obsługuje katalogu głównego $ref ani automatycznego ładowania toolbox.yaml.

Ścieżki względne są rozpoznawane z pliku zawierającego element $ref. Zdalne adresy URL nie są obsługiwane.

services:
    triage:
        host: azure.ai.agent
        uses:
            - ai-project
        $ref: ./agents/triage.yaml

Plik zawiera umożliwia przechowywanie dużych definicji agentów we własnych plikach i udostępnianie definicji między projektami.

Zachowaj podstawowe pola usługi we wpisie głównym azure.yaml podczas korzystania z usługi $ref: host, , projectuses, language, , imagei docker. Umieść pola definicji należące do dostawcy, takie jak kind, name, descriptioni protocols, w mapowaniu, do którego się odwołujesz. $ref rozpoznaje lokalne pliki YAML lub JSON rekursywnie; Adresy URL i cykle odwołań nie są obsługiwane.

Podstawianie zmiennych

Dwie składnie podstawień mogą być wyświetlane w pliku azure.yaml:

Składnia Rozwiązane, gdy Przez co
${VAR_NAME} azd provision lub azd deploy azd zmienne środowiskowe z .azure/<env>/.env, rozwiązane po stronie klienta.
${{ ... }} W czasie wykonywania Rozpoznawanie po stronie serwera programu Foundry. azd przechodzi przez nietknięte.

Tryby infrastruktury i wdrażania

Bicep mniej domyślnie

azd ai agent init jest domyślnie mniej bicep: nie zapisuje infra/ katalogu i azd syntetyzuje infrastrukturę z azure.yaml usług w czasie aprowizacji. Aby zmaterializować pliki infrastruktury jako kodu, wyrzuć je:

Polecenie Result
azd ai agent init --infra Wysunie Bicep; domyślna ścieżka bez istniejącej infrastruktury to ./infra/.
azd ai agent init --infra=bicep Wyrzuca Bicep (jawne).
azd ai agent init --infra=terraform Wyrzuca warstwę narzędzia Terraform Foundry i rejestruje jej dostawcę w programie azure.yaml.

Wyrzucenie zachowuje istniejącą infrastrukturę aplikacji przez dodanie warstwy foundry w obszarze infra/foundry. Istniejące konfiguracje warstwowe zachowują zadeklarowane ścieżki. Jeśli projekt deklaruje już usługi Foundry, uruchom --infra sam: ta gałąź wyrzuca istniejące deklaracje i odrzuca dane wejściowe inicjowania, takie jak --template i ścieżkę pozycyjną.

Tryby wdrażania

Hostowany agent jest wdrażany w jednym z dwóch trybów:

Tryb Jak to działa Jak wybrać
code azd przekazuje źródło jako plik ZIP i tworzy je zdalnie. Jest to ustawienie domyślne dla projektów Python i .NET. azd ai agent init --deploy-mode code
container azd tworzy obraz platformy Docker z poziomu usługi Dockerfile i wdraża go. azd ai agent init --deploy-mode container

W przypadku wdrożeń źródłowych pole w usłudze codeConfiguration agenta przechwytuje środowisko uruchomieniowe i punkt wejścia. W przypadku wstępnie utworzonych obrazów ustaw image pole w usłudze agenta i pomiń kompilację pliku Dockerfile.

Migracja starszej wersji konfiguracji

Starsze definicje agentów mogą zagnieżdżać zmienne środowiskowe w obszarze config: env. W ujednoliconym systemie azure.yamlprzenieś env mapowanie do usługi agenta:

# Legacy
services:
    my-agent:
        host: azure.ai.agent
        config:
            env:
                MICROSOFT_FOUNDRY_MODEL_DEPLOYMENT_NAME: ${MICROSOFT_FOUNDRY_MODEL_DEPLOYMENT_NAME}
# Unified azure.yaml
services:
    my-agent:
        host: azure.ai.agent
        env:
            MICROSOFT_FOUNDRY_MODEL_DEPLOYMENT_NAME: ${MICROSOFT_FOUNDRY_MODEL_DEPLOYMENT_NAME}

Walidacja schematu JSON

Dodaj odwołanie do schematu dla autouzupełniania środowiska IDE:

# yaml-language-server: $schema=https://raw.githubusercontent.com/Azure/azure-dev/main/schemas/v1.0/azure.yaml.json