Referenční informace ke schématu agent.yaml

Important

Položky označené jako náhled v tomto článku jsou aktuálně ve verzi Preview. Tato verze Preview se poskytuje bez smlouvy o úrovni služeb a Microsoft ji nedoporučuje pro produkční úlohy. Některé funkce nemusí být podporované nebo můžou mít omezené možnosti. Další informace najdete v dodatečných podmínkách použití pro verze Preview v Microsoft Azure.

Poznámka:

Manifesty agentů (agent.manifest.yaml) a samostatné definice agenta (agent.yaml) jsou zastaralé. Od rozšíření Foundry azd (azure.ai.agents 1.0.0-beta.1) se všechny hostované konfigurace agenta nacházejí v jediném azure.yaml. Informace o hostovaných agentech a azure.yaml najdete v tématu Vytváření agentů azure.yaml pro hostované agenty.

Specifikace AgentSchema je otevřený standard pro definování agentů AI. Při sestavování hostovaných agentů primárně pracujete se třemi typy schémat nejvyšší úrovně: AgentDefinition, AgentManifest a ContainerAgent. Tento starší model schématu pro AgentManifest, AgentDefinitionagent.manifest.yaml, a agent.yaml je zachován pro odkaz a je nahrazen azure.yaml. Schéma není specifické pro jeden nástroj. Rozhraní příkazového řádku pro vývojáře Azure (azd) a Microsoft Foundry Toolkit pro Visual Studio Code ho používají.

Schéma se zobrazí ve dvou kontextech souborů s odlišnými zásadami vytváření názvů:

agent.manifest.yaml je AgentManifest, parametrizovaná šablona používaná staršími ukázkami. Aktuální azd ai agent init -t inicializace vyžaduje azure.yaml dokument projektu a odmítne obálky AgentManifest.
agent.yaml je AgentDefinition, konkrétní konfigurace, která starší inicializace napsala do projektu na src/<agent>/agent.yamladrese .

Oba soubory popisují , co je agent: jeho model, nástroje, protokoly, prostředí a prostředky. Liší se od azure.yamltoho, jak zřizovat a nasazovat Azure prostředky. azure.yaml Referenční informace najdete v referenčních informacích k azure.yaml pro hostované agenty.

Typy schémat

AgentDefinition

AgentDefinition je konkrétní specifikace agenta, který je připravený ke spuštění. Popisuje jednu instanci agenta s konkrétní konfigurací a žádné {{ parameter }} zástupné symboly šablony.

Každý AgentDefinition má kind pole, které určuje typ agenta.

Druh	Description
`prompt`	Agent založený na příkazovém řádku nakonfigurovaný pouze podle pokynů.
`hosted`	Kontejnerizovaný agent nasazený jako image kontejneru
`workflow`	Agent orchestrace, který koordinuje ostatní agenty.

Vygenerovaná definice AgentDefinition může stále obsahovat ${VAR_NAME} odkazy. Jedná se o azd zástupné symboly proměnných prostředí, nikoli součást specifikace AgentSchema. Umožňují, aby jeden definiční soubor fungoval v různých azd prostředích tím, že v době nasazení přeloží hodnoty ze souboru každého prostředí .azure/<env>/.env .

AgentManifest

AgentManifest je parametrizovaná šablona pro dynamické vytváření agentů. Zabalí agentaDefinition jako jeho template pole a přidá:

parameters: hodnoty, které se při vytváření zobrazí nebo vloží, pomocí {{ parameter }} syntaxe nahrazení.
resources: Externí závislosti, jako jsou nasazení modelu, sady nástrojů nebo připojení.

AgentManifest použijte, pokud potřebujete opakovaně použitelné šablony nebo chcete nasadit podobné agenty s různými konfiguracemi. Při spuštění azd ai agent initobvykle ukazujete na manifest, a to buď výběrem šablony nebo zadáním adresy URL. Inicializační proces vyzve k zadání hodnot parametrů a vygeneruje AgentDefinition.

ContainerAgent

ContainerAgent je AgentDefinition s kind: hosted. Rozšiřuje základní definici o pole specifická pro kontejnery a je template uvnitř agentaManifest při sestavování hostovaného agenta.

Kdy použít manifest nebo definici

Použití manifestu, když	Použití definice v případech, kdy
Publikujete opakovaně použitelnou šablonu agenta, aby ostatní mohli vytvořit instanci.	Nasadíte konkrétního jednoúčelového agenta.
Chcete, aby uživatelé na inicializaci nakonfigurovali model, nástroje nebo připojení.	Všechny hodnoty konfigurace jsou známé a opravené.
Vytvoříte ukázkovou nebo úvodní šablonu.	Už jste spustili `azd ai agent init` a máte vygenerovanou definici.

Většina vývojářů začne od manifestu až do azd ai agent init poté pracovat s vygenerovanou definicí. Autoři šablon a ukázkové vydavatelé jsou primární tvůrci manifestů.

Pole nejvyšší úrovně

Následující odkaz dokumentuje pole manifestu, což jsou nadmnožina polí definice.

Field	Typ	Povinné	Description
`name`	řetězec	Ano	Název manifestu agenta
`description`	řetězec	Ne	Popis agenta
`metadata`	objekt	Ne	Další metadata, například `tags`.
`template`	ContainerAgent	Ano	Šablona definice agenta.
`parameters`	objekt	Ne	Konfigurovatelné parametry se během inicializaci zobrazily.
`resources`	pole	Ano	Prostředky vyžadované agentem.

template (ContainerAgent)

Pole template definuje hostovaného agenta kontejneru.

Field	Typ	Povinné	Description
`name`	řetězec	Ano	Jméno agenta.
`kind`	řetězec	Ano	Musí se jednat `hosted` o hostované agenty.
`protocols`	pole	Ano	Podpora protokolu.
`environment_variables`	pole	Ne	Proměnné prostředí pro kontejner
`resources`	objekt	Ne	Prostředky procesoru a paměti kontejneru.
`image`	řetězec	Ne	Předem připravená cesta k imagi kontejneru
`dockerfilePath`	řetězec	Ne	Cesta k souboru Dockerfile.

protokoly

protocols:
  - protocol: responses    # OpenAI Responses API
    version: 2.0.0

Protocol	Description
`responses`	Rozhraní API odpovědí OpenAI Zahrnuje správu historie konverzací.
`invocations`	Vlastní datový protokol. Žádná integrovaná správa konverzací.

Úplnou specifikaci protokolu najdete v tématu Kontrakt modulu runtime hostovaného agenta.

environment_variables

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

Syntaxe ${ } odkazuje na azd proměnné prostředí z .azure/<env>/.env.

Poznámka:

Neprohlašujte FOUNDRY_PROJECT_ENDPOINT v environment_variablessouboru . Platforma ji automaticky vloží do hostovaných kontejnerů a azd ai agent run nastaví ji pro místní vývoj. Deklarace je zde redundantní a riskuje stínování hodnoty platformy.

parameters

azd ai agent initBěhem . Používá se secret: true pro citlivé hodnoty.

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

resources

Prostředky definují, co agent potřebuje. Následující obrazce popisují, co manifesty deklarují a co azd ai agent init zapisuje do projektu. Po inicializaci spravujte stejné prostředky v rámci projektu za běhu pomocí přímých příkazů rozhraní příkazového řádku: azd ai connection, azd ai toolbox, azd ai skilla azd ai routine.

Poznámka:

Schéma neobsahuje pole dovedností. Dovednosti azd ai agent init, azd ai agent runa azd up příkazy se automaticky nestahou. Spravujte dovednosti jako prostředky azd ai skill na úrovni projektu a zachovejte je do modulu runtime vašeho agenta sami.

Prostředek modelu

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

Prostředek připojení

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

Prostředek panelu nástrojů

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 }}"

Verze sady nástrojů má tři druhy položek: nezpracované tools položky (například předdefinované funkce, jako web-search je nebo code-interpreter), connections (projektová připojení, jako je server MCP vzdáleného nástroje nebo index vyhledávání), a skills (odkazy na stávající dovednosti projektu). Slot tools je deklarován před manifestem. Přidání propojení a odkazů na dovednosti přírůstkově pomocí azd ai toolbox connection add a azd ai toolbox skill add.

Kompletní příklad

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 }}"

Nahrazení proměnných

Nahrazení probíhá ve dvou vrstvách: parametry manifestu se přeloží v inicializační době a proměnné prostředí se přeloží za běhu nebo v době nasazení. Jeden definiční soubor pak může fungovat ve všech vašich azd prostředích.

Syntax	Vyřešeno při	Podle čeho
`{{ param_name }}`	`azd ai agent init`	Hodnoty parametrů manifestu byly vyzvány od uživatele.
`${VAR_NAME}`	`azd deploy` nebo `azd ai agent run`	`azd` proměnné prostředí z `.azure/<env>/.env`.

Váš názor

Byla tato stránka užitečná?

Poslední aktualizace v 2026-10-16

Referenční informace ke schématu agent.yaml

Typy schémat

AgentDefinition

AgentManifest

ContainerAgent

Kdy použít manifest nebo definici

Pole nejvyšší úrovně

template (ContainerAgent)

protokoly

environment_variables

parameters

resources

Prostředek modelu

Prostředek připojení

Prostředek panelu nástrojů

Kompletní příklad

Nahrazení proměnných

Související obsah

Váš názor

Další materiály