Knowledge Agents - Get
Haalt een agentdefinitie op.
GET {endpoint}/agents('{agentName}')?api-version=2025-08-01-preview
URI-parameters
| Name | In | Vereist | Type | Description |
|---|---|---|---|---|
|
agent
|
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 | ||
| Other Status Codes |
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 |
|---|---|
|
Azure |
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. |
|
Azure |
Hiermee kunt u een vectorinbedding genereren voor een bepaalde tekstinvoer met behulp van de Azure OpenAI-resource. |
|
Azure |
De Azure Open AI-modelnaam die wordt aangeroepen. |
|
Azure |
Hiermee geeft u de parameters op voor het maken van verbinding met de Azure OpenAI-resource. |
|
Error |
Aanvullende informatie over de resourcebeheerfout. |
|
Error |
De foutdetails. |
|
Error |
Foutreactie |
|
Input |
Voer veldtoewijzing in voor een vaardigheid. |
|
Knowledge |
|
|
Knowledge |
Hiermee geeft u de Azure OpenAI-resource op die wordt gebruikt om queryplanning uit te voeren. |
|
Knowledge |
Het AI-model dat moet worden gebruikt voor queryplanning. |
|
Knowledge |
|
|
Knowledge |
De uitvoerconfiguratie voor de agent |
|
Knowledge |
Vangrails om te beperken hoeveel middelen worden gebruikt voor een verzoek om één agent op te halen. |
|
Knowledge |
|
|
Output |
Uitvoerveldtoewijzing voor een vaardigheid. |
|
Search |
Hiermee wist u de identiteitseigenschap van een gegevensbron. |
|
Search |
Hiermee geeft u de identiteit op voor een gegevensbron die moet worden gebruikt. |
|
Search |
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. |
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 |
Invoer van de vaardigheden kan een kolom in de brongegevensset zijn, of de uitvoer van een stroomopwaartse vaardigheid. |
|
| modelName |
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 |
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 |
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 |
De fout bevat aanvullende informatie. |
|
| code |
string |
De foutcode. |
| details |
De foutdetails. |
|
| message |
string |
Het foutbericht. |
| target |
string |
Het foutdoel. |
ErrorResponse
Foutreactie
| Name | Type | Description |
|---|---|---|
| error |
Het foutobject. |
InputFieldMappingEntry
Voer veldtoewijzing in voor een vaardigheid.
| Name | Type | Description |
|---|---|---|
| inputs |
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 |
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 | ||
| models | KnowledgeAgentModel[]: |
Bevat configuratieopties voor het maken van verbinding met AI-modellen. |
| name |
string |
De naam van de kennisagent. |
| outputConfiguration | ||
| requestLimits |
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: |
Bevat de parameters die specifiek zijn voor het Azure OpenAI-modeleindpunt. |
| kind |
string:
azure |
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 |
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. |
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. |
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 |
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 |