Knowledge Agents - Get

Tjänst:: Search Service

API-versionen:: 2025-05-01-preview

Hämtar en agentdefinition.

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

URI-parametrar

Namn	I	Krävs	Typ	Beskrivning
agentName	path	True	string	Namnet på agenten som ska hämtas.
endpoint	path	True	string	Slutpunkts-URL:en för söktjänsten.
api-version	query	True	string	Klient-API-version.

Begäran-huvud

Namn	Krävs	Typ	Beskrivning
x-ms-client-request-id		string (uuid)	Spårnings-ID:t som skickas med begäran för att hjälpa till med felsökning.

Svaren

Namn	Typ	Beskrivning
200 OK	KnowledgeAgent
Other Status Codes	ErrorResponse	Felsvar.

Exempel

SearchServiceGetKnowledgeAgent

Exempelförfrågan

HTTP

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

Exempelsvar

Statuskod:: 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>"
    }
  }
}

Definitioner

Namn	Beskrivning
AzureActiveDirectoryApplicationCredentials	Autentiseringsuppgifter för ett registrerat program som skapats för din söktjänst och som används för autentiserad åtkomst till krypteringsnycklarna som lagras i Azure Key Vault.
AzureOpenAIEmbeddingSkill	Gör att du kan generera en vektorinbäddning för en viss textinmatning med hjälp av Azure OpenAI-resursen.
AzureOpenAIModelName	Namnet på Azure Open AI-modellen som ska anropas.
AzureOpenAIParameters	Anger parametrarna för att ansluta till Azure OpenAI-resursen.
ErrorAdditionalInfo	Ytterligare information om resurshanteringsfelet.
ErrorDetail	Felinformationen.
ErrorResponse	Felsvar
InputFieldMappingEntry	Mappning av indatafält för en färdighet.
KnowledgeAgent
KnowledgeAgentAzureOpenAIModel	Anger den Azure OpenAI-resurs som används för att göra frågeplanering.
KnowledgeAgentModelKind	AI-modellen som ska användas för frågeplanering.
KnowledgeAgentRequestLimits	Skyddsräcken för att begränsa hur mycket resurser som används för en enskild agenthämtningsbegäran.
KnowledgeAgentTargetIndex
OutputFieldMappingEntry	Mappning av utdatafält för en färdighet.
SearchIndexerDataNoneIdentity	Rensar identitetsegenskapen för en datakälla.
SearchIndexerDataUserAssignedIdentity	Anger identiteten för en datakälla som ska användas.
SearchResourceEncryptionKey	En kundhanterad krypteringsnyckel i Azure Key Vault. Nycklar som du skapar och hanterar kan användas för att kryptera eller dekryptera vilande data, till exempel index och synonymkartor.

AzureActiveDirectoryApplicationCredentials

Objekt

Autentiseringsuppgifter för ett registrerat program som skapats för din söktjänst och som används för autentiserad åtkomst till krypteringsnycklarna som lagras i Azure Key Vault.

Namn	Typ	Beskrivning
applicationId	string	Ett AAD-program-ID som har beviljats nödvändiga åtkomstbehörigheter till Azure Key Vault som ska användas när du krypterar dina data i vila. Program-ID:t bör inte förväxlas med objekt-ID:t för ditt AAD-program.
applicationSecret	string	Autentiseringsnyckeln för det angivna AAD-programmet.

AzureOpenAIEmbeddingSkill

Objekt

Gör att du kan generera en vektorinbäddning för en viss textinmatning med hjälp av Azure OpenAI-resursen.

Namn	Typ	Beskrivning
@odata.type	string: #Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill	Ett URI-fragment som anger typen av kompetens.
apiKey	string	API-nyckeln för den avsedda Azure OpenAI-resursen.
authIdentity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	Den användartilldelade hanterade identiteten som används för utgående anslutningar.
context	string	Representerar den nivå där åtgärder utförs, till exempel dokumentroten eller dokumentinnehållet (till exempel /document eller /document/content). Standardvärdet är /document.
deploymentId	string	ID för Azure OpenAI-modelldistributionen på den avsedda resursen.
description	string	Beskrivningen av den färdighet som beskriver indata, utdata och användning av färdigheten.
dimensions	integer (int32)	Antalet dimensioner som resulterande inbäddningar av utdata ska ha. Stöds endast i text-inbäddning-3 och senare modeller.
inputs	InputFieldMappingEntry[]	Indata för färdigheterna kan vara en kolumn i källdatauppsättningen eller utdata från en överordnad färdighet.
modelName	AzureOpenAIModelName	Namnet på den inbäddningsmodell som distribueras på den angivna deploymentId-sökvägen.
name	string	Namnet på den färdighet som unikt identifierar den inom kompetensuppsättningen. En färdighet utan definierat namn får ett standardnamn för sitt 1-baserade index i kunskapsmatrisen, prefixet med tecknet '#'.
outputs	OutputFieldMappingEntry[]	Utdata från en färdighet är antingen ett fält i ett sökindex eller ett värde som kan användas som indata av en annan färdighet.
resourceUri	string (uri)	Resurs-URI för Azure OpenAI-resursen.

AzureOpenAIModelName

Uppräkning

Namnet på Azure Open AI-modellen som ska anropas.

Värde	Beskrivning
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

Objekt

Anger parametrarna för att ansluta till Azure OpenAI-resursen.

Namn	Typ	Beskrivning
apiKey	string	API-nyckeln för den avsedda Azure OpenAI-resursen.
authIdentity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	Den användartilldelade hanterade identiteten som används för utgående anslutningar.
deploymentId	string	ID för Azure OpenAI-modelldistributionen på den avsedda resursen.
modelName	AzureOpenAIModelName	Namnet på den inbäddningsmodell som distribueras på den angivna deploymentId-sökvägen.
resourceUri	string (uri)	Resurs-URI för Azure OpenAI-resursen.

ErrorAdditionalInfo

Objekt

Ytterligare information om resurshanteringsfelet.

Namn	Typ	Beskrivning
info	object	Ytterligare information.
type	string	Ytterligare informationstyp.

ErrorDetail

Objekt

Felinformationen.

Namn	Typ	Beskrivning
additionalInfo	ErrorAdditionalInfo[]	Ytterligare information om felet.
code	string	Felkoden.
details	ErrorDetail[]	Felinformationen.
message	string	Felmeddelandet.
target	string	Felmålet.

ErrorResponse

Objekt

Felsvar

Namn	Typ	Beskrivning
error	ErrorDetail	Felobjektet.

InputFieldMappingEntry

Objekt

Mappning av indatafält för en färdighet.

Namn	Typ	Beskrivning
inputs	InputFieldMappingEntry[]	De rekursiva indata som används när du skapar en komplex typ.
name	string	Namnet på indata.
source	string	Källan för indata.
sourceContext	string	Källkontexten som används för att välja rekursiva indata.

KnowledgeAgent

Objekt

Namn	Typ	Beskrivning
@odata.etag	string	ETag för agenten.
description	string	Beskrivningen av agenten.
encryptionKey	SearchResourceEncryptionKey	En beskrivning av en krypteringsnyckel som du skapar i Azure Key Vault. Den här nyckeln används för att ge ytterligare en nivå av kryptering i vila för din agentdefinition när du vill ha fullständig försäkran om att ingen, inte ens Microsoft, kan dekryptera dem. När du har krypterat agentdefinitionen förblir den alltid krypterad. Söktjänsten ignorerar försök att ange den här egenskapen till null. Du kan ändra den här egenskapen efter behov om du vill rotera krypteringsnyckeln. Din agentdefinition påverkas inte. Kryptering med kundhanterade nycklar är inte tillgängligt för kostnadsfria söktjänster och är endast tillgängligt för betaltjänster som skapats den 1 januari 2019 eller senare.
models	KnowledgeAgentModel[]: KnowledgeAgentAzureOpenAIModel[]	Innehåller konfigurationsalternativ för hur du ansluter till AI-modeller.
name	string	Namnet på kunskapsagenten.
requestLimits	KnowledgeAgentRequestLimits	Skyddsräcken för att begränsa hur mycket resurser som används för en enskild agenthämtningsbegäran.
targetIndexes	KnowledgeAgentTargetIndex[]

KnowledgeAgentAzureOpenAIModel

Objekt

Anger den Azure OpenAI-resurs som används för att göra frågeplanering.

Namn	Typ	Beskrivning
azureOpenAIParameters	AzureOpenAIParameters: AzureOpenAIEmbeddingSkill	Innehåller de parametrar som är specifika för Azure OpenAI-modellens slutpunkt.
kind	string: azureOpenAI	Typ av AI-modell.

KnowledgeAgentModelKind

Uppräkning

AI-modellen som ska användas för frågeplanering.

Värde	Beskrivning
azureOpenAI	Använd Azure Open AI-modeller för frågeplanering.

KnowledgeAgentRequestLimits

Objekt

Skyddsräcken för att begränsa hur mycket resurser som används för en enskild agenthämtningsbegäran.

Namn	Typ	Beskrivning
maxOutputSize	integer (int32)	Begränsar den maximala storleken på innehållet i utdata.
maxRuntimeInSeconds	integer (int32)	Den maximala körtiden i sekunder.

KnowledgeAgentTargetIndex

Objekt

Namn	Typ	Beskrivning
defaultIncludeReferenceSourceData	boolean	Anger om referenskälldata ska inkluderas.
defaultMaxDocsForReranker	integer (int32)	Begränsar antalet dokument som övervägs för rangordning.
defaultRerankerThreshold	number (float) minimum: 0 maximum: 4	Ett tröskelvärde för omrankningsresultat (intervall: 0–4).
indexName	string	Namnet på målindexet.

OutputFieldMappingEntry

Objekt

Mappning av utdatafält för en färdighet.

Namn	Typ	Beskrivning
name	string	Namnet på utdata som definieras av färdigheten.
targetName	string	Utdatans målnamn. Det är valfritt och standardnamn.

SearchIndexerDataNoneIdentity

Objekt

Rensar identitetsegenskapen för en datakälla.

Namn	Typ	Beskrivning
@odata.type	string: #Microsoft.Azure.Search.DataNoneIdentity	Ett URI-fragment som anger typen av identitet.

SearchIndexerDataUserAssignedIdentity

Objekt

Anger identiteten för en datakälla som ska användas.

Namn	Typ	Beskrivning
@odata.type	string: #Microsoft.Azure.Search.DataUserAssignedIdentity	Ett URI-fragment som anger typen av identitet.
userAssignedIdentity	string	Det fullständigt kvalificerade Azure-resurs-ID:t för en användartilldelad hanterad identitet, vanligtvis i formuläret "/subscriptions/12345678-1234-1234-1234567890ab/resourceGroups/rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myId" som borde ha tilldelats söktjänsten.

SearchResourceEncryptionKey

Objekt

En kundhanterad krypteringsnyckel i Azure Key Vault. Nycklar som du skapar och hanterar kan användas för att kryptera eller dekryptera vilande data, till exempel index och synonymkartor.

Namn	Typ	Beskrivning
accessCredentials	AzureActiveDirectoryApplicationCredentials	Valfria Azure Active Directory-autentiseringsuppgifter som används för att komma åt ditt Azure Key Vault. Krävs inte om du använder hanterad identitet i stället.
identity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	En explicit hanterad identitet som ska användas för den här krypteringsnyckeln. Om det inte anges och egenskapen för åtkomstautentiseringsuppgifter är null används den systemtilldelade hanterade identiteten. Om den explicita identiteten är ospecificerad vid uppdatering av resursen förblir den oförändrad. Om "ingen" anges rensas värdet för den här egenskapen.
keyVaultKeyName	string	Namnet på din Azure Key Vault-nyckel som ska användas för att kryptera dina vilande data.
keyVaultKeyVersion	string	Den version av Azure Key Vault-nyckeln som ska användas för att kryptera dina vilande data.
keyVaultUri	string	URI:n för ditt Azure Key Vault, även kallat DNS-namn, som innehåller nyckeln som ska användas för att kryptera dina data i vila. Ett exempel på en URI kan vara `https://my-keyvault-name.vault.azure.net`.