Knowledge Agents - Create Or Update

Tjänst:: Search Service

API-versionen:: 2025-08-01-preview

Skapar en ny agent eller uppdaterar en agent om den redan finns.

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

URI-parametrar

Namn	I	Krävs	Typ	Beskrivning
agentName	path	True	string	Namnet på agenten som ska skapas eller uppdateras.
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 skickades med begäran för att hjälpa till med felsökning.
If-Match		string	Definierar villkoret If-Match. Åtgärden utförs endast om ETag på servern matchar det här värdet.
If-None-Match		string	Definierar villkoret Om-None-Match. Åtgärden utförs endast om ETag på servern inte matchar det här värdet.
Prefer	True	string	För HTTP PUT-begäranden instruerar tjänsten att returnera den skapade/uppdaterade resursen när den lyckas.

Begäranarorgan

Namn	Krävs	Typ	Beskrivning
knowledgeSources	True	KnowledgeSourceReference[]
models	True	KnowledgeAgentModel[]: KnowledgeAgentAzureOpenAIModel[]	Innehåller konfigurationsalternativ för hur du ansluter till AI-modeller.
name	True	string	Namnet på kunskapsagenten.
@odata.etag		string	ETag för agenten.
description		string	Beskrivningen av agenten.
encryptionKey		SearchResourceEncryptionKey	En beskrivning av en krypteringsnyckel som du skapar i Azure 密钥保管库. 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.
outputConfiguration		KnowledgeAgentOutputConfiguration
requestLimits		KnowledgeAgentRequestLimits	Skyddsräcken för att begränsa hur mycket resurser som används för en enskild agenthämtningsbegäran.
retrievalInstructions		string	Instruktioner som beaktas av kunskapsagenten när du utvecklar frågeplanen.

Svaren

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

Exempel

SearchServiceCreateOrUpdateKnowledgeAgent

Exempelförfrågan

HTTP

PUT https://previewexampleservice.search.windows.net/agents('agent-preview-test')?api-version=2025-08-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"
    }
  ],
  "knowledgeSources": [
    {
      "name": "ks-preview-test",
      "includeReferences": true,
      "includeReferenceSourceData": true,
      "alwaysQuerySource": true,
      "maxSubQueries": 5,
      "rerankerThreshold": 2.1
    }
  ],
  "outputConfiguration": {
    "modality": "extractiveData",
    "answerInstructions": "Provide a concise answer to the question.",
    "attemptFastPath": false,
    "includeActivity": true
  },
  "requestLimits": {
    "maxRuntimeInSeconds": 60,
    "maxOutputSize": 100000
  },
  "retrievalInstructions": "Instructions for retrieval for the agent.",
  "@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."
}

Exempelsvar

Statuskod:: 200

{
  "@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": "api-key",
        "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>"
    }
  }
}

Statuskod:: 201

{
  "@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": "api-key",
        "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>"
    }
  }
}

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 inmatningsfä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.
KnowledgeAgentOutputConfiguration
KnowledgeAgentOutputConfigurationModality	Utdatakonfigurationen för agenten
KnowledgeAgentRequestLimits	Skyddsräcken för att begränsa hur mycket resurser som används för en enskild agenthämtningsbegäran.
KnowledgeSourceReference
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 密钥保管库. Nycklar som du skapar och hanterar kan användas för att kryptera eller dekryptera vilande data, till exempel index och synonymmappningar.

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 de åtkomstbehörigheter som krävs för att Azure Key Vault ska användas när du krypterar dina vilande data. Program-ID:t ska 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 färdighet.
apiKey	string	API-nyckel för den angivna 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å på vilken åtgärder utförs, till exempel dokumentets rot eller dokumentinnehåll (till exempel /document eller /document/content). Standardvärdet är /document.
deploymentId	string	ID för Azure OpenAI-modelldistributionen på den angivna resursen.
description	string	Beskrivningen av färdigheten 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-embedding-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å inbäddningsmodellen som distribueras på den angivna deploymentId-sökvägen.
name	string	Namnet på färdigheten som unikt identifierar den i kompetensuppsättningen. En färdighet utan definierat namn får ett standardnamn för dess 1-baserade index i kompetensmatrisen, med prefixet "#".
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:n 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-nyckel för den angivna 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 angivna resursen.
modelName	AzureOpenAIModelName	Namnet på inbäddningsmodellen som distribueras på den angivna deploymentId-sökvägen.
resourceUri	string (uri)	Resurs-URI:n 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 inmatningsfält för en färdighet.

Namn	Typ	Beskrivning
inputs	InputFieldMappingEntry[]	Rekursiva indata som används när du skapar en komplex typ.
name	string	Namnet på indata.
source	string	Källan till 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 密钥保管库. 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.
knowledgeSources	KnowledgeSourceReference[]
models	KnowledgeAgentModel[]: KnowledgeAgentAzureOpenAIModel[]	Innehåller konfigurationsalternativ för hur du ansluter till AI-modeller.
name	string	Namnet på kunskapsagenten.
outputConfiguration	KnowledgeAgentOutputConfiguration
requestLimits	KnowledgeAgentRequestLimits	Skyddsräcken för att begränsa hur mycket resurser som används för en enskild agenthämtningsbegäran.
retrievalInstructions	string	Instruktioner som beaktas av kunskapsagenten när du utvecklar frågeplanen.

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.

KnowledgeAgentOutputConfiguration

Objekt

Namn	Typ	Beskrivning
answerInstructions	string	Instruktioner som kunskapsagenten tar hänsyn till när svar genereras
attemptFastPath	boolean	Anger om agenten ska försöka utfärda det senaste chattmeddelandet som en direkt fråga till kunskapskällorna, utan modellanropen.
includeActivity	boolean	Anger att hämtningsresultaten ska innehålla aktivitetsinformation.
modality	KnowledgeAgentOutputConfigurationModality	Utdatakonfigurationen för agenten

KnowledgeAgentOutputConfigurationModality

Uppräkning

Utdatakonfigurationen för agenten

Värde	Beskrivning
answerSynthesis	Syntetisera ett svar för svarsnyttolasten.
extractiveData	Returnera data från kunskapskällorna direkt utan generativ förändring.

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.

KnowledgeSourceReference

Objekt

Namn	Typ	Beskrivning
alwaysQuerySource	boolean	Anger att den här kunskapskällan ska kringgå valet av källa och alltid efterfrågas vid hämtningen.
includeReferenceSourceData	boolean	Anger om referenser ska innehålla strukturerade data som erhålls under hämtningen i nyttolasten.
includeReferences	boolean	Anger om referenser ska inkluderas för data som hämtas från den här källan.
maxSubQueries	integer (int32)	Det maximala antalet frågor som kan utfärdas i taget när du hämtar data från den här källan.
name	string	Namnet på kunskapskällan.
rerankerThreshold	number (float)	Tröskelvärdet för omrankning som alla hämtade dokument måste uppfylla för att tas med i svaret.

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	Målnamnet för utdata. Det är valfritt och standardvärdet är namn.

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 formatet "/subscriptions/12345678-1234-1234-1234-1234567890ab/resourceGroups/rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myId" som skulle ha tilldelats till söktjänsten.

SearchResourceEncryptionKey

Objekt

En kundhanterad krypteringsnyckel i Azure 密钥保管库. Nycklar som du skapar och hanterar kan användas för att kryptera eller dekryptera vilande data, till exempel index och synonymmappningar.

Namn	Typ	Beskrivning
accessCredentials	AzureActiveDirectoryApplicationCredentials	Valfria Azure Active Directory-autentiseringsuppgifter som används för att komma åt din 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 inget anges och egenskapen för autentiseringsuppgifter för åtkomst är null används den system tilldelade hanterade identiteten. Vid uppdatering av resursen, om den explicita identiteten är ospecificerad, 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 din Azure Key Vault-nyckel som ska användas för att kryptera dina vilande data.
keyVaultUri	string	URI:n för din Azure Key Vault, även kallat DNS-namn, som innehåller nyckeln som ska användas för att kryptera dina vilande data. Ett exempel på en URI kan vara `https://my-keyvault-name.vault.azure.net`.