agent.yaml-Schemareferenz

Important

Elemente, die in diesem Artikel als Vorschau gekennzeichnet sind, befinden sich derzeit in der Vorschau. Diese Vorschau wird ohne Vereinbarung auf Serviceebene bereitgestellt, und Microsoft wird sie für Produktionsworkloads nicht empfohlen. Manche Features werden möglicherweise nicht unterstützt oder sind nur eingeschränkt verwendbar. Weitere Informationen finden Sie unter Supplementale Nutzungsbedingungen für Microsoft Azure Previews.

Note

Agentmanifeste (agent.manifest.yaml) und eigenständige Agentdefinitionen (agent.yaml) sind veraltet. Ab den Foundry-Erweiterungen azd (azure.ai.agents 1.0.0-beta.1) leben alle gehosteten Agent-Konfigurationen in einem einzigen azure.yaml. Siehe Autor azure.yaml für gehostete Agents und azure.yaml-Referenz für gehostete Agents.

Die AgentSchema-Spezifikation ist ein offener Standard zum Definieren von KI-Agents. Wenn Sie gehostete Agents erstellen, arbeiten Sie in erster Linie mit drei Schematypen der obersten Ebene: AgentDefinition, AgentManifest und ContainerAgent. Dieses ältere Schemamodell für AgentManifest, AgentDefinition, agent.manifest.yamlund agent.yaml wird für Referenz beibehalten und wird von azure.yaml. Das Schema ist nicht spezifisch für ein Tool. Die Azure Developer CLI (azd) und das Microsoft Foundry Toolkit für Visual Studio Code beide verwenden es.

Das Schema wird in zwei Dateikontexten mit unterschiedlichen Benennungskonventionen angezeigt:

  • agent.manifest.yaml ist ein AgentManifest, eine parametrisierte Vorlage, die von Legacybeispielen verwendet wird. Die aktuelle azd ai agent init -t Initialisierung erfordert ein azure.yaml Projektdokument und lehnt AgentManifest-Wrapper ab.
  • agent.yamlist eine AgentDefinition, die konkrete Konfiguration, die die Legacyinitialisierung in Ihr Projekt geschrieben hat.src/<agent>/agent.yaml

Beide Dateien beschreiben , was ein Agent ist: sein Modell, Tools, Protokolle, Umgebung und Ressourcen. Dies unterscheidet sich von azure.yamldem, was beschreibt, wie Azure Ressourcen bereitgestellt und bereitgestellt werden. Die Referenz finden Sie in der azure.yamlAzure.yaml-Referenz für gehostete Agents.

Schematypen

AgentDefinition

Ein AgentDefinition ist eine konkrete Spezifikation eines Agents, der zur Ausführung bereit ist. Es beschreibt eine einzelne Agentinstanz mit einer bestimmten Konfiguration und keine {{ parameter }} Vorlagenplatzhalter.

Jeder AgentDefinition verfügt über ein kind Feld, das den Agenttyp bestimmt.

Kind Description
prompt Ein eingabeaufforderungsbasierter Agent, der nur über Anweisungen konfiguriert ist.
hosted Ein containerisierter Agent, der als Containerimage bereitgestellt wird.
workflow Ein Orchestrierungs-Agent, der andere Agents koordiniert.

Eine generierte AgentDefinition kann weiterhin Verweise enthalten ${VAR_NAME} . Hierbei handelt azd es sich um Umgebungsvariablenplatzhalter, nicht um Einen Teil der AgentSchema-Spezifikation. Sie ermöglichen es einer einzelnen Definitionsdatei, die über mehrere azd Umgebungen hinweg funktioniert, indem Werte aus der Datei jeder Umgebung .azure/<env>/.env zur Bereitstellungszeit aufgelöst werden.

AgentManifest

Ein AgentManifest ist eine parametrisierte Vorlage zum dynamischen Erstellen von Agents. Es umschließt eine AgentDefinition als Feld template und fügt Folgendes hinzu:

  • parameters: Werte, die zur Erstellungszeit aufgefordert oder eingefügt werden, mithilfe der {{ parameter }} Ersetzungsyntax.
  • resources: externe Abhängigkeiten wie Modellbereitstellungen, Toolboxen oder Verbindungen.

Verwenden Sie einen AgentManifest, wenn Sie wiederverwendbare Vorlagen benötigen oder ähnliche Agents mit unterschiedlichen Konfigurationen bereitstellen möchten. Wenn Sie ausgeführt werden azd ai agent init, zeigen Sie in der Regel auf ein Manifest, entweder durch Auswählen einer Vorlage oder Bereitstellen einer URL. Der Init-Prozess fordert Parameterwerte auf und generiert einen AgentDefinition.

ContainerAgent

Ein ContainerAgent ist eine AgentDefinition mit kind: hosted. Sie erweitert die Basisdefinition mit containerspezifischen Feldern und befindet template sich innerhalb eines AgentManifests, wenn Sie einen gehosteten Agent erstellen.

Gründe für die Verwendung eines Manifests oder einer Definition

Verwenden eines Manifests, wenn Verwenden einer Definition, wenn
Sie veröffentlichen eine wiederverwendbare Agent-Vorlage für andere, um instanziieren zu können. Sie stellen einen bestimmten, einzelzweckigen Agent bereit.
Sie möchten, dass Benutzer das Modell, die Tools oder Verbindungen gleichzeitig konfigurieren. Alle Konfigurationswerte sind bekannt und behoben.
Sie erstellen eine Beispiel- oder Startvorlage. Sie haben bereits eine generierte Definition ausgeführt azd ai agent init .

Die meisten Entwickler beginnen mit einem Manifest azd ai agent init und arbeiten dann mit der generierten Definition. Vorlagenautoren und Beispielverleger sind die primären Ersteller von Manifesten.

Felder auf oberster Ebene

Der folgende Verweis dokumentiert die Manifestfelder, die eine Obermenge der Definitionsfelder sind.

Field Typ Erforderlich Description
name string Yes Name des Agentmanifests.
description string No Beschreibung des Agents.
metadata object No Zusätzliche Metadaten, z tags. B. .
template ContainerAgent Yes Die Agentdefinitionsvorlage.
parameters object No Konfigurierbare Parameter, die während des Init-Objekts aufgefordert werden.
resources array Yes Ressourcen, die vom Agent benötigt werden.

Vorlage (ContainerAgent)

Das template Feld definiert den gehosteten Container-Agent.

Field Typ Erforderlich Description
name string Yes Name des Agenten.
kind string Yes Muss für gehostete Agents sein hosted .
protocols array Yes Protokollunterstützung.
environment_variables array No Umgebungsvariablen für den Container.
resources object No Cpu- und Arbeitsspeicherressourcen des Containers.
image string No Vordefinierter Containerimagepfad.
dockerfilePath string No Pfad zur Dockerfile-Datei.

Protokolle

protocols:
  - protocol: responses    # OpenAI Responses API
    version: 2.0.0
Protocol Description
responses OpenAI-Antwort-API. Umfasst die Verwaltung des Unterhaltungsverlaufs.
invocations Benutzerdefiniertes Nutzlastprotokoll. Keine integrierte Unterhaltungsverwaltung.

Die vollständige Protokollspezifikation finden Sie unter Vertrag für gehostete Agent-Laufzeit.

environment_variables

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

Die ${ } Syntax verweist auf azd Umgebungsvariablen aus .azure/<env>/.env.

Note

Deklarieren FOUNDRY_PROJECT_ENDPOINT Sie nicht in environment_variables. Die Plattform fügt sie automatisch in gehostete Container ein und azd ai agent run legt sie für die lokale Entwicklung fest. Das Deklarieren ist hier redundant und riskiert, den Plattformwert zu schattieren.

parameters

Parameter werden während azd ai agent initder Eingabeaufforderung angezeigt. Wird für vertrauliche Werte verwendet secret: true .

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

resources

Ressourcen definieren, was der Agent benötigt. Die folgenden Shapes beschreiben, welche Manifeste deklarieren und was azd ai agent init in Ihr Projekt geschrieben wird. Verwalten Sie nach dem Initieren die gleichen projektbezogenen Ressourcen zur Laufzeit mit direkten CLI-Befehlen: azd ai connection, , , azd ai toolbox, azd ai skillund azd ai routine.

Note

Das Schema enthält kein Kompetenzfeld. Die azd ai agent initBefehle azd ai agent runund azd up Befehle können nicht automatisch heruntergeladen werden. Verwalten Sie Fähigkeiten als Ressourcen auf Projektebene, azd ai skill und verbinden Sie sie selbst mit Ihrer Agent-Laufzeit.

Modellressource

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

Verbindungsressource

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

Toolbox-Ressource

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

Eine Toolboxversion enthält drei Arten von Einträgen: Unformatierte tools Einträge (integrierte Funktionen wie web-search oder code-interpreter), connections (Projektverbindungen wie einen MCP-Server für Remotetools oder einen Suchindex) und skills (Verweise auf vorhandene Projektkompetenzen). Der tools Steckplatz wird im Manifest vorab deklariert. Hinzufügen von Verbindungen und Qualifikationsbezügen inkrementell mit azd ai toolbox connection add und azd ai toolbox skill add.

Vollständiges Beispiel

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

Variablenersetzung

Die Ersetzung erfolgt in zwei Ebenen: Manifestparameter werden zur Initzeit aufgelöst, und Umgebungsvariablen werden zur Laufzeit oder Bereitstellung aufgelöst. Eine Definitionsdatei kann dann in allen Umgebungen azd funktionieren.

Syntax Behoben, wenn Nach dem, was
{{ param_name }} azd ai agent init Manifestparameterwerte, die vom Benutzer aufgefordert werden.
${VAR_NAME} azd deploy oder azd ai agent run azd Umgebungsvariablen aus .azure/<env>/.env.

Verwandte Inhalte

  • Zuletzt aktualisiert um