agent.yaml スキーマリファレンス

Important

この記事でプレビューとしてマークされているアイテムは、現在プレビュー段階です。このプレビューはサービスレベルアグリーメントなしで提供され、Microsoftは運用環境のワークロードには推奨されません。特定の機能がサポートされていないか、機能が制限されている可能性があります。詳細については、「 Microsoft Azure プレビューの追加使用条件」を参照してください。

Note

エージェントマニフェスト (agent.manifest.yaml) とスタンドアロンエージェント定義 (agent.yaml) は非推奨です。 Foundry azd 拡張機能 (azure.ai.agents 1.0.0-beta.1) の時点では、ホストされているすべてのエージェント構成は 1 つの azure.yamlに存在します。ホストされるエージェントの場合は azure.yaml の作成、ホストされるエージェントの場合は azure.yaml リファレンスを参照してください。

AgentSchema 仕様は、AI エージェントを定義するためのオープン標準です。ホストされるエージェントをビルドするときは、主に 、AgentDefinition、 AgentManifest、 ContainerAgent の 3 種類の最上位レベルのスキーマを使用します。 AgentManifest、AgentDefinition、agent.manifest.yaml、およびagent.yamlのこのレガシスキーマモデルは、参照用に保持され、azure.yamlに置き換えられます。スキーマは、1 つのツールに固有ではありません。 Azure Developer CLI (azd) と Microsoft Foundry Toolkit for Visual Studio Codeはどちらも使用します。

スキーマは、異なる名前付け規則を持つ 2 つのファイルコンテキストで表示されます。

agent.manifest.yaml は AgentManifest であり、レガシサンプルで使用されるパラメーター化されたテンプレートです。現在の azd ai agent init -t 初期化では、 azure.yaml プロジェクトドキュメントが必要であり、AgentManifest ラッパーが拒否されます。
agent.yaml は AgentDefinition です。これは、従来の初期化が src/<agent>/agent.yamlでプロジェクトに書き込んだ具体的な構成です。

どちらのファイルもエージェントとは 何かを 記述します。エージェントのモデル、ツール、プロトコル、環境、リソースです。これは、Azureリソースをプロビジョニングしてデプロイするazure.yamlを説明するとは異なります。 azure.yamlリファレンスについては、ホストされているエージェントの azure.yaml リファレンスを参照してください。

スキーマの種類

AgentDefinition

AgentDefinition は、実行する準備ができているエージェントの具体的な仕様です。特定の構成を持ち、テンプレートプレースホルダーを {{ parameter }} しない単一のエージェントインスタンスについて説明します。

すべての AgentDefinition には、エージェントの種類を決定する kind フィールドがあります。

サブタイプ	Description
`prompt`	指示によってのみ構成されたプロンプトベースのエージェント。
`hosted`	コンテナーイメージとしてデプロイされたコンテナー化されたエージェント。
`workflow`	他のエージェントを調整するオーケストレーションエージェント。

生成された AgentDefinition には、引き続き ${VAR_NAME} 参照を含めることができます。これらは環境変数プレースホルダー azd であり、AgentSchema 仕様の一部ではありません。デプロイ時に各環境のazd ファイルの値を解決することで、1 つの定義ファイルを複数の.azure/<env>/.env環境で機能させます。

AgentManifest

AgentManifest は、エージェントを動的に作成するためのパラメーター化されたテンプレートです。 AgentDefinition を template フィールドとしてラップし、次の値を追加します。

parameters: {{ parameter }} 置換構文を使用して、作成時にプロンプトまたは挿入される値。
resources: モデルのデプロイ、ツールボックス、接続などの外部依存関係。

再利用可能なテンプレートが必要な場合、または異なる構成で同様のエージェントをデプロイする場合は、AgentManifest を使用します。 azd ai agent initを実行するときは、通常、テンプレートを選択するか URL を指定してマニフェストをポイントします。 init プロセスはパラメーター値の入力を求め、AgentDefinition を生成します。

ContainerAgent

ContainerAgent は、 kind: hostedを持つ AgentDefinition です。これにより、コンテナー固有のフィールドを使用して基本定義が拡張され、ホストされるエージェントを構築するときに AgentManifest 内の template になります。

マニフェストまたは定義を使用する場合

次の場合にマニフェストを使用する	次の場合に定義を使用する
他のユーザーがインスタンス化できるように、再利用可能なエージェントテンプレートを発行します。	特定の単一目的エージェントをデプロイします。
ユーザーは、モデル、ツール、または接続を初期化時に構成する必要があります。	すべての構成値は既知であり、固定されています。
サンプルまたはスターターテンプレートを作成します。	既に `azd ai agent init` を実行しており、定義が生成されています。

ほとんどの開発者は、マニフェストから azd ai agent init を開始し、生成された定義を操作します。テンプレート作成者とサンプル発行元は、マニフェストの主な作成者です。

最上位レベルのフィールド

以下のリファレンスでは、定義フィールドのスーパーセットであるマニフェストフィールドについて説明します。

Field	タイプ	必須	Description
`name`	文字列	はい	エージェントマニフェストの名前。
`description`	文字列	いいえ	エージェントの説明。
`metadata`	オブジェクト	いいえ	`tags`などの追加のメタデータ。
`template`	ContainerAgent	はい	エージェント定義テンプレート。
`parameters`	オブジェクト	いいえ	init 中にプロンプトが表示される構成可能なパラメーター。
`resources`	アレイ	はい	エージェントに必要なリソース。

template (ContainerAgent)

template フィールドは、ホストされるコンテナーエージェントを定義します。

Field	タイプ	必須	Description
`name`	文字列	はい	エージェント名。
`kind`	文字列	はい	ホストされるエージェントの `hosted` する必要があります。
`protocols`	アレイ	はい	プロトコルのサポート。
`environment_variables`	アレイ	いいえ	コンテナーの環境変数。
`resources`	オブジェクト	いいえ	コンテナーの CPU リソースとメモリリソース。
`image`	文字列	いいえ	事前構築済みのコンテナーイメージパス。
`dockerfilePath`	文字列	いいえ	Dockerfile へのパス。

プロトコル

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

プロトコル	Description
`responses`	OpenAI Responses API。会話履歴の管理が含まれます。
`invocations`	カスタムペイロードプロトコル。組み込みの会話管理はありません。

完全なプロトコル仕様については、ホストされるエージェントのランタイムコントラクトに関するページを参照してください。

environment_variables

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

${ }構文は、azdの環境変数.azure/<env>/.env参照します。

Note

FOUNDRY_PROJECT_ENDPOINTでenvironment_variablesを宣言しないでください。プラットフォームによってホストされたコンテナーに自動的に挿入され、 azd ai agent run はローカル開発用に設定されます。ここで宣言することは冗長であり、プラットフォームの価値をシャドウするリスクがあります。

parameters

パラメーターは、 azd ai agent init中にプロンプトが表示されます。機密性の高い値には secret: true を使用します。

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

resources

リソースは、エージェントに必要なものを定義します。次の図形は、マニフェストが宣言する内容と、プロジェクトに書き込む azd ai agent init について説明しています。初期化後、 azd ai connection、 azd ai toolbox、 azd ai skill、 azd ai routineなどの直接 CLI コマンドを使用して、実行時に同じプロジェクトスコープのリソースを管理します。

Note

スキーマにはスキルフィールドは含まれません。 azd ai agent init、azd ai agent run、およびazd upコマンドでは、スキルは自動ダウンロードされません。 azd ai skillを使用してプロジェクトレベルのリソースとしてのスキルを管理し、自分でエージェントランタイムに接続します。

モデルリソース

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

接続リソース

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

ツールボックスリソース

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

ツールボックスバージョンには、生の tools エントリ ( web-search や code-interpreterなどの組み込み機能)、 connections (リモートツール MCP サーバーや検索インデックスなどのプロジェクト接続)、 skills (既存のプロジェクトスキルへの参照) の 3 種類のエントリが含まれています。 tools スロットは、マニフェストの前に宣言されます。 azd ai toolbox connection addとazd ai toolbox skill addを使用して、接続とスキル参照を段階的に追加します。

完全なコード例

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

変数の置換

置換は 2 つのレイヤーで行われます。マニフェストパラメーターは初期化時に解決され、環境変数は実行時またはデプロイ時に解決されます。その後、すべての azd 環境で 1 つの定義ファイルを使用できます。

構文	解決日時	何によって
`{{ param_name }}`	`azd ai agent init`	ユーザーから求められたマニフェストパラメーター値。
`${VAR_NAME}`	`azd deploy` または `azd ai agent run`	`azd` `.azure/<env>/.env`からの環境変数。

フィードバック

このページはお役に立ちましたか?

最終更新: 2026-07-07

agent.yaml スキーマ リファレンス

スキーマの種類

AgentDefinition

AgentManifest

ContainerAgent

マニフェストまたは定義を使用する場合

最上位レベルのフィールド

template (ContainerAgent)

プロトコル

environment_variables

parameters

resources

モデル リソース

接続リソース

ツールボックス リソース

完全なコード例

変数の置換

関連するコンテンツ

フィードバック

その他のリソース

agent.yaml スキーマリファレンス

モデルリソース

ツールボックスリソース