ホストされるエージェントの azure.yaml リファレンス

azure.yaml ファイルは、ホストされたエージェント プロジェクトの単一の Azure Developer CLI (azd) プロジェクト構成です。 Foundry リソース (プロジェクト、モデルのデプロイ、接続、ツールボックス、スキル、ルーチン、エージェント自体) を一連のサービスとして宣言し、それらをプロビジョニングしてデプロイする方法を azd に指示します。 この統合ファイルは、 agent.manifest.yaml と agent.yamlの間で構成を分割する以前の 2 ファイル モデルに置き換えられます。

このファイルを段階的に作成および作成する方法については、 ホストされているエージェントの azure.yaml の作成に関するページを参照してください。

azd で azure.yaml を使用する方法

Azure Developer CLI は、開発者からクラウドへのワークフローを合理化します。 Foundry プロジェクト、モデル デプロイ、コンテナー レジストリなどのAzureリソースのプロビジョニングと、それらのリソースへのコードのデプロイという 2 つの処理が行われます。 ホストされるエージェントの場合、 azure.ai.agents 拡張機能は、 azd ai agent init や azd ai agent runなどのエージェント固有のコマンドを追加します。

すべての azd プロジェクトのルートに azure.yaml ファイルがあります。 エージェント プロジェクトの場合、このファイルはエージェント構成とデプロイ構成の両方の信頼のソースです。

Environments

環境とは、特定の展開の設定を格納する名前付き構成 ( dev、 staging、 prodなど) です。 各環境では、Azureサブスクリプションと場所、リソース グループとリソース名、および設定したカスタム変数が追跡されます。 設定は、 .azure/<env-name>/.envにローカルに格納されます。 同じプロジェクトに対して複数の環境を使用できます。

コア コマンド

拡張機能の互換性

azure.ai.agents拡張機能は、azure.ai.agent ホストを提供します。 azure.ai.projects拡張機能は、azure.ai.project ホストとmicrosoft.foundry インフラストラクチャ プロバイダーを提供します。 azure.ai.projects バージョン 1.0.0-beta.4 以降でバージョン 1.0.0-beta.8 以降azure.ai.agents使用します。 インストールとアップグレードの手順については、「Azure Developer CLI Foundry 拡張機能のインストール」を参照してください。

互換性のある最小バージョンは、 azure.yamlで宣言できます。

requiredVersions:
    azd: ">=1.27.1"
    extensions:
        azure.ai.agents: ">=1.0.0-beta.8"
        azure.ai.projects: ">=1.0.0-beta.4"

サービス プロバイダーのライフサイクル

プロジェクトに接続、ツールボックス、スキル、またはルーチンが含まれている場合は、 microsoft.foundry メタ パッケージをインストールします。 対応する azure.ai.* ホストを実装するプロバイダー拡張機能がインストールされます。

プロジェクトと接続プロバイダーは、 azd provision中に構成を適用します。 エージェント、ツールボックス、スキル、ルーチン プロバイダーは、 azd deploy中に構成を適用します。 azd upを実行して、両方のフェーズを完了します。 azure.yamlからデータ プレーン サービスを削除すると、azdが管理できなくなります。リモート リソースが不要になったら、リモート リソースを個別に削除します。

• azd down - 現在の環境で Foundry プロジェクトが作成されたときにリソース グループを削除します。 既存のプロジェクトとそのリソースはそのままにします。 |
• azd env set - azd env set FOUNDRY_MODEL_NAME=gpt-5.4-miniなどの環境変数を設定します。 |

分割サービス モデル

servicesでは、各エントリは、宣言する Foundry リソースの種類を識別するhost フィールドを持つ名前付きサービスです。 サービスは、 uses フィールドを介して相互に参照します。これにより、プロビジョニング時とデプロイ時に解決 azd 依存関係グラフが形成されます。 一般的なプロジェクトには、モデルのデプロイを所有する 1 つの azure.ai.project サービスと、それに依存する 1 つの azure.ai.agent サービスがあります。

最小限の例

# 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}
        container:
            resources:
                cpu: "0.25"
                memory: 0.5Gi

完全な例

次のプロジェクトは、接続、ツールボックス、プライベート ネットワークを追加します。

# 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
        protocols:
            - protocol: responses
              version: 2.0.0
        container:
            resources:
                cpu: "1.0"
                memory: 2Gi

infra:
    provider: bicep
    path: ./infra

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

azure.ai.project サービス

プロジェクト サービスは Foundry プロジェクトをプロビジョニングまたは接続し、そのモデルデプロイを所有します。

デプロイ

展開エントリには、外部ファイル ( - $ref: ./deployments/embeddings.yaml) を含めることもできます。

ネットワーク

networkを設定して、ネットワークで保護されたアカウントをプロビジョニングします。 peSubnet フィールドが必要であり、アカウントのプライベート エンドポイントを確立します。 エージェント ランタイムを独自のサブネットに挿入する (独自の仮想ネットワークを持ち込む) agentSubnetを追加するか、Microsoftマネージド ネットワークを使用するためにそれを省略します。 完全なチュートリアルについては、 ホストされたエージェントのプライベート ネットワークに関するページを参照してください。

プライベート ネットワーク構成

azure.ai.project サービスのnetworkを使用して、アカウントのプライベート エンドポイントとエージェントエグレスを構成します。 次の例では、エージェント ランタイムにカスタマー マネージド サブネットを使用します。

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}

プライベート ネットワークでは、アカウントのパブリック データ プレーン アクセスが無効になります。 この構成では、自動的に作成されたAzure Container Registryはサポートされていません。 ソース コードのデプロイを使用するか、事前構築済みの imageを指定します。

azure.ai.agent サービス

エージェント サービスには、エージェント定義とそのビルドとデプロイの設定が含まれます。 これは、古い agent.yamlを置き換えるサービスです。

agentCard.skills と azure.ai.skill

agentCard.skills では、検出カード内のエージェントの機能について説明します。 クライアントのメタデータを提供し、再利用可能な Foundry スキルを作成またはアタッチしません。 各カード スキルには、 id、 name、および descriptionが必要です。

azure.ai.skill サービスは、命令とオプションで許可されているツールからバージョン管理されたスキルを作成します。 servicesで個別に宣言します。uses リストは依存関係の順序を制御しますが、agentCard.skillsに設定したり、エージェントにスキルをアタッチしたりすることはありません。 探索メタデータには agentCard.skills を使用し、再利用可能な手順については azure.ai.skill を使用します。

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

探索カードを完了する

クライアントがより豊富な探索メタデータを必要とする場合は、 version、 tags、および examples を追加します。 カードには、 description と少なくとも 1 つのスキルが必要です。 各スキルには、 id、 name、および 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.

責任ある AI ポリシー

policiesを使用して、責任ある AI ポリシーをホストされるエージェントに関連付けます。 raiPolicyNameポリシーの完全な ARM リソース ID に設定します。

policies:
    - type: rai_policy
      raiPolicyName: ${RAI_POLICY_RESOURCE_ID}

rai_policyの種類とraiPolicyNameが必要です。 拡張機能は、一覧の最初の有効なポリシーを、ホストされたエージェントの責任ある AI 構成に適用します。 ポリシーの作成と管理のガイダンスについては、「 ホストされているエージェントにガードレールを追加する」を参照してください。

メモリストア

memoryStoresを使用して、デプロイ前に Foundry メモリ ストアを作成または再利用します。 各ストアには、既存のチャット モデルと埋め込みモデルのデプロイ名が必要です。

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

デプロイ中、既存のストアは更新されません。 宣言された定義が既存のストアと異なる場合、 azd は違いを報告します。 メモリ ストアを宣言しても、エージェント コードが変更されたり、メモリ ツールが自動的にアタッチされたりすることはありません。 メモリ検索ツールまたはメモリ ストア API を使用して、アプリケーションをメモリ ストアに接続します。 詳細については、「 エージェントでメモリを使用する」を参照してください。

エージェント エンドポイントを構成する

agentEndpointを使用して、エージェント エンドポイントによって発行されたプロトコルと承認スキームを構成します。 公開する機能を他のエージェントが検出できるように、A2A エンドポイントでエージェント カードを使用します。

agentEndpoint:
    protocols:
        - responses
        - a2a
    authorizationSchemes:
        - type: Entra

エンドポイント トラフィックを受信するエージェントのバージョンを制御する必要がある場合は、 versionSelector.versionSelectionRules を定義することもできます。 エージェント サービスは、デプロイ中にエンドポイント プロトコルと承認の値を検証します。

protocols

protocols:
    - protocol: responses
      version: 2.0.0

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

追加のランタイム プロトコルとアクティビティ エンドポイント

responses、invocations、およびa2aに加えて、ホストされるエージェントは、WebSocket 呼び出しのinvocations_wsと、Microsoft 365および Teams アクティビティ シナリオのactivityをサポートします。

protocols:
    - protocol: invocations_ws
      version: 2.0.0
    - protocol: activity
      version: 2.0.0

アクティビティ エージェントの場合は、パブリック エンドポイント構成にactivityを追加し、必要なBot Service承認スキームを使用します。

agentEndpoint:
    protocols:
        - activity
    authorizationSchemes:
        - type: BotServiceRbac

アクティビティ プロトコルは、同じエージェント エンドポイント上の他のプロトコルと共存できます。 ランタイム プロトコルの動作については、「 ホストされるエージェントとは」を参照してください。

env

env:
    MICROSOFT_FOUNDRY_MODEL_DEPLOYMENT_NAME: ${MICROSOFT_FOUNDRY_MODEL_DEPLOYMENT_NAME}
    LOG_LEVEL: info

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

プラットフォーム環境、ID、エンドポイント

プラットフォームは、 FOUNDRY_ プレフィックスと AGENT_ プレフィックスを予約します。 FOUNDRY_PROJECT_ENDPOINTなどのプラットフォーム変数をアプリケーション コードから読み取りますが、envで定義したりオーバーライドしたりしないでください。 エージェント定義の環境値は文字列です。

デプロイされた各ホステッド エージェントは、専用のMicrosoft Entra ID エージェント ID とエンドポイントを受け取ります。 エージェント サービスに identity ブロックを追加しないでください。 エージェント ID は、既定でプロジェクト エンドポイントとセッション ストレージを使用できます。 エージェントが外部リソースにアクセスする必要がある場合は、ID に追加のロールを割り当てます。 詳細については、 ホストされているエージェントのアクセス許可のリファレンスを参照してください。

宣言するプロトコルによって、デプロイ後にアクティブなエンドポイントが決まります。 azd ai agent showを実行して、デプロイされたエージェントとそのエンドポイント URL を調べます。

デプロイ後、 azd は、 <SERVICE>の代わりに正規化されたサービス名を使用して、次の値をアクティブな環境に書き込みます。

• AGENT_<SERVICE>_NAME
• AGENT_<SERVICE>_VERSION
• AGENT_<SERVICE>_ENDPOINT
• AGENT_<SERVICE>_<PROTOCOL>_ENDPOINT 有効な responses、 invocations、および invocations_ws プロトコルの場合

アプリケーションまたはオートメーションで呼び出し URL が必要な場合は、プロトコル固有の出力を使用します。 ベース エンドポイントは、セッション管理操作用にデプロイされたエージェントのバージョンを識別します。

コンテナ

container:
    resources:
        cpu: "0.25"
        memory: 0.5Gi

cpuから"0.25"に"4.0"を設定し、memoryから0.5Giまで8.0Giします。

ソース コードのデプロイ

ソース コードをコンテナー イメージではなく ZIP としてデプロイするように codeConfiguration を設定します。 エントリ ポイントのファイル名またはアセンブリ名を 1 つ指定します。 azd は、hosted-agent バージョンを作成するときに、それを選択したランタイムと組み合わせます。

codeConfiguration:
    runtime: python_3_13
    entryPoint: main.py
    dependencyResolution: remote_build

remote_buildを使用してプロジェクト ソースから依存関係を復元するか、ZIP に Linux 互換の依存関係が含まれている場合はbundledを使用します。 codeConfigurationをイメージ ベースのコンテナー構成と組み合わせないでください。 パッケージ化と依存関係のガイダンスについては、「 ソース コードからホストされるエージェントをデプロイする」を参照してください。

コンテナー ビルドと事前構築済みイメージ

projectの下のDockerfileを使用してコンテナー イメージをビルドするか、事前構築済みのイメージをデプロイするimageを設定します。

image: myregistry.azurecr.io/agents/researcher:1.2.3

Dockerfileとimageの両方を使用できる場合は、対話型の展開プロンプトで事前構築済みのイメージを選択します。 無人展開の場合は、AZD_AGENT_SKIP_ACRをアクティブなazd環境でtrueに設定して、構成済みのイメージを選択します。 レジストリのアクセス許可とプライベート レジストリの展開については、「プライベート Azure Container Registryを使用してホストされるエージェントをデプロイする」を参照してください。

メタデータとスキーマの制限事項

デプロイされたエージェント メタデータには文字列値を使用します。 authorsメタデータ値には、文字列の一覧を指定できます。 displayName、inputSchema、またはoutputSchemaに依存してデプロイされたホステッド エージェントを構成しないでください。統合構成はこれらのフィールドを受け入れますが、hosted-agent 作成要求では使用されません。

azure.ai.connection サービス

接続により、プロジェクトが外部リソースにリンクされます。 サービス キーは接続名であり、サービスは usesを介してプロジェクトに依存します。

github-conn:
    host: azure.ai.connection
    uses:
        - ai-project
    category: RemoteTool
    target: https://api.githubcopilot.com/mcp
    authType: CustomKeys
    credentials:
        Authorization: ${GITHUB_PAT}

接続の変更は、azd deployではなく、azd provision中に適用されます。 資格情報の値をazd環境に格納し、シークレットをazure.yamlに配置するのではなく、${VAR}で参照します。

azure.ai.toolbox サービス

ツールボックスは、エージェントが参照するツールの名前付きバンドルです。 接続に基づくツールでは、azure.ai.connection フィールドを使用してconnection サービスに名前を付けます。

research-tools:
    host: azure.ai.toolbox
    uses:
        - ai-project
        - search-conn
    tools:
        - type: azure_ai_search
          connection: search-conn
        - type: code_interpreter

エージェントは、ツールボックス サービス名を uses とその toolboxes リストの両方に追加して、ツールボックスを参照します。

ツールボックス エンドポイントを使用する

分割サービス プロジェクトでは、 uses によって配置順序が制御されます。 アプリケーションは、実行時にツールボックスの MCP エンドポイントに接続します。 envを介してツールボックス名またはエンドポイントをアプリケーションに渡し、エージェント コードのFOUNDRY_PROJECT_ENDPOINTからコンシューマー エンドポイントを構築します。 エンド ツー エンドの例については、「 ホストされたエージェントでツールボックスを使用する」を参照してください。

azure.ai.skill と azure.ai.routine サービス

azure.ai.skill サービスは、エージェントが名前で参照する再利用可能な動作ガイドラインを定義します。 azure.ai.routine サービスは、トリガー (スケジュールまたはイベント) とエージェントを呼び出すアクションを定義します。 どちらも、 usesで使用するリソースに依存します。 エージェント用ツールの追加の詳細については、「 Foundry のツールボックスとは」 および「ルーチンを 使用する」を参照してください。

スキルとルーチンは個別のリソースです。 いずれかのサービスを宣言すると、そのライフサイクルが制御されますが、エージェントにスキルが自動的にアタッチされたり、ルーチン アクション ターゲットが推論されたりすることはありません。 使用しているアプリケーションまたはルーチンアクションを明示的に構成します。

用途を含む依存関係

uses フィールドは、特定のサービスが依存するサービスを宣言します。 azd では、このグラフを使用して、プロビジョニングの順序付けや、エージェントの接続やツールボックスなどのワイヤリファレンスへの接続を行います。

uses:
    - ai-project
    - search-conn
    - research-tools

ファイルインクルードと$ref

サービスまたはリストのエントリは、外部の YAML または JSON ファイルへの参照に置き換えることができます。 相対パスは、 $refを含むファイルから解決されます。 リモート URL はサポートされていません。

services:
    triage:
        host: azure.ai.agent
        uses:
            - ai-project
        $ref: ./agents/triage.yaml

ファイルインクルードを使用すると、大規模なエージェント定義を独自のファイルに保持し、プロジェクト間で定義を共有できます。

host、uses、project、language、image、dockerなど、サービス $refを使用する場合は、ルート azure.yaml エントリにコア サービス フィールドを保持します。 参照先のマッピングに、 kind、 name、 description、 protocolsなどのプロバイダー所有の定義フィールドを配置します。 $ref はローカルの YAML または JSON ファイルを再帰的に解決します。URL と参照サイクルはサポートされていません。

変数の置換

azure.yamlでは、次の 2 つの置換構文を使用できます。

インフラストラクチャとデプロイ モード

既定ではBicepレス

azd ai agent init は既定では bicep-less です。 infra/ ディレクトリは書き込まれません。 azd は、プロビジョニング時に azure.yaml サービスからインフラストラクチャを合成します。 コードとしてのインフラストラクチャ ファイルを具体化するには、それらを取り出します。

infraにazure.yamlが存在する場合、azdはインフラストラクチャを合成する代わりにこれらのファイルを使用します。

デプロイ モード

ホストされるエージェントは、次の 2 つのモードのいずれかでデプロイされます。

ソース デプロイの場合、エージェント サービスの codeConfiguration フィールドはランタイムとエントリ ポイントをキャプチャします。 事前構築済みイメージの場合は、エージェント サービスに image フィールドを設定し、Dockerfile ビルドをスキップします。

レガシ構成の移行

以前のエージェント定義では、環境変数を config: envの下に入れ子にすることができます。 統合 azure.yamlで、 env マッピングをエージェント サービスに移動します。

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

JSON スキーマの検証

IDE オートコンプリートのスキーマ参照を追加します。

# yaml-language-server: $schema=https://raw.githubusercontent.com/Azure/azure-dev/main/schemas/v1.0/azure.yaml.json

関連するコンテンツ

• ホストされているエージェントの azure.yaml を作成する
• Azure Developer CLI を使用してホステッド エージェント プロジェクトを初期化する
• Azure Developer CLI を使用したホステッド エージェント インフラストラクチャ
• ホステッド エージェント ランタイム コントラクト
• ホスト型エージェントとは何ですか？