機能ホスト

メモ

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

機能ホストは、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 リソースによってエージェントデータが格納および処理されます。これは 、標準エージェントのセットアップです。ネットワークで保護された標準エージェントのセットアップでは、関連するすべてのリソースを仮想ネットワーク (VNet) と同じリージョンにデプロイします。ガイダンスについては、「ユーザーマネージド ID を使用して新しいネットワークで保護された環境を作成する」を参照してください。

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

メモ

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

構成階層

機能ホストは、より具体的な構成がより広範な構成よりも優先される階層に従います。

Service defaults (Microsoft マネージド検索とストレージ) - 機能ホストが構成されていない場合に使用されます。
アカウントレベルのケイパビリティホスト - 共有の既定値をすべてのアカウントのプロジェクトに提供します。
プロジェクトレベルの機能ホスト - 特定のプロジェクトに対して、アカウントレベルをオーバーライドします。

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

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

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

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

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

Thread storage: Azure Cosmos DBの接続
File storage: Azure Storage接続
Vector store: Azure AI 検索接続

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

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

機能ホストを構成する

現時点では、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

プロジェクト能力ホスト

この構成は、サービスの既定値とアカウントレベルの設定をオーバーライドします。このプロジェクトのすべてのエージェントは、指定したリソースを使用します。

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

メモ

Foundry プロジェクトはすべて、これらの設定を継承します。次に、必要に応じてプロジェクトレベルで特定の設定をオーバーライドします。

構成を確認する

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

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

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-04-30