Knowledge Agents - Get

Haalt een agentdefinitie op.

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

URI-parameters

Name In Vereist Type Description
agentName
path True

string

De naam van de agent die moet worden opgehaald.

endpoint
path True

string

De eindpunt-URL van de zoekservice.

api-version
query True

string

Client-API-versie.

Aanvraagkoptekst

Name Vereist Type Description
x-ms-client-request-id

string (uuid)

De tracking-ID die is verzonden met het verzoek om te helpen bij het opsporen.

Antwoorden

Name Type Description
200 OK

KnowledgeAgent

Other Status Codes

ErrorResponse

Foutreactie.

Voorbeelden

SearchServiceGetKnowledgeAgent

Voorbeeldaanvraag

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

Voorbeeldrespons

{
  "@odata.etag": "0x1234568AE7E58A1",
  "name": "agent-preview-test",
  "description": "Description of the agent.",
  "retrievalInstructions": "Instructions for retrieval for the agent.",
  "knowledgeSources": [
    {
      "name": "ks-preview-test",
      "alwaysQuerySource": true,
      "includeReferences": true,
      "includeReferenceSourceData": true,
      "maxSubQueries": 5,
      "rerankerThreshold": 2.1
    }
  ],
  "models": [
    {
      "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "https://test-sample.openai.azure.com",
        "deploymentId": "myDeployment",
        "apiKey": "<redacted>",
        "modelName": "gpt-4o-mini"
      }
    }
  ],
  "outputConfiguration": {
    "modality": "extractiveData",
    "answerInstructions": "Provide a concise answer to the question.",
    "attemptFastPath": false,
    "includeActivity": true
  },
  "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>"
    }
  }
}

Definities

Name Description
AzureActiveDirectoryApplicationCredentials

Referenties van een geregistreerde toepassing die is gemaakt voor uw zoekservice en die worden gebruikt voor geverifieerde toegang tot de versleutelingssleutels die zijn opgeslagen in Azure Key Vault.

AzureOpenAIEmbeddingSkill

Hiermee kunt u een vectorinbedding genereren voor een bepaalde tekstinvoer met behulp van de Azure OpenAI-resource.

AzureOpenAIModelName

De Azure Open AI-modelnaam die wordt aangeroepen.

AzureOpenAIParameters

Hiermee geeft u de parameters op voor het maken van verbinding met de Azure OpenAI-resource.

ErrorAdditionalInfo

Aanvullende informatie over de resourcebeheerfout.

ErrorDetail

De foutdetails.

ErrorResponse

Foutreactie

InputFieldMappingEntry

Voer veldtoewijzing in voor een vaardigheid.

KnowledgeAgent
KnowledgeAgentAzureOpenAIModel

Hiermee geeft u de Azure OpenAI-resource op die wordt gebruikt om queryplanning uit te voeren.

KnowledgeAgentModelKind

Het AI-model dat moet worden gebruikt voor queryplanning.

KnowledgeAgentOutputConfiguration
KnowledgeAgentOutputConfigurationModality

De uitvoerconfiguratie voor de agent

KnowledgeAgentRequestLimits

Vangrails om te beperken hoeveel middelen worden gebruikt voor een verzoek om één agent op te halen.

KnowledgeSourceReference
OutputFieldMappingEntry

Uitvoerveldtoewijzing voor een vaardigheid.

SearchIndexerDataNoneIdentity

Hiermee wist u de identiteitseigenschap van een gegevensbron.

SearchIndexerDataUserAssignedIdentity

Hiermee geeft u de identiteit op voor een gegevensbron die moet worden gebruikt.

SearchResourceEncryptionKey

Een door de klant beheerde versleutelingssleutel in Azure Key Vault. Sleutels die u maakt en beheert, kunnen worden gebruikt om inactieve gegevens, zoals indexen en synoniementoewijzingen, te versleutelen of te ontsleutelen.

AzureActiveDirectoryApplicationCredentials

Referenties van een geregistreerde toepassing die is gemaakt voor uw zoekservice en die worden gebruikt voor geverifieerde toegang tot de versleutelingssleutels die zijn opgeslagen in Azure Key Vault.

Name Type Description
applicationId

string

Een AAD-toepassings-id waaraan de vereiste toegangsmachtigingen zijn verleend voor de Azure Key Vault die moet worden gebruikt bij het versleutelen van uw gegevens in rust. De applicatie-ID mag niet worden verward met de object-ID voor uw AAD-applicatie.

applicationSecret

string

De authenticatiesleutel van de opgegeven AAD-toepassing.

AzureOpenAIEmbeddingSkill

Hiermee kunt u een vectorinbedding genereren voor een bepaalde tekstinvoer met behulp van de Azure OpenAI-resource.

Name Type Description
@odata.type string:

#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill

Een URI-fragment dat het type vaardigheid specificeert.

apiKey

string

API-sleutel van de aangewezen Azure OpenAI-resource.

authIdentity SearchIndexerDataIdentity:

De door de gebruiker toegewezen beheerde identiteit die wordt gebruikt voor uitgaande verbindingen.

context

string

Vertegenwoordigt het niveau waarop bewerkingen plaatsvinden, zoals de hoofdmap van het document of de inhoud van het document (bijvoorbeeld /document of /document/content). De standaardinstelling is /document.

deploymentId

string

ID van de implementatie van het Azure OpenAI-model op de aangewezen resource.

description

string

De beschrijving van de vaardigheid die de invoer, uitvoer en het gebruik van de vaardigheid beschrijft.

dimensions

integer (int32)

Het aantal dimensies dat de resulterende uitvoer-insluitingen moeten hebben. Alleen ondersteund in modellen met tekstinbedding 3 en hoger.

inputs

InputFieldMappingEntry[]

Invoer van de vaardigheden kan een kolom in de brongegevensset zijn, of de uitvoer van een stroomopwaartse vaardigheid.

modelName

AzureOpenAIModelName

De naam van het inbeddingsmodel dat wordt geïmplementeerd op het opgegeven deploymentId-pad.

name

string

De naam van de vaardigheid die deze op unieke wijze identificeert binnen de vaardighedenset. Een vaardigheid waarvoor geen naam is gedefinieerd, krijgt een standaardnaam van de op 1 gebaseerde index in de vaardigheidsarray, voorafgegaan door het teken '#'.

outputs

OutputFieldMappingEntry[]

De uitvoer van een vaardigheid is een veld in een zoekindex of een waarde die als invoer door een andere vaardigheid kan worden verbruikt.

resourceUri

string (uri)

De resource-URI van de Azure OpenAI-resource.

AzureOpenAIModelName

De Azure Open AI-modelnaam die wordt aangeroepen.

Waarde 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

Hiermee geeft u de parameters op voor het maken van verbinding met de Azure OpenAI-resource.

Name Type Description
apiKey

string

API-sleutel van de aangewezen Azure OpenAI-resource.

authIdentity SearchIndexerDataIdentity:

De door de gebruiker toegewezen beheerde identiteit die wordt gebruikt voor uitgaande verbindingen.

deploymentId

string

ID van de implementatie van het Azure OpenAI-model op de aangewezen resource.

modelName

AzureOpenAIModelName

De naam van het inbeddingsmodel dat wordt geïmplementeerd op het opgegeven deploymentId-pad.

resourceUri

string (uri)

De resource-URI van de Azure OpenAI-resource.

ErrorAdditionalInfo

Aanvullende informatie over de resourcebeheerfout.

Name Type Description
info

object

De aanvullende informatie.

type

string

Het extra informatietype.

ErrorDetail

De foutdetails.

Name Type Description
additionalInfo

ErrorAdditionalInfo[]

De fout bevat aanvullende informatie.

code

string

De foutcode.

details

ErrorDetail[]

De foutdetails.

message

string

Het foutbericht.

target

string

Het foutdoel.

ErrorResponse

Foutreactie

Name Type Description
error

ErrorDetail

Het foutobject.

InputFieldMappingEntry

Voer veldtoewijzing in voor een vaardigheid.

Name Type Description
inputs

InputFieldMappingEntry[]

De recursieve invoer die wordt gebruikt bij het maken van een complex type.

name

string

De naam van de invoer.

source

string

De bron van de input.

sourceContext

string

De broncontext die wordt gebruikt voor het selecteren van recursieve invoer.

KnowledgeAgent

Name Type Description
@odata.etag

string

De ETag van de agent.

description

string

De beschrijving van de agent.

encryptionKey

SearchResourceEncryptionKey

Een beschrijving van een versleutelingssleutel die u maakt in Azure Key Vault. Deze sleutel wordt gebruikt om een extra niveau van versleuteling-at-rest te bieden voor uw agentdefinitie wanneer u volledige zekerheid wilt dat niemand, zelfs Microsoft niet, deze kan ontsleutelen. Zodra u uw agentdefinitie hebt versleuteld, blijft deze altijd versleuteld. De zoekservice negeert pogingen om deze eigenschap op null in te stellen. U kunt deze eigenschap naar wens wijzigen als u uw coderingssleutel wilt roteren; Uw agentdefinitie blijft onaangetast. Versleuteling met door de klant beheerde sleutels is niet beschikbaar voor gratis zoekservices en is alleen beschikbaar voor betaalde services die op of na 1 januari 2019 zijn gemaakt.

knowledgeSources

KnowledgeSourceReference[]

models KnowledgeAgentModel[]:

KnowledgeAgentAzureOpenAIModel[]

Bevat configuratieopties voor het maken van verbinding met AI-modellen.

name

string

De naam van de kennisagent.

outputConfiguration

KnowledgeAgentOutputConfiguration

requestLimits

KnowledgeAgentRequestLimits

Vangrails om te beperken hoeveel middelen worden gebruikt voor een verzoek om één agent op te halen.

retrievalInstructions

string

Instructies waarmee de kennisagent rekening houdt bij het ontwikkelen van een queryplan.

KnowledgeAgentAzureOpenAIModel

Hiermee geeft u de Azure OpenAI-resource op die wordt gebruikt om queryplanning uit te voeren.

Name Type Description
azureOpenAIParameters AzureOpenAIParameters:

AzureOpenAIEmbeddingSkill

Bevat de parameters die specifiek zijn voor het Azure OpenAI-modeleindpunt.

kind string:

azureOpenAI

Het type AI-model.

KnowledgeAgentModelKind

Het AI-model dat moet worden gebruikt voor queryplanning.

Waarde Description
azureOpenAI

Gebruik Azure Open AI-modellen voor het plannen van query's.

KnowledgeAgentOutputConfiguration

Name Type Description
answerInstructions

string

Instructies waarmee de kennisagent rekening houdt bij het genereren van antwoorden

attemptFastPath

boolean

Geeft aan of de agent moet proberen het meest recente chatbericht uit te geven als een directe query naar de kennisbronnen, waarbij de modelaanroepen worden omzeild.

includeActivity

boolean

Geeft aan dat de ophaalresultaten activiteitsinformatie moeten bevatten.

modality

KnowledgeAgentOutputConfigurationModality

De uitvoerconfiguratie voor de agent

KnowledgeAgentOutputConfigurationModality

De uitvoerconfiguratie voor de agent

Waarde Description
answerSynthesis

Synthetiseer een antwoord voor de payload van het antwoord.

extractiveData

Retourneer gegevens uit de kennisbronnen direct zonder generatieve wijziging.

KnowledgeAgentRequestLimits

Vangrails om te beperken hoeveel middelen worden gebruikt voor een verzoek om één agent op te halen.

Name Type Description
maxOutputSize

integer (int32)

Hiermee beperkt u de maximale grootte van de inhoud in de uitvoer.

maxRuntimeInSeconds

integer (int32)

De maximale looptijd in seconden.

KnowledgeSourceReference

Name Type Description
alwaysQuerySource

boolean

Geeft aan dat deze kennisbron de bronselectie moet overslaan en altijd moet worden opgevraagd op het moment dat deze wordt opgehaald.

includeReferenceSourceData

boolean

Geeft aan of referenties de gestructureerde gegevens die tijdens het ophalen zijn verkregen, in hun payload moeten opnemen.

includeReferences

boolean

Geeft aan of referenties moeten worden opgenomen voor gegevens die uit deze bron worden opgehaald.

maxSubQueries

integer (int32)

Het maximale aantal query's dat tegelijk kan worden uitgegeven bij het ophalen van gegevens uit deze bron.

name

string

De naam van de kennisbron.

rerankerThreshold

number (float)

De herrangschikkingsdrempel waaraan alle opgehaalde documenten moeten voldoen om in de reactie te worden opgenomen.

OutputFieldMappingEntry

Uitvoerveldtoewijzing voor een vaardigheid.

Name Type Description
name

string

De naam van de uitvoer die door de vaardigheid wordt gedefinieerd.

targetName

string

De doelnaam van de uitvoer. Het is optioneel en standaard een naam.

SearchIndexerDataNoneIdentity

Hiermee wist u de identiteitseigenschap van een gegevensbron.

Name Type Description
@odata.type string:

#Microsoft.Azure.Search.DataNoneIdentity

Een URI-fragment dat het type identiteit specificeert.

SearchIndexerDataUserAssignedIdentity

Hiermee geeft u de identiteit op voor een gegevensbron die moet worden gebruikt.

Name Type Description
@odata.type string:

#Microsoft.Azure.Search.DataUserAssignedIdentity

Een URI-fragment dat het type identiteit specificeert.

userAssignedIdentity

string

De volledig gekwalificeerde Azure-resource-id van een gebruiker waaraan een beheerde identiteit is toegewezen, meestal in de vorm '/subscriptions/12345678-1234-1234-1234-1234567890ab/resourceGroups/rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myId' die had moeten zijn toegewezen aan de zoekservice.

SearchResourceEncryptionKey

Een door de klant beheerde versleutelingssleutel in Azure Key Vault. Sleutels die u maakt en beheert, kunnen worden gebruikt om inactieve gegevens, zoals indexen en synoniementoewijzingen, te versleutelen of te ontsleutelen.

Name Type Description
accessCredentials

AzureActiveDirectoryApplicationCredentials

Optionele Azure Active Directory-referenties die worden gebruikt voor toegang tot uw Azure Key Vault. Niet vereist als u in plaats daarvan beheerde identiteit gebruikt.

identity SearchIndexerDataIdentity:

Een expliciete beheerde identiteit die u voor deze versleutelingssleutel kunt gebruiken. Als dit niet is opgegeven en de eigenschap toegangsreferenties null is, wordt de door het systeem toegewezen beheerde identiteit gebruikt. Als de expliciete identiteit bij het bijwerken van de resource niet is opgegeven, blijft deze ongewijzigd. Als "geen" is opgegeven, wordt de waarde van deze eigenschap gewist.

keyVaultKeyName

string

De naam van uw Azure Key Vault-sleutel die moet worden gebruikt om uw gegevens in rust te versleutelen.

keyVaultKeyVersion

string

De versie van uw Azure Key Vault-sleutel die moet worden gebruikt om uw gegevens in rust te versleutelen.

keyVaultUri

string

De URI van uw Azure Key Vault, ook wel DNS-naam genoemd, die de sleutel bevat die moet worden gebruikt om uw gegevens in rust te versleutelen. Een voorbeeld van een URI zou kunnen zijn https://my-keyvault-name.vault.azure.net.