機能ホスト

メモ

機能ホストの更新はサポートされていません。機能ホストを変更するには、既存のホストを削除し、新しい構成で再作成する必要があります。

機能ホストは、Microsoft Foundry アカウントと Foundry プロジェクトスコープの両方で構成するサブリソースです。次のようなエージェントデータを格納して処理する場所を Foundry Agent Service に伝えます。

会話履歴
ファイルのアップロード
ベクターストア

前提条件

Microsoft Foundry プロジェクト
エージェントデータ (標準エージェントのセットアップ) に独自のリソースを使用する場合は、必要なAzureリソースと接続を作成します。
- 独自のリソースを使用する
- プロジェクトに新しい接続を追加する
必要なアクセス許可:
- 機能ホストを作成するための Foundry アカウントの共同作成者ロール
- User Access Administrator または Owner ロールを使用して、Azure リソースへのアクセスを割り当てます (標準エージェントセットアップの場合)
- 詳細については、Microsoft Foundry の Required permissions および Role ベースのアクセス制御 (RBAC) に関するページを参照してください。

機能ホストを使用する理由

独自のAzure リソースを使用できるキャパビリティホストは、既定のMicrosoftマネージドプラットフォームリソースの代わりに使用できます。これにより、次の操作が行われます。

データ主権 - Azure サブスクリプション内のすべてのエージェントデータを保持します。
セキュリティ制御 - 独自のストレージアカウント、データベース、および検索サービスを使用します。
コンプライアンス - 特定の規制または組織の要件を満たします。

機能ホストはどのように動作しますか？

機能ホストの作成は必要ありません。エージェントが独自のAzure リソースを使用する場合は、アカウントスコープとプロジェクトスコープの両方で機能ホストを作成します。

既定の動作 (Microsoftマネージドリソース)

機能ホストを作成しない場合、Agent Service では次のMicrosoftマネージド Azure リソースが自動的に使用されます。

会話ストレージ (会話履歴、エージェント定義)
ファイルストレージ (アップロードされたドキュメント)
ベクター検索 (埋め込みと取得)

独自のリソースを持ち込む

アカウントレベルとプロジェクトレベルの両方で機能ホストを作成すると、Azure リソースによってエージェントデータが格納および処理されます。これは 、標準エージェントのセットアップです。エージェントサービスをセキュリティで保護する方法については、「 Foundry Agent Service のプライベートネットワークを設定する」を参照してください。

標準エージェントのセットアップの詳細については、標準エージェントのセットアップを使用した組み込みのエンタープライズ対応性に関するページを参照してください。

メモ

標準エージェントのセットアップと基本的なエージェントのセットアップには、個別の Foundry アカウントとプロジェクトを使用することをお勧めします。同じ Foundry アカウント内でセットアップの種類を混在しないようにします。

構成階層

機能ホストは、次の 2 つの異なるスコープで動作します。

Service defaults (Microsoft マネージド検索とストレージ) - 機能ホストが構成されていない場合に使用されます。
アカウントレベルの機能ホスト - アカウントレベルでエージェントサービスを有効にします。
Project レベルの機能ホスト - エージェントサービスがその特定のprojectに使用する BYO リソースを定義します。

Important

プロジェクトレベルの機能ホストは、エージェントサービスが読み取る内容で、プロジェクトに使用するストレージ、会話、およびベクターストアリソースを決定します。アカウント機能ホストからプロジェクトへの BYO リソース構成の自動継承はありません。アカウント機能ホストが接続を参照している場合でも、エージェントサービスは、それらの接続がプロジェクト機能ホストで明示的に参照されていない限り、それらをプロジェクトに使用しません。

機能ホストの制約について

機能ホストを作成するときは、競合を回避するために、次の重要な制約に注意してください。

スコープごとに 1 つの機能ホスト: 各アカウントと各プロジェクトは、アクティブな機能ホストを 1 つだけ持つことができます。同じスコープで別の名前の 2 つ目の機能ホストを作成しようとすると、409 エラーが表示されます。
構成を更新できません:構成を変更する必要がある場合は、既存の機能ホストを削除して再作成します。
アカウント機能ホストの前提条件: アカウントレベルの機能ホストが既に存在しない限り、プロジェクト機能ホストを作成することはできません。

機能ホストのための接続を設定する

Capabilityホストは、Foundryアカウントとプロジェクトで設定した接続名を参照します。標準エージェントのセットアップ用にプロジェクト機能ホストを構成する前に、エージェントデータを格納するリソースの接続を作成します。

会話ストレージ: Azure Cosmos DB接続
File storage: Azure Storage接続
Vector store: Azure AI 検索接続

独自の Azure OpenAI リソースからのモデルデプロイを使用する場合は、Azure OpenAI 接続も作成します。

Foundry ポータルで接続を追加するには、「新しい接続をプロジェクトに追加する」を参照してください。

必要な接続プロパティ

エージェントサービスが実行時にリソースを正しく解決して使用するには、機能ホストによって参照される各接続に次のプロパティが設定されている必要があります。

プロパティ	Description
`authType`	接続の認証の種類 (たとえば、 `AAD`)
`category`	Azure リソースの種類 (例: `AzureStorageAccount`、`AzureCosmosDb`、`CognitiveSearch`)
`target`	リソースのサービスエンドポイント URL (リソース ID ではない)
`metadata.ResourceId`	リソースの完全なAzure リソース ID

Important

エージェントサービスが実行時にリソースを正しく解決するには、 metadata.ResourceId フィールドが必要です。これは、機能ホストによって参照されるプロジェクトレベルの接続とアカウントレベルの接続の両方に適用されます。

次の例は、正しく構成されたAzure Storage接続を示しています。

{
  "properties": {
    "authType": "AAD",
    "category": "AzureStorageAccount",
    "target": "https://{storageAccountName}.blob.core.windows.net/",
    "metadata": {
      "ResourceId": "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Storage/storageAccounts/{storageAccountName}"
    }
  }
}

メモ

接続テンプレートには追加のメタデータフィールドが含まれる場合があります。正しい解決とランタイム動作の機能要件は有効な metadata.ResourceId であり、正しく設定された authType、 category、および target プロパティです。

機能ホストを構成する

現時点では、REST API を使用して機能ホストを管理しています。機能ホスト管理に対する SDK のサポートは利用できません。

必須プロパティ (プロジェクト機能ホスト)

エージェントデータに独自のリソースを使用するには (標準エージェントのセットアップ)、次のプロパティを使用してプロジェクト機能ホストを構成します。

プロパティ	目的	必要なAzure リソース	接続名の例
`threadStorageConnections`	エージェント定義と会話履歴を格納します	Azure Cosmos DB	`"my-cosmosdb-connection"`
`vectorStoreConnections`	取得および検索用のベクターストレージを処理する	Azure AI 検索	`"my-ai-search-connection"`
`storageConnections`	ファイルのアップロードと BLOB ストレージを管理します	Azure Storage アカウント	`"my-storage-connection"`

省略可能なプロパティ

プロパティ	目的	必要なAzure リソース	使用するタイミング
`aiServicesConnections`	あなたの独自モデルデプロイメントを使用する	Azure OpenAI	既存の Azure OpenAI リソースのモデルを、組み込みのアカウントレベルのものではなく使用する場合。

アカウント機能ホスト

アカウント機能ホストを使用して、アカウントレベルでエージェントサービスを有効にします。

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/capabilityHosts/{name}?api-version=2025-06-01

{
  "properties": {
    "capabilityHostKind": "Agents"
  }
}

リファレンス: Foundry アカウント管理 REST API

プロジェクト能力ホスト

プロジェクト機能ホストは、エージェントサービスが読み取って、プロジェクトに使用する BYO リソースを決定します。このプロジェクトのすべてのエージェントは、ここで参照されているリソースを使用します。

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/projects/{projectName}/capabilityHosts/{name}?api-version=2025-06-01

{
  "properties": {
    "capabilityHostKind": "Agents",
    "threadStorageConnections": ["my-cosmos-db-connection"],
    "vectorStoreConnections": ["my-ai-search-connection"],
    "storageConnections": ["my-storage-account-connection"],
    "aiServicesConnections": ["my-azure-openai-connection"]
  }
}

リファレンス: プロジェクト能力ホスト - 作成または更新

オプション: プロジェクト機能に対応したホストでのアカウントレベルの接続

アカウントレベルで接続を定義することもできます。そのアカウントで新しいプロジェクトが作成されると、それらの接続はプロジェクトによって継承されます。ただし、プロジェクト機能ホストの構成は継承されません。プロジェクト機能ホストを明示的に作成し、そのプロジェクトにエージェントサービスで使用する接続を参照する必要があります。

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/capabilityHosts/{name}?api-version=2025-06-01

{
  "properties": {
    "capabilityHostKind": "Agents",
    "threadStorageConnections": ["shared-cosmosdb-connection"],
    "vectorStoreConnections": ["shared-ai-search-connection"],
    "storageConnections": ["shared-storage-connection"]
  }
}

メモ

アカウントレベルで定義された接続は、新しいプロジェクトによって継承されます。ただし、プロジェクト機能ホストの構成は継承されません。エージェントサービスでこれらの接続を使用するには、プロジェクトレベルの接続を明示的に参照するプロジェクト機能ホストを作成する必要があります。

構成を確認する

機能ホストが正しく構成されていることを確認するには、次の手順に従います。

アカウント機能ホストを取得し、存在を確認します。

GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/capabilityHosts?api-version=2025-06-01

指定された接続名を確認し、プロジェクトのキャパビリティホストを取得します。

GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/projects/{projectName}/capabilityHosts?api-version=2025-06-01

テストエージェントを作成し、会話を実行して、構成をテストします。次の点を確認します。
- 会話がAzure Cosmos DBに表示されます。
- アップロードしたファイルがAzure Storage アカウントに表示される
- Azure AI 検索インデックスにベクターデータが表示される
接続を更新する場合、またはデータの格納場所を変更する場合は、更新された構成で機能ホストを削除して再作成します。

機能ホストを削除する

警告

機能ホストを削除すると、それに依存するすべてのエージェントに影響します。続行する前に、影響を理解していることを確認してください。たとえば、プロジェクトとアカウント機能のホストを削除すると、プロジェクト内のエージェントは、以前にアクセスしたファイル、会話、ベクターストアにアクセスできなくなります。

アカウントレベルの機能ホストを削除する

DELETE https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/capabilityHosts/{name}?api-version=2025-06-01

プロジェクトレベルの機能ホストを削除する

DELETE https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/projects/{projectName}/capabilityHosts/{name}?api-version=2025-06-01

トラブルシューティング

機能ホストの作成時に問題が発生している場合は、このセクションで最も一般的な問題とエラーの解決策について説明します。

HTTP 409 競合エラー

問題: スコープごとに複数の機能ホスト

症状： スコープが空であると思われる場合でも、機能ホストを作成しようとすると、409 競合エラーが発生します。

エラーメッセージ:

{
  "error": {
    "code": "Conflict",
    "message": "There is an existing Capability Host with name: existing-host, provisioning state: Succeeded for workspace: /subscriptions/.../workspaces/my-workspace, cannot create a new Capability Host with name: new-host for the same ClientId."
  }
}

根本原因: 各アカウントと各プロジェクトは、アクティブな機能ホストを 1 つだけ持つことができます。同じスコープに既に存在する場合は、別の名前の機能ホストを作成しようとしています。

ソリューション：

既存の機能ホストを確認する - スコープにクエリを実行して、既に存在するものを確認する
一貫性のある名前付けを使用 する - 同じスコープのすべての要求で同じ名前を使用していることを確認する
要件を確認 する - 既存の機能ホストがニーズを満たしているかどうかを判断する

検証手順:「構成の確認」の GET 要求を使用して、ターゲットスコープに機能ホストが既に存在するかどうかを確認します。

問題: 同時実行中の操作が検知されました。

症状： 別の操作が現在実行中であることを示す 409 競合エラーが表示されます。

エラーメッセージ:

{
  "error": {
    "code": "Conflict", 
    "message": "Create: Capability Host my-host is currently in non creating, retry after its complete: /subscriptions/.../workspaces/my-workspace"
  }
}

根本原因: 別の操作 (更新、削除、変更) が同じスコープで進行中の間に、機能ホストを作成しようとしています。

ソリューション：

現在の操作が完了するまで待機する - 進行中の操作の状態を確認する
操作の進行状況を監視 する - 操作 API を使用して完了を追跡する
再試行ロジックを実装 する - 一時的な競合に指数バックオフを使用する

操作の監視:

GET https://management.azure.com/subscriptions/{subscriptionId}/providers/Microsoft.CognitiveServices/locations/{location}/operationResults/{operationId}?api-version=2025-06-01

競合防止のベストプラクティス

1. 事前要求の検証

変更を行う前に、常に現在の状態を確認してください。

ターゲットスコープ内の既存の機能ホストに対してクエリを実行する
進行中の操作を確認する
現在の構成を理解する

2. 指数バックオフを使用して再試行ロジックを実装する

try 
{
    var response = await CreateCapabilityHostAsync(request);
    return response;
}
catch (HttpRequestException ex) when (ex.Message.Contains("409"))
{
    if (ex.Message.Contains("existing Capability Host with name"))
    {
        // Handle name conflict - check if existing resource is acceptable
        var existing = await GetExistingCapabilityHostAsync();
        if (IsAcceptable(existing))
        {
            return existing; // Use existing resource
        }
        else
        {
            throw new InvalidOperationException("Scope already has a capability host with different name");
        }
    }
    else if (ex.Message.Contains("currently in non creating"))
    {
        // Handle concurrent operation - implement retry with backoff
        await Task.Delay(TimeSpan.FromSeconds(30));
        return await CreateCapabilityHostAsync(request); // Retry once
    }
}

3. べき等の動作を理解する

システムはべき等作成要求をサポートします。

同じ名前 + 同じ構成 →既存のリソースを返します (200 OK)
同じ名前 + 異なる構成 → 400 無効な要求が返されます
異なる名前 → 409 競合を返します

4. 構成変更のワークフロー

更新プログラムはサポートされていないため、構成の変更については次の手順に従ってください。

既存の機能ホストを削除する
削除が完了するまで待ちます
必要な構成で新しい機能ホストを作成する

一般的なシナリオ

開発とテスト: Microsoftマネージドリソースを使用します。機能ホストの構成は必要ありません。
コンプライアンス要件を満たす運用: 独自のAzure Cosmos DB、ストレージ、AI Search を使用して機能ホストを作成します。
プロジェクト間の共有リソース: アカウントレベルの接続を構成し、それらの接続を明示的に参照するプロジェクトごとにプロジェクト機能ホストを作成します。

次の手順

フィードバック

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

Last updated on 2026-07-09