odwołanie do schematu agent.yaml

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.

Uwaga / Notatka

Manifesty agentów (agent.manifest.yaml) i autonomiczne definicje agentów (agent.yaml) są przestarzałe. Od rozszerzeń foundry azd (azure.ai.agents 1.0.0-beta.1) wszystkie hostowane konfiguracje agenta znajdują się w jednym elemecie azure.yaml. Zobacz Tworzenie pliku azure.yaml dla hostowanych agentów i dokumentacji azure.yaml dla hostowanych agentów.

Specyfikacja AgentSchema to otwarty standard definiowania agentów sztucznej inteligencji. Podczas tworzenia hostowanych agentów pracujesz głównie z trzema typami schematów najwyższego poziomu: AgentDefinition, AgentManifest i ContainerAgent. Ten starszy model schematu dla elementu AgentManifest, AgentDefinition, agent.manifest.yamli agent.yaml jest zachowywany dla odwołania i jest zastępowany przez azure.yaml. Schemat nie jest specyficzny dla jednego narzędzia. Interfejs wiersza polecenia dewelopera Azure (azd) i zestaw narzędzi Microsoft Foundry Toolkit dla Visual Studio Code go używać.

Schemat jest wyświetlany w dwóch kontekstach pliku z różnymi konwencjami nazewnictwa:

agent.manifest.yaml to agentManifest, sparametryzowany szablon używany przez starsze przykłady. Bieżąca azd ai agent init -t inicjalizacja azure.yaml wymaga dokumentu projektu i odrzuca otoki AgentManifest.
agent.yaml to agentDefinition , konkretna konfiguracja, która starsza inicjalizacja zapisała się w projekcie pod adresem src/<agent>/agent.yaml.

Oba pliki opisują , czym jest agent: jego model, narzędzia, protokoły, środowisko i zasoby. Różni się to od azure.yamlelementu , w którym opisano sposób aprowizowania i wdrażania zasobów Azure. Aby uzyskać informacje azure.yaml , zobacz azure.yaml reference for hosted agents (Dokumentacja pliku azure.yaml dla hostowanych agentów).

Typy schematów

AgentDefinition

AgentDefinition to konkretna specyfikacja agenta, który jest gotowy do uruchomienia. Opisuje pojedyncze wystąpienie agenta z określoną konfiguracją i bez {{ parameter }} symboli zastępczych szablonu.

Każdy element AgentDefinition ma kind pole określające typ agenta.

Rodzaj	Opis
`prompt`	Agent oparty na monitach skonfigurowany tylko za pomocą instrukcji.
`hosted`	Konteneryzowany agent wdrożony jako obraz kontenera.
`workflow`	Agent orkiestracji, który koordynuje innych agentów.

Wygenerowany element AgentDefinition może nadal zawierać ${VAR_NAME} odwołania. azd Są to symbole zastępcze zmiennych środowiskowych, a nie część specyfikacji AgentSchema. Umożliwiają one pracę pojedynczego pliku definicji w wielu azd środowiskach przez rozpoznawanie wartości z pliku każdego środowiska .azure/<env>/.env w czasie wdrażania.

AgentManifest

AgentManifest to sparametryzowany szablon do dynamicznego tworzenia agentów. Opakowuje element AgentDefinition jako pole template i dodaje:

parameters: wartości, które są monitowane lub wstrzykiwane w czasie tworzenia, przy użyciu {{ parameter }} składni podstawienia.
resources: zależności zewnętrzne, takie jak wdrożenia modelu, przyborniki lub połączenia.

Użyj agentaManifest, jeśli potrzebujesz szablonów wielokrotnego użytku lub chcesz wdrożyć podobnych agentów z różnymi konfiguracjami. Po uruchomieniu polecenia azd ai agent initzwykle wskazujesz manifest, wybierając szablon lub podając adres URL. Proces inicjowania monituje o wartości parametrów i generuje element AgentDefinition.

ContainerAgent

KontenerAgent to agentDefinition z elementem kind: hosted. Rozszerza definicję podstawową przy użyciu pól specyficznych dla kontenera i jest template elementem wewnątrz agentaManifest podczas tworzenia hostowanego agenta.

Kiedy należy użyć manifestu lub definicji

Używanie manifestu, gdy	Używanie definicji, gdy
Szablon agenta wielokrotnego użytku można opublikować dla innych użytkowników w celu utworzenia wystąpienia.	Wdrażasz określonego agenta pojedynczego przeznaczenia.
Chcesz, aby użytkownicy konfigurowali model, narzędzia lub połączenia w czasie inicjowania.	Wszystkie wartości konfiguracji są znane i stałe.
Tworzysz przykładowy lub początkowy szablon.	Uruchomiono już definicję `azd ai agent init` wygenerowaną.

Większość deweloperów zaczyna od manifestu, azd ai agent init a następnie pracuje z wygenerowaną definicją. Autorzy szablonów i przykładowi wydawcy są głównymi twórcami manifestów.

Pola najwyższego poziomu

Poniższe odwołanie dokumentuje pola manifestu, które są nadzbiorem pól definicji.

(No changes needed)	Typ	Wymagane	Opis
`name`	ciąg	Yes	Nazwa manifestu agenta.
`description`	ciąg	No	Opis agenta.
`metadata`	obiekt	No	Dodatkowe metadane, takie jak `tags`.
`template`	ContainerAgent	Yes	Szablon definicji agenta.
`parameters`	obiekt	No	Konfigurowalne parametry są monitowane podczas inicjowania.
`resources`	macierz	Yes	Zasoby wymagane przez agenta.

template (ContainerAgent)

Pole template definiuje hostowanego agenta kontenera.

(No changes needed)	Typ	Wymagane	Opis
`name`	ciąg	Yes	Nazwisko agenta.
`kind`	ciąg	Yes	Musi być `hosted` przeznaczony dla hostowanych agentów.
`protocols`	macierz	Yes	Obsługa protokołu.
`environment_variables`	macierz	No	Zmienne środowiskowe dla kontenera.
`resources`	obiekt	No	Zasoby procesora CPU i pamięci kontenera.
`image`	ciąg	No	Wstępnie utworzona ścieżka obrazu kontenera.
`dockerfilePath`	ciąg	No	Ścieżka do pliku Dockerfile.

Protokołów

protocols:
  - protocol: responses    # OpenAI Responses API
    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.

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

environment_variables

environment_variables:
  - name: FOUNDRY_MODEL_NAME
    value: ${FOUNDRY_MODEL_NAME}

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

Uwaga / Notatka

Nie deklaruj FOUNDRY_PROJECT_ENDPOINT w pliku environment_variables. 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.

parameters

Parametry są monitowane podczas wykonywania azd ai agent initpolecenia . Służy secret: true do obsługi wartości poufnych.

parameters:
  github_pat:
    secret: true
    description: GitHub Personal Access Token

resources

Zasoby definiują, czego potrzebuje agent. W poniższych kształtach opisano, jakie manifesty deklarują i co azd ai agent init zapisuje w projekcie. Po zainicjowaniu zarządzaj tymi samymi zasobami o zakresie projektu w czasie wykonywania za pomocą poleceń interfejsu wiersza polecenia bezpośredniego: azd ai connection, , azd ai toolboxazd ai skilli azd ai routine.

Uwaga / Notatka

Schemat nie zawiera pola umiejętności. Polecenia azd ai agent init, azd ai agent runi azd up nie umożliwiają automatycznego pobierania umiejętności. Samodzielne zarządzanie umiejętnościami azd ai skill jako zasobami na poziomie projektu i podłączanie ich do środowiska uruchomieniowego agenta.

Zasób modelu

resources:
  - kind: model
    name: chat
    id: gpt-4.1-mini

Zasób połączenia

resources:
  - kind: connection
    name: MyConnection
    target: https://api.example.com
    category: remoteTool
    credentials:
        type: CustomKeys
        keys:
            Authorization: "Bearer {{ my_api_key }}"

Zasób przybornika

resources:
  - kind: toolbox
    name: agent-tools
    description: Agent toolbox
    tools:
      - name: webSearch
        type: builtin
        capability: web-search
      - name: codeInterpreter
        type: builtin
        capability: code-interpreter
      - name: myMcp
        type: connection
        connection: "{{ MyConnection }}"

Wersja przybornika zawiera trzy rodzaje wpisów: nieprzetworzone tools wpisy (wbudowane funkcje, takie jak web-search lub code-interpreter), connections (połączenia projektu, takie jak serwer MCP narzędzia zdalnego lub indeks wyszukiwania) i skills (odwołania do istniejących umiejętności projektu). Miejsce tools jest deklarowane z góry w manifeście. Dodaj połączenia i odwołania do umiejętności przyrostowo za pomocą poleceń azd ai toolbox connection add i azd ai toolbox skill add.

Kompletny przykład

name: my-web-search-agent
description: An agent with web search and MCP tools

metadata:
  tags:
    - AI Agent Hosting

template:
  name: my-web-search-agent
  kind: hosted
  protocols:
    - protocol: responses
      version: 2.0.0
  environment_variables:
    - name: FOUNDRY_MODEL_NAME
      value: ${FOUNDRY_MODEL_NAME}
    - name: TOOLBOX_ENDPOINT
      value: ${TOOLBOX_ENDPOINT}

parameters:
  github_pat:
    secret: true
    description: GitHub PAT for MCP connection

resources:
  - kind: model
    name: chat
    id: gpt-4.1-mini

  - kind: connection
    name: GithubMcpConnection
    target: https://api.githubcopilot.com/mcp
    category: remoteTool
    credentials:
        type: CustomKeys
        keys:
            Authorization: "Bearer {{ github_pat }}"

  - kind: toolbox
    name: agent-tools
    description: Web search and GitHub MCP tools
    tools:
      - name: webSearch
        type: builtin
        capability: web-search
      - name: github
        type: connection
        connection: "{{ GithubMcpConnection }}"

Podstawianie zmiennych

Podstawianie odbywa się w dwóch warstwach: parametry manifestu są rozpoznawane w czasie inicjowania, a zmienne środowiskowe są rozpoznawane w czasie wykonywania lub wdrażania. Jeden plik definicji może następnie działać we wszystkich azd środowiskach.

Składnia	Rozwiązane, gdy	Przez co
`{{ param_name }}`	`azd ai agent init`	Wartości parametrów manifestu monitowane od użytkownika.
`${VAR_NAME}`	`azd deploy` lub `azd ai agent run`	`azd` zmienne środowiskowe z `.azure/<env>/.env`.

Opinia

Czy ta strona była pomocna?

Ostatnia aktualizacja o 2026-10-16

odwołanie do schematu agent.yaml

Typy schematów

AgentDefinition

AgentManifest

ContainerAgent

Kiedy należy użyć manifestu lub definicji

Pola najwyższego poziomu

template (ContainerAgent)

Protokołów

environment_variables

parameters

resources

Zasób modelu

Zasób połączenia

Zasób przybornika

Kompletny przykład

Podstawianie zmiennych

Treści powiązane

Opinia

Dodatkowe zasoby