Knowledge Agents - Create Or Update

サービス:: Search Service

API バージョン:: 2025-05-01-preview

新しいエージェントを作成するか、エージェントがすでに存在する場合はエージェントを更新します。

PUT {endpoint}/agents('{agentName}')?api-version=2025-05-01-preview

URI パラメーター

名前	/	必須	型	説明
agentName	path	True	string	作成または更新するエージェントの名前。
endpoint	path	True	string	検索サービスのエンドポイント URL。
api-version	query	True	string	クライアント API のバージョン。

要求ヘッダー

名前	必須	型	説明
x-ms-client-request-id		string (uuid)	デバッグに役立つ要求と共に送信される追跡 ID。
If-Match		string	If-Match 条件を定義します。この操作は、サーバー上の ETag がこの値と一致する場合にのみ実行されます。
If-None-Match		string	If-None-Match 条件を定義します。この操作は、サーバー上の ETag がこの値と一致しない場合にのみ実行されます。
Prefer	True	string	HTTP PUT 要求の場合は、正常に作成/更新されたリソースを返すようにサービスに指示します。

要求本文

名前	必須	型	説明
models	True	KnowledgeAgentModel[]: KnowledgeAgentAzureOpenAIModel[]	AI モデルへの接続方法に関する構成オプションが含まれています。
name	True	string	ナレッジエージェントの名前。
targetIndexes	True	KnowledgeAgentTargetIndex[]
@odata.etag		string	エージェントの ETag。
description		string	エージェントの説明。
encryptionKey		SearchResourceEncryptionKey	Azure Key Vault で作成する暗号化キーの説明。このキーは、エージェント定義に対して、Microsoft でさえも暗号化を解除できないという完全な保証が必要な場合に、エージェント定義の保存時の暗号化レベルを追加するために使用されます。エージェント定義を暗号化すると、常に暗号化されたままになります。検索サービスは、このプロパティを null に設定する試行を無視します。暗号化キーをローテーションする場合は、必要に応じてこのプロパティを変更できます。エージェントの定義は影響を受けません。カスタマーマネージドキーを使用した暗号化は、無料の検索サービスでは使用できません。また、2019 年 1 月 1 日以降に作成された有料サービスでのみ使用できます。
requestLimits		KnowledgeAgentRequestLimits	1 つのエージェント取得要求に使用されるリソースの量を制限するガードレール。

応答

名前	型	説明
200 OK	KnowledgeAgent
201 Created	KnowledgeAgent
Other Status Codes	ErrorResponse	エラー応答。

例

SearchServiceCreateOrUpdateKnowledgeAgent

要求のサンプル

HTTP

PUT https://previewexampleservice.search.windows.net/agents('agent-preview-test')?api-version=2025-05-01-preview





{
  "name": "agent-preview-test",
  "models": [
    {
      "azureOpenAIParameters": {
        "resourceUri": "https://test-sample.openai.azure.com/",
        "deploymentId": "myDeployment",
        "apiKey": "api-key",
        "modelName": "gpt-4o-mini"
      },
      "kind": "azureOpenAI"
    }
  ],
  "targetIndexes": [
    {
      "indexName": "preview-test",
      "defaultRerankerThreshold": 2.5,
      "defaultIncludeReferenceSourceData": true,
      "defaultMaxDocsForReranker": 100
    }
  ],
  "requestLimits": {
    "maxRuntimeInSeconds": 60,
    "maxOutputSize": 100000
  },
  "@odata.etag": "0x1234568AE7E58A1",
  "encryptionKey": {
    "keyVaultKeyName": "myUserManagedEncryptionKey-createdinAzureKeyVault",
    "keyVaultKeyVersion": "myKeyVersion-32charAlphaNumericString",
    "keyVaultUri": "https://myKeyVault.vault.azure.net",
    "accessCredentials": {
      "applicationId": "00000000-0000-0000-0000-000000000000",
      "applicationSecret": "<applicationSecret>"
    }
  },
  "description": "Description of the agent."
}

応答のサンプル

状態コード:: 200

{
  "@odata.etag": "0x1234568AE7E58A1",
  "name": "agent-preview-test",
  "description": "Description of the agent.",
  "targetIndexes": [
    {
      "indexName": "preview-test",
      "defaultRerankerThreshold": 2.5,
      "defaultIncludeReferenceSourceData": true,
      "defaultMaxDocsForReranker": 100
    }
  ],
  "models": [
    {
      "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "https://test-sample.openai.azure.com/",
        "deploymentId": "myDeployment",
        "apiKey": "api-key",
        "modelName": "gpt-4o-mini"
      }
    }
  ],
  "requestLimits": {
    "maxRuntimeInSeconds": 60,
    "maxOutputSize": 100000
  },
  "encryptionKey": {
    "keyVaultKeyName": "myUserManagedEncryptionKey-createdinAzureKeyVault",
    "keyVaultKeyVersion": "myKeyVersion-32charAlphaNumericString",
    "keyVaultUri": "https://myKeyVault.vault.azure.net",
    "accessCredentials": {
      "applicationId": "00000000-0000-0000-0000-000000000000",
      "applicationSecret": "<applicationSecret>"
    }
  }
}

状態コード:: 201

{
  "@odata.etag": "0x1234568AE7E58A1",
  "name": "agent-preview-test",
  "description": "Description of the agent.",
  "targetIndexes": [
    {
      "indexName": "preview-test",
      "defaultRerankerThreshold": 2.5,
      "defaultIncludeReferenceSourceData": true,
      "defaultMaxDocsForReranker": 100
    }
  ],
  "models": [
    {
      "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "https://test-sample.openai.azure.com/",
        "deploymentId": "myDeployment",
        "apiKey": "api-key",
        "modelName": "gpt-4o-mini"
      }
    }
  ],
  "requestLimits": {
    "maxRuntimeInSeconds": 60,
    "maxOutputSize": 100000
  },
  "encryptionKey": {
    "keyVaultKeyName": "myUserManagedEncryptionKey-createdinAzureKeyVault",
    "keyVaultKeyVersion": "myKeyVersion-32charAlphaNumericString",
    "keyVaultUri": "https://myKeyVault.vault.azure.net",
    "accessCredentials": {
      "applicationId": "00000000-0000-0000-0000-000000000000",
      "applicationSecret": "<applicationSecret>"
    }
  }
}

定義

名前	説明
AzureActiveDirectoryApplicationCredentials	Azure Key Vault に格納されている暗号化キーへの認証済みアクセスに使用される、検索サービス用に作成された登録済みアプリケーションの資格情報。
AzureOpenAIEmbeddingSkill	Azure OpenAI リソースを使用して、特定のテキスト入力のベクター埋め込みを生成できます。
AzureOpenAIModelName	呼び出される Azure Open AI モデル名。
AzureOpenAIParameters	Azure OpenAI リソースに接続するためのパラメーターを指定します。
ErrorAdditionalInfo	リソース管理エラーの追加情報。
ErrorDetail	エラーの詳細。
ErrorResponse	エラー応答
InputFieldMappingEntry	スキルの入力フィールドマッピング。
KnowledgeAgent
KnowledgeAgentAzureOpenAIModel	クエリ計画の実行に使用する Azure OpenAI リソースを指定します。
KnowledgeAgentModelKind	クエリ計画に使用する AI モデル。
KnowledgeAgentRequestLimits	1 つのエージェント取得要求に使用されるリソースの量を制限するガードレール。
KnowledgeAgentTargetIndex
OutputFieldMappingEntry	スキルの出力フィールドマッピング。
SearchIndexerDataNoneIdentity	データソースの ID プロパティをクリアします。
SearchIndexerDataUserAssignedIdentity	使用するデータソースの ID を指定します。
SearchResourceEncryptionKey	Azure Key Vault のカスタマーマネージド暗号化キー。作成および管理するキーは、インデックスやシノニムマップなどの保存データの暗号化または暗号化解除に使用できます。

AzureActiveDirectoryApplicationCredentials

Object

Azure Key Vault に格納されている暗号化キーへの認証済みアクセスに使用される、検索サービス用に作成された登録済みアプリケーションの資格情報。

名前	型	説明
applicationId	string	保存データの暗号化時に使用される Azure Key Vault に対する必要なアクセス許可が付与された AAD アプリケーション ID。アプリケーション ID は、AAD アプリケーションのオブジェクト ID と混同しないでください。
applicationSecret	string	指定した AAD アプリケーションの認証キー。

AzureOpenAIEmbeddingSkill

Object

Azure OpenAI リソースを使用して、特定のテキスト入力のベクター埋め込みを生成できます。

名前	型	説明
@odata.type	string: #Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill	スキルの種類を指定する URI フラグメント。
apiKey	string	指定された Azure OpenAI リソースの API キー。
authIdentity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	送信接続に使用されるユーザー割り当てマネージド ID。
context	string	ドキュメントのルートやドキュメントのコンテンツ (/document や /document/content など) など、操作が行われるレベルを表します。既定値は /document です。
deploymentId	string	指定されたリソースに対する Azure OpenAI モデルデプロイの ID。
description	string	スキルの入力、出力、および使用方法を記述するスキルの説明。
dimensions	integer (int32)	結果として出力される埋め込みに必要なディメンションの数。 text-embedding-3 以降のモデルでのみサポートされます。
inputs	InputFieldMappingEntry[]	スキルの入力には、ソースデータセット内の列、またはアップストリームスキルの出力を指定できます。
modelName	AzureOpenAIModelName	指定された deploymentId パスにデプロイされる埋め込みモデルの名前。
name	string	スキルセット内で一意に識別されるスキルの名前。名前が定義されていないスキルには、スキル配列内の 1 から始まるインデックスの既定の名前が付けられます。先頭には文字 '#' が付きます。
outputs	OutputFieldMappingEntry[]	スキルの出力は、検索インデックス内のフィールドか、別のスキルによる入力として使用できる値のいずれかです。
resourceUri	string (uri)	Azure OpenAI リソースのリソース URI。

AzureOpenAIModelName

列挙

呼び出される Azure Open AI モデル名。

値	説明
text-embedding-ada-002
text-embedding-3-large
text-embedding-3-small
gpt-4o
gpt-4o-mini
gpt-4.1
gpt-4.1-mini
gpt-4.1-nano

AzureOpenAIParameters

Object

Azure OpenAI リソースに接続するためのパラメーターを指定します。

名前	型	説明
apiKey	string	指定された Azure OpenAI リソースの API キー。
authIdentity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	送信接続に使用されるユーザー割り当てマネージド ID。
deploymentId	string	指定されたリソースに対する Azure OpenAI モデルデプロイの ID。
modelName	AzureOpenAIModelName	指定された deploymentId パスにデプロイされる埋め込みモデルの名前。
resourceUri	string (uri)	Azure OpenAI リソースのリソース URI。

ErrorAdditionalInfo

Object

リソース管理エラーの追加情報。

名前	型	説明
info	object	追加情報。
type	string	追加情報の種類。

ErrorDetail

Object

エラーの詳細。

名前	型	説明
additionalInfo	ErrorAdditionalInfo[]	エラーの追加情報。
code	string	エラーコード。
details	ErrorDetail[]	エラーの詳細。
message	string	エラーメッセージ。
target	string	エラーターゲット。

ErrorResponse

Object

エラー応答

名前	型	説明
error	ErrorDetail	エラーオブジェクト。

InputFieldMappingEntry

Object

スキルの入力フィールドマッピング。

名前	型	説明
inputs	InputFieldMappingEntry[]	複合型の作成時に使用される再帰入力。
name	string	入力の名前。
source	string	入力のソース。
sourceContext	string	再帰入力の選択に使用されるソースコンテキスト。

KnowledgeAgent

Object

名前	型	説明
@odata.etag	string	エージェントの ETag。
description	string	エージェントの説明。
encryptionKey	SearchResourceEncryptionKey	Azure Key Vault で作成する暗号化キーの説明。このキーは、エージェント定義に対して、Microsoft でさえも暗号化を解除できないという完全な保証が必要な場合に、エージェント定義の保存時の暗号化レベルを追加するために使用されます。エージェント定義を暗号化すると、常に暗号化されたままになります。検索サービスは、このプロパティを null に設定する試行を無視します。暗号化キーをローテーションする場合は、必要に応じてこのプロパティを変更できます。エージェントの定義は影響を受けません。カスタマーマネージドキーを使用した暗号化は、無料の検索サービスでは使用できません。また、2019 年 1 月 1 日以降に作成された有料サービスでのみ使用できます。
models	KnowledgeAgentModel[]: KnowledgeAgentAzureOpenAIModel[]	AI モデルへの接続方法に関する構成オプションが含まれています。
name	string	ナレッジエージェントの名前。
requestLimits	KnowledgeAgentRequestLimits	1 つのエージェント取得要求に使用されるリソースの量を制限するガードレール。
targetIndexes	KnowledgeAgentTargetIndex[]

KnowledgeAgentAzureOpenAIModel

Object

クエリ計画の実行に使用する Azure OpenAI リソースを指定します。

名前	型	説明
azureOpenAIParameters	AzureOpenAIParameters: AzureOpenAIEmbeddingSkill	Azure OpenAI モデルエンドポイントに固有のパラメーターが含まれます。
kind	string: azureOpenAI	AI モデルのタイプ。

KnowledgeAgentModelKind

列挙

クエリ計画に使用する AI モデル。

値	説明
azureOpenAI	クエリ計画に Azure Open AI モデルを使用します。

KnowledgeAgentRequestLimits

Object

1 つのエージェント取得要求に使用されるリソースの量を制限するガードレール。

名前	型	説明
maxOutputSize	integer (int32)	出力内のコンテンツの最大サイズを制限します。
maxRuntimeInSeconds	integer (int32)	最大実行時間 (秒単位)。

KnowledgeAgentTargetIndex

Object

名前	型	説明
defaultIncludeReferenceSourceData	boolean	参照元データを含めるかどうかを示します。
defaultMaxDocsForReranker	integer (int32)	ランク付けの対象となるドキュメントの数を制限します。
defaultRerankerThreshold	number (float) minimum: 0 maximum: 4	結果の再ランク付けのしきい値 (範囲: 0 から 4)。
indexName	string	ターゲットインデックスの名前。

OutputFieldMappingEntry

Object

スキルの出力フィールドマッピング。

名前	型	説明
name	string	スキルによって定義された出力の名前。
targetName	string	出力のターゲット名。これは省略可能であり、既定では名前になります。

SearchIndexerDataNoneIdentity

Object

データソースの ID プロパティをクリアします。

名前	型	説明
@odata.type	string: #Microsoft.Azure.Search.DataNoneIdentity	ID の種類を指定する URI フラグメント。

SearchIndexerDataUserAssignedIdentity

Object

使用するデータソースの ID を指定します。

名前	型	説明
@odata.type	string: #Microsoft.Azure.Search.DataUserAssignedIdentity	ID の種類を指定する URI フラグメント。
userAssignedIdentity	string	通常、ユーザー割り当てマネージド ID の完全修飾 Azure リソース ID は、検索サービスに割り当てられている必要がある "/subscriptions/12345678-1234-1234-1234567890ab/resourceGroups/rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myId" の形式です。

SearchResourceEncryptionKey

Object

Azure Key Vault のカスタマーマネージド暗号化キー。作成および管理するキーは、インデックスやシノニムマップなどの保存データの暗号化または暗号化解除に使用できます。

名前	型	説明
accessCredentials	AzureActiveDirectoryApplicationCredentials	Azure Key Vault へのアクセスに使用されるオプションの Azure Active Directory 資格情報。代わりにマネージド ID を使用する場合は必要ありません。
identity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	この暗号化キーに使用する明示的なマネージド ID。指定されず、アクセス資格情報プロパティが null の場合は、システム割り当てマネージド ID が使用されます。リソースの更新時に、明示的な ID が指定されていない場合、変更されません。 "none" が指定されている場合、このプロパティの値はクリアされます。
keyVaultKeyName	string	保存データの暗号化に使用する Azure Key Vault キーの名前。
keyVaultKeyVersion	string	保存データの暗号化に使用する Azure Key Vault キーのバージョン。
keyVaultUri	string	保存データの暗号化に使用するキーを含む Azure Key Vault の URI (DNS 名とも呼ばれます)。 URI の例は、`https://my-keyvault-name.vault.azure.net`可能性があります。