Knowledge Agents - Get

服務:
Search Service
API 版本:
2025-05-01-preview

檢索代理定義。

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

URI 參數

名稱 位於 必要 類型 Description
agentName
 path True

string

要檢索的代理的名稱。
endpoint
 path True

string

搜尋服務的端點 URL。
api-version
 query True

string

用戶端 API 版本。

要求標頭

名稱 必要 類型 Description
x-ms-client-request-id

string (uuid)

隨要求一起傳送的追蹤標識碼，以協助偵錯。

回應

名稱 類型 Description
200 OK

KnowledgeAgent

Other Status Codes

ErrorResponse

錯誤回應。

範例

SearchServiceGetKnowledgeAgent

範例要求

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

範例回覆

狀態碼:
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": "<redacted>",
        "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>"
    }
  }
}

定義

名稱 Description
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

防護機制來限制單個代理檢索請求使用的資源量。
KnowledgeAgentTargetIndex
OutputFieldMappingEntry

技能的輸出欄位對應。
SearchIndexerDataNoneIdentity

清除資料源的識別屬性。
SearchIndexerDataUserAssignedIdentity

指定要使用之數據源的身分識別。
SearchResourceEncryptionKey

Azure Key Vault 中客戶管理的加密密鑰。 您建立和管理的金鑰可用來加密或解密待用數據，例如索引和同義字對應。

AzureActiveDirectoryApplicationCredentials

Object

為搜尋服務建立之已註冊應用程式的認證，用於對儲存在 Azure Key Vault 中的加密密鑰進行驗證存取。

名稱 類型 Description
applicationId

string

AAD 應用程式識別碼，已將待用數據加密時要使用的 Azure Key Vault 所需訪問許可權授與。 應用程式標識碼不應與 AAD 應用程式的物件標識元混淆。
applicationSecret

string

指定 AAD 應用程式的驗證金鑰。

AzureOpenAIEmbeddingSkill

Object

可讓您使用 Azure OpenAI 資源為指定的文字輸入產生向量內嵌。

名稱 類型 Description
@odata.type string:

#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill

指定技能類型的 URI 片段。
apiKey

string

所指定 Azure OpenAI 資源的 API 金鑰。
authIdentity SearchIndexerDataIdentity:

用於輸出連線的使用者指派受控識別。
context

string

代表作業發生的層級，例如檔根目錄或文件內容（例如 /document 或 /document/content）。 預設值為 /document。
deploymentId

string

指定資源上 Azure OpenAI 模型部署的識別碼。
description

string

描述技能的描述，描述技能的輸入、輸出和使用方式。
dimensions

integer (int32)

產生的輸出內嵌應具有的維度數目。 只有文字內嵌-3 和更新版本的模型才支援。
inputs

InputFieldMappingEntry[]

技能的輸入可以是源數據集中的數據行，或上游技能的輸出。
modelName

AzureOpenAIModelName

在提供的 deploymentId 路徑上部署的內嵌模型名稱。
name

string

技能的名稱，可唯一識別技能集內的技能。 未定義名稱的技能將會在技能數位中指定其以 1 起始索引的預設名稱，前面加上字元 『#』。
outputs

OutputFieldMappingEntry[]

技能的輸出是搜尋索引中的字段，或是另一個技能可作為輸入的值。
resourceUri

string (uri)

Azure OpenAI 資源的資源 URI。

AzureOpenAIModelName

列舉型別

將呼叫的 Azure Open AI 模型名稱。

值 Description
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 資源的參數。

名稱 類型 Description
apiKey

string

所指定 Azure OpenAI 資源的 API 金鑰。
authIdentity SearchIndexerDataIdentity:

用於輸出連線的使用者指派受控識別。
deploymentId

string

指定資源上 Azure OpenAI 模型部署的識別碼。
modelName

AzureOpenAIModelName

在提供的 deploymentId 路徑上部署的內嵌模型名稱。
resourceUri

string (uri)

Azure OpenAI 資源的資源 URI。

ErrorAdditionalInfo

Object

資源管理錯誤其他資訊。

名稱 類型 Description
info

object

其他資訊。
type

string

其他信息類型。

ErrorDetail

Object

錯誤詳細數據。

名稱 類型 Description
additionalInfo

ErrorAdditionalInfo[]

錯誤其他資訊。
code

string

錯誤碼。
details

ErrorDetail[]

錯誤詳細數據。
message

string

錯誤訊息。
target

string

錯誤目標。

ErrorResponse

Object

錯誤回應

名稱 類型 Description
error

ErrorDetail

error 物件。

InputFieldMappingEntry

Object

技能的輸入欄位對應。

名稱 類型 Description
inputs

InputFieldMappingEntry[]

建立複雜型別時所使用的遞歸輸入。
name

string

輸入的名稱。
source

string

輸入的來源。
sourceContext

string

用於選取遞歸輸入的來源內容。

KnowledgeAgent

Object
名稱 類型 Description
@odata.etag

string

代理的 ETag。
description

string

代理程式的描述。
encryptionKey

SearchResourceEncryptionKey

您在 Azure Key Vault 中建立的加密金鑰描述。 當您希望完全保證沒有人（甚至 Microsoft）可以解密它們時，此密鑰用於為您的代理定義提供額外的靜態加密級別。 加密代理定義后，它將始終保持加密狀態。 搜尋服務會忽略將此屬性設定為 null 的嘗試。 如果要輪換加密金鑰，您可以根據需要更改此屬性;您的代理定義將不受影響。 使用客戶管理的金鑰加密不適用於免費搜尋服務，而且僅適用於 2019 年 1 月 1 日或之後建立的付費服務。
models KnowledgeAgentModel[]:

KnowledgeAgentAzureOpenAIModel[]

包含有關如何連接到 AI 模型的配置選項。
name

string

知識代理的名稱。
requestLimits

KnowledgeAgentRequestLimits

防護機制來限制單個代理檢索請求使用的資源量。
targetIndexes

KnowledgeAgentTargetIndex[]

KnowledgeAgentAzureOpenAIModel

Object

指定用於執行查詢規劃的 Azure OpenAI 資源。

名稱 類型 Description
azureOpenAIParameters AzureOpenAIParameters:

AzureOpenAIEmbeddingSkill

包含特定於 Azure OpenAI 模型終結點的參數。
kind string:

azureOpenAI

AI 模型的類型。

KnowledgeAgentModelKind

列舉型別

用於查詢規劃的 AI 模型。

值 Description
azureOpenAI

使用 Azure Open AI 模型進行查詢規劃。

KnowledgeAgentRequestLimits

Object

防護機制來限制單個代理檢索請求使用的資源量。

名稱 類型 Description
maxOutputSize

integer (int32)

限制輸出中內容的最大大小。
maxRuntimeInSeconds

integer (int32)

最大運行時間（以秒為單位）。

KnowledgeAgentTargetIndex

Object
名稱 類型 Description
defaultIncludeReferenceSourceData

boolean

指示是否應包含引用源數據。
defaultMaxDocsForReranker

integer (int32)

限制考慮進行排名的文件數量。
defaultRerankerThreshold

number (float)

minimum: 0
maximum: 4

重新排名結果的閾值（範圍：0-4）。
indexName

string

目標索引的名稱。

OutputFieldMappingEntry

Object

技能的輸出欄位對應。

名稱 類型 Description
name

string

技能所定義的輸出名稱。
targetName

string

輸出的目標名稱。 這是選擇性的，預設為 name。

SearchIndexerDataNoneIdentity

Object

清除資料源的識別屬性。

名稱 類型 Description
@odata.type string:

#Microsoft.Azure.Search.DataNoneIdentity

指定身分識別類型的 URI 片段。

SearchIndexerDataUserAssignedIdentity

Object

指定要使用之數據源的身分識別。

名稱 類型 Description
@odata.type string:

#Microsoft.Azure.Search.DataUserAssignedIdentity

指定身分識別類型的 URI 片段。
userAssignedIdentity

string

使用者指派受控識別的完整 Azure 資源標識符，通常格式為 “/subscriptions/12345678-1234-1234-1234-1234567890ab/resourceGroups/rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myId”。

SearchResourceEncryptionKey

Object

Azure Key Vault 中客戶管理的加密密鑰。 您建立和管理的金鑰可用來加密或解密待用數據，例如索引和同義字對應。

名稱 類型 Description
accessCredentials

AzureActiveDirectoryApplicationCredentials

用來存取 Azure Key Vault 的選擇性 Azure Active Directory 認證。 如果改用受控識別，則不需要。
identity SearchIndexerDataIdentity:

要用於此加密金鑰的明確受控識別。 如果未指定，且存取認證屬性為 Null，則會使用系統指派的受控識別。 更新資源時，如果未指定明確識別，則會維持不變。 如果指定了 「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。