Notatka
Dostęp do tej strony wymaga autoryzacji. Może spróbować zalogować się lub zmienić katalogi.
Dostęp do tej strony wymaga autoryzacji. Możesz spróbować zmienić katalogi.
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ładazd 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>_NAMEAGENT_<SERVICE>_VERSIONAGENT_<SERVICE>_ENDPOINT-
AGENT_<SERVICE>_<PROTOCOL>_ENDPOINTdla włączonychresponsesprotokołów ,invocationsiinvocations_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
Treści powiązane
- Tworzenie pliku azure.yaml dla hostowanych agentów
- Inicjowanie projektu hostowanego agenta przy użyciu interfejsu wiersza polecenia dewelopera Azure
- Infrastruktura hostowanego agenta za pomocą interfejsu wiersza polecenia dewelopera Azure
- Umowa hostowanego agenta dotycząca środowiska uruchomieniowego
- Co to są hostowani agenci?