Knowledge Agents - Create Or Update

Usługa:: Search Service

Wersja API:: 2025-08-01-preview

Tworzy nowego agenta lub aktualizuje agenta, jeśli już istnieje.

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

Parametry URI

Nazwa	W	Wymagane	Typ	Opis
agentName	path	True	string	Nazwa agenta, który ma zostać utworzony lub zaktualizowany.
endpoint	path	True	string	Adres URL punktu końcowego usługi wyszukiwania.
api-version	query	True	string	Wersja interfejsu API klienta.

Nagłówek żądania

Nazwa	Wymagane	Typ	Opis
x-ms-client-request-id		string (uuid)	Identyfikator śledzenia wysłany z żądaniem, aby pomóc w debugowaniu.
If-Match		string	Definiuje warunek If-Match. Operacja zostanie wykonana tylko wtedy, gdy element ETag na serwerze jest zgodny z tą wartością.
If-None-Match		string	Definiuje warunek If-None-Match. Operacja zostanie wykonana tylko wtedy, gdy element ETag na serwerze nie jest zgodny z tą wartością.
Prefer	True	string	W przypadku żądań HTTP PUT instruuje usługę, aby zwróciła utworzony/zaktualizowany zasób w przypadku powodzenia.

Ciało żądania

Nazwa	Wymagane	Typ	Opis
knowledgeSources	True	KnowledgeSourceReference[]
models	True	KnowledgeAgentModel[]: KnowledgeAgentAzureOpenAIModel[]	Zawiera opcje konfiguracji dotyczące sposobu nawiązywania połączenia z modelami AI.
name	True	string	Nazwa agenta wiedzy.
@odata.etag		string	Element ETag agenta.
description		string	Opis agenta.
encryptionKey		SearchResourceEncryptionKey	Opis klucza szyfrowania utworzonego w usłudze Azure Key Vault. Ten klucz jest używany w celu zapewnienia dodatkowego poziomu szyfrowania magazynowanych dla definicji agenta, gdy chcesz mieć pełną pewność, że nikt, nawet firma Microsoft, nie może ich odszyfrować. Po zaszyfrowaniu definicji agenta zawsze pozostanie ona zaszyfrowana. Usługa wyszukiwania zignoruje próby ustawienia tej właściwości na wartość null. Możesz zmienić tę właściwość zgodnie z potrzebami, jeśli chcesz obrócić klucz szyfrowania; Nie będzie to miało wpływu na definicję agenta. Szyfrowanie za pomocą kluczy zarządzanych przez klienta nie jest dostępne w przypadku bezpłatnych usług wyszukiwania i jest dostępne tylko w przypadku płatnych usług utworzonych 1 stycznia 2019 r. lub później.
outputConfiguration		KnowledgeAgentOutputConfiguration
requestLimits		KnowledgeAgentRequestLimits	Bariery ochronne ograniczające ilość zasobów wykorzystywanych dla pojedynczego żądania pobrania agenta.
retrievalInstructions		string	Instrukcje uwzględniane przez agenta wiedzy podczas opracowywania planu zapytania.

Odpowiedzi

Nazwa	Typ	Opis
200 OK	KnowledgeAgent
201 Created	KnowledgeAgent
Other Status Codes	ErrorResponse	Odpowiedź na błąd.

Przykłady

SearchServiceCreateOrUpdateKnowledgeAgent

Przykładowa prośba

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."
}

Przykładowa odpowiedź

Kod statusu:: 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>"
    }
  }
}

Kod statusu:: 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>"
    }
  }
}

Definicje

Nazwa	Opis
AzureActiveDirectoryApplicationCredentials	Poświadczenia zarejestrowanej aplikacji utworzonej dla usługi wyszukiwania, używanej do uwierzytelnionego dostępu do kluczy szyfrowania przechowywanych w usłudze Azure Key Vault.
AzureOpenAIEmbeddingSkill	Umożliwia wygenerowanie osadzania wektora dla danego tekstu wejściowego przy użyciu zasobu usługi Azure OpenAI.
AzureOpenAIModelName	Nazwa modelu Azure Open AI, który zostanie wywołany.
AzureOpenAIParameters	Określa parametry nawiązywania połączenia z zasobem usługi Azure OpenAI.
ErrorAdditionalInfo	Dodatkowe informacje o błędzie zarządzania zasobami.
ErrorDetail	Szczegóły błędu.
ErrorResponse	Odpowiedź na błąd
InputFieldMappingEntry	Mapowanie pól wejściowych dla umiejętności.
KnowledgeAgent
KnowledgeAgentAzureOpenAIModel	Określa zasób usługi Azure OpenAI używany do planowania zapytań.
KnowledgeAgentModelKind	Model sztucznej inteligencji, który ma być używany do planowania zapytań.
KnowledgeAgentOutputConfiguration
KnowledgeAgentOutputConfigurationModality	Konfiguracja wyjściowa agenta
KnowledgeAgentRequestLimits	Bariery ochronne ograniczające ilość zasobów wykorzystywanych dla pojedynczego żądania pobrania agenta.
KnowledgeSourceReference
OutputFieldMappingEntry	Mapowanie pola wyjściowego dla umiejętności.
SearchIndexerDataNoneIdentity	Czyści właściwość tożsamości źródła danych.
SearchIndexerDataUserAssignedIdentity	Określa tożsamość źródła danych, które ma być używane.
SearchResourceEncryptionKey	Klucz szyfrowania zarządzany przez klienta w usłudze Azure Key Vault. Klucze, które tworzysz i którymi zarządzasz, mogą służyć do szyfrowania lub odszyfrowywania danych magazynowanych, takich jak indeksy i mapy synonimów.

AzureActiveDirectoryApplicationCredentials

Sprzeciwiać się

Poświadczenia zarejestrowanej aplikacji utworzonej dla usługi wyszukiwania, używanej do uwierzytelnionego dostępu do kluczy szyfrowania przechowywanych w usłudze Azure Key Vault.

Nazwa	Typ	Opis
applicationId	string	Identyfikator aplikacji usługi AAD, któremu udzielono wymaganych uprawnień dostępu do usługi Azure Key Vault, który ma być używany podczas szyfrowania danych magazynowanych. Identyfikatora aplikacji nie należy mylić z identyfikatorem obiektu aplikacji usługi AAD.
applicationSecret	string	Klucz uwierzytelniania określonej aplikacji usługi AAD.

AzureOpenAIEmbeddingSkill

Sprzeciwiać się

Umożliwia wygenerowanie osadzania wektora dla danego tekstu wejściowego przy użyciu zasobu usługi Azure OpenAI.

Nazwa	Typ	Opis
@odata.type	string: #Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill	Fragment identyfikatora URI określający typ umiejętności.
apiKey	string	Klucz interfejsu API wyznaczonego zasobu usługi Azure OpenAI.
authIdentity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	Tożsamość zarządzana przypisana przez użytkownika używana dla połączeń wychodzących.
context	string	Reprezentuje poziom, na którym są wykonywane operacje, na przykład katalog główny dokumentu lub zawartość dokumentu (na przykład /document lub /document/content). Wartość domyślna to /document.
deploymentId	string	Identyfikator wdrożenia modelu usługi Azure OpenAI w wyznaczonym zasobie.
description	string	Opis umiejętności, który opisuje dane wejściowe, wyjściowe i użycie umiejętności.
dimensions	integer (int32)	Liczba wymiarów, które powinny mieć wynikowe osadzanie danych wyjściowych. Obsługiwane tylko w modelach text-embedding-3 i nowszych.
inputs	InputFieldMappingEntry[]	Dane wejściowe umiejętności mogą być kolumną w źródłowym zestawie danych lub danymi wyjściowymi umiejętności nadrzędnej.
modelName	AzureOpenAIModelName	Nazwa modelu osadzania, który jest wdrażany w podanej ścieżce deploymentId.
name	string	Nazwa umiejętności, która jednoznacznie identyfikuje ją w zestawie umiejętności. Umiejętność, która nie ma zdefiniowanej nazwy, otrzyma domyślną nazwę indeksu opartego na liczbie 1 w tablicy umiejętności, poprzedzoną znakiem "#".
outputs	OutputFieldMappingEntry[]	Dane wyjściowe umiejętności są albo polem w indeksie wyszukiwania, albo wartością, która może być używana jako dane wejściowe przez inną umiejętność.
resourceUri	string (uri)	Identyfikator URI zasobu usługi Azure OpenAI.

AzureOpenAIModelName

Wyliczenie

Nazwa modelu Azure Open AI, który zostanie wywołany.

Wartość	Opis
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

Sprzeciwiać się

Określa parametry nawiązywania połączenia z zasobem usługi Azure OpenAI.

Nazwa	Typ	Opis
apiKey	string	Klucz interfejsu API wyznaczonego zasobu usługi Azure OpenAI.
authIdentity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	Tożsamość zarządzana przypisana przez użytkownika używana dla połączeń wychodzących.
deploymentId	string	Identyfikator wdrożenia modelu usługi Azure OpenAI w wyznaczonym zasobie.
modelName	AzureOpenAIModelName	Nazwa modelu osadzania, który jest wdrażany w podanej ścieżce deploymentId.
resourceUri	string (uri)	Identyfikator URI zasobu usługi Azure OpenAI.

ErrorAdditionalInfo

Sprzeciwiać się

Dodatkowe informacje o błędzie zarządzania zasobami.

Nazwa	Typ	Opis
info	object	Dodatkowe informacje.
type	string	Dodatkowy typ informacji.

ErrorDetail

Sprzeciwiać się

Szczegóły błędu.

Nazwa	Typ	Opis
additionalInfo	ErrorAdditionalInfo[]	Dodatkowe informacje o błędzie.
code	string	Kod błędu.
details	ErrorDetail[]	Szczegóły błędu.
message	string	Komunikat o błędzie.
target	string	Element docelowy błędu.

ErrorResponse

Sprzeciwiać się

Odpowiedź na błąd

Nazwa	Typ	Opis
error	ErrorDetail	Obiekt błędu.

InputFieldMappingEntry

Sprzeciwiać się

Mapowanie pól wejściowych dla umiejętności.

Nazwa	Typ	Opis
inputs	InputFieldMappingEntry[]	Rekurencyjne dane wejściowe używane podczas tworzenia typu złożonego.
name	string	Nazwa danych wejściowych.
source	string	Źródło danych wejściowych.
sourceContext	string	Kontekst źródłowy używany do wybierania rekurencyjnych danych wejściowych.

KnowledgeAgent

Sprzeciwiać się

Nazwa	Typ	Opis
@odata.etag	string	Element ETag agenta.
description	string	Opis agenta.
encryptionKey	SearchResourceEncryptionKey	Opis klucza szyfrowania utworzonego w usłudze Azure Key Vault. Ten klucz jest używany w celu zapewnienia dodatkowego poziomu szyfrowania magazynowanych dla definicji agenta, gdy chcesz mieć pełną pewność, że nikt, nawet firma Microsoft, nie może ich odszyfrować. Po zaszyfrowaniu definicji agenta zawsze pozostanie ona zaszyfrowana. Usługa wyszukiwania zignoruje próby ustawienia tej właściwości na wartość null. Możesz zmienić tę właściwość zgodnie z potrzebami, jeśli chcesz obrócić klucz szyfrowania; Nie będzie to miało wpływu na definicję agenta. Szyfrowanie za pomocą kluczy zarządzanych przez klienta nie jest dostępne w przypadku bezpłatnych usług wyszukiwania i jest dostępne tylko w przypadku płatnych usług utworzonych 1 stycznia 2019 r. lub później.
knowledgeSources	KnowledgeSourceReference[]
models	KnowledgeAgentModel[]: KnowledgeAgentAzureOpenAIModel[]	Zawiera opcje konfiguracji dotyczące sposobu nawiązywania połączenia z modelami AI.
name	string	Nazwa agenta wiedzy.
outputConfiguration	KnowledgeAgentOutputConfiguration
requestLimits	KnowledgeAgentRequestLimits	Bariery ochronne ograniczające ilość zasobów wykorzystywanych dla pojedynczego żądania pobrania agenta.
retrievalInstructions	string	Instrukcje uwzględniane przez agenta wiedzy podczas opracowywania planu zapytania.

KnowledgeAgentAzureOpenAIModel

Sprzeciwiać się

Określa zasób usługi Azure OpenAI używany do planowania zapytań.

Nazwa	Typ	Opis
azureOpenAIParameters	AzureOpenAIParameters: AzureOpenAIEmbeddingSkill	Zawiera parametry specyficzne dla punktu końcowego modelu usługi Azure OpenAI.
kind	string: azureOpenAI	Typ modelu AI.

KnowledgeAgentModelKind

Wyliczenie

Model sztucznej inteligencji, który ma być używany do planowania zapytań.

Wartość	Opis
azureOpenAI	Używanie modeli sztucznej inteligencji usługi Azure Open do planowania zapytań.

KnowledgeAgentOutputConfiguration

Sprzeciwiać się

Nazwa	Typ	Opis
answerInstructions	string	Instrukcje uwzględniane przez agenta wiedzy podczas generowania odpowiedzi
attemptFastPath	boolean	Wskazuje, czy agent powinien podjąć próbę wysłania najnowszej wiadomości czatu jako bezpośredniego zapytania do źródeł wiedzy, pomijając wywołania modelu.
includeActivity	boolean	Wskazuje, że wyniki pobierania powinny zawierać informacje o aktywności.
modality	KnowledgeAgentOutputConfigurationModality	Konfiguracja wyjściowa agenta

KnowledgeAgentOutputConfigurationModality

Wyliczenie

Konfiguracja wyjściowa agenta

Wartość	Opis
answerSynthesis	Zsyntetyzuj odpowiedź dla ładunku odpowiedzi.
extractiveData	Zwracanie danych ze źródeł wiedzy bezpośrednio bez generatywnych zmian.

KnowledgeAgentRequestLimits

Sprzeciwiać się

Bariery ochronne ograniczające ilość zasobów wykorzystywanych dla pojedynczego żądania pobrania agenta.

Nazwa	Typ	Opis
maxOutputSize	integer (int32)	Ogranicza maksymalny rozmiar zawartości w danych wyjściowych.
maxRuntimeInSeconds	integer (int32)	Maksymalny czas pracy w sekundach.

KnowledgeSourceReference

Sprzeciwiać się

Nazwa	Typ	Opis
alwaysQuerySource	boolean	Wskazuje, że to źródło wiedzy powinno pomijać wybór źródła i zawsze być odpytywane w czasie pobierania.
includeReferenceSourceData	boolean	Wskazuje, czy odwołania powinny zawierać w swoim ładunku uporządkowane dane uzyskane podczas pobierania.
includeReferences	boolean	Wskazuje, czy odwołania powinny być uwzględniane dla danych pobranych z tego źródła.
maxSubQueries	integer (int32)	Maksymalna liczba zapytań, które mogą zostać wysłane w momencie pobierania danych z tego źródła.
name	string	Nazwa źródła wiedzy.
rerankerThreshold	number (float)	Próg rerankera, który muszą spełniać wszystkie pobrane dokumenty, aby mogły zostać uwzględnione w odpowiedzi.

OutputFieldMappingEntry

Sprzeciwiać się

Mapowanie pola wyjściowego dla umiejętności.

Nazwa	Typ	Opis
name	string	Nazwa danych wyjściowych zdefiniowanych przez umiejętność.
targetName	string	Docelowa nazwa danych wyjściowych. Jest to opcjonalne i domyślnie ma nazwę użytkownika.

SearchIndexerDataNoneIdentity

Sprzeciwiać się

Czyści właściwość tożsamości źródła danych.

Nazwa	Typ	Opis
@odata.type	string: #Microsoft.Azure.Search.DataNoneIdentity	Fragment identyfikatora URI określający typ tożsamości.

SearchIndexerDataUserAssignedIdentity

Sprzeciwiać się

Określa tożsamość źródła danych, które ma być używane.

Nazwa	Typ	Opis
@odata.type	string: #Microsoft.Azure.Search.DataUserAssignedIdentity	Fragment identyfikatora URI określający typ tożsamości.
userAssignedIdentity	string	W pełni kwalifikowany identyfikator zasobu platformy Azure tożsamości zarządzanej przypisanej przez użytkownika zwykle w postaci "/subscriptions/12345678-1234-1234-1234-1234567890ab/resourceGroups/rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/myId", który powinien zostać przypisany do usługi wyszukiwania.

SearchResourceEncryptionKey

Sprzeciwiać się

Klucz szyfrowania zarządzany przez klienta w usłudze Azure Key Vault. Klucze, które tworzysz i którymi zarządzasz, mogą służyć do szyfrowania lub odszyfrowywania danych magazynowanych, takich jak indeksy i mapy synonimów.

Nazwa	Typ	Opis
accessCredentials	AzureActiveDirectoryApplicationCredentials	Opcjonalne poświadczenia usługi Azure Active Directory używane do uzyskiwania dostępu do usługi Azure Key Vault. Nie jest to wymagane, jeśli zamiast tego używasz tożsamości zarządzanej.
identity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	Jawna tożsamość zarządzana do użycia dla tego klucza szyfrowania. Jeśli nie zostanie określona, a właściwość poświadczeń dostępu ma wartość null, zostanie użyta tożsamość zarządzana przypisana przez system. Podczas aktualizacji zasobu, jeśli jawna tożsamość nie jest określona, pozostaje niezmieniona. Jeśli określono wartość "none", wartość tej właściwości jest czyszczona.
keyVaultKeyName	string	Nazwa klucza usługi Azure Key Vault, który ma być używany do szyfrowania danych magazynowanych.
keyVaultKeyVersion	string	Wersja klucza usługi Azure Key Vault, która ma być używana do szyfrowania danych magazynowanych.
keyVaultUri	string	Identyfikator URI usługi Azure Key Vault, nazywany również nazwą DNS, który zawiera klucz, który ma być używany do szyfrowania danych magazynowanych. Przykładowym identyfikatorem URI może być `https://my-keyvault-name.vault.azure.net`.