Knowledge Agents - Create Or Update

Usługa:: Search Service

Wersja API:: 2025-05-01-preview

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

PUT {endpoint}/agents('{agentName}')?api-version=2025-05-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 ułatwić debugowanie.
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 nakazuje usłudze zwrócenie utworzonego/zaktualizowanego zasobu w przypadku powodzenia.

Ciało żądania

Nazwa	Wymagane	Typ	Opis
models	True	KnowledgeAgentModel[]: KnowledgeAgentAzureOpenAIModel[]	Zawiera opcje konfiguracji dotyczące sposobu nawiązywania połączenia z modelami AI.
name	True	string	Nazwa agenta wiedzy.
targetIndexes	True	KnowledgeAgentTargetIndex[]
@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 dla bezpłatnych usług wyszukiwania i jest dostępne tylko dla płatnych usług utworzonych w dniu 1 stycznia 2019 r. lub po 1 stycznia 2019 r.
requestLimits		KnowledgeAgentRequestLimits	Bariery ochronne ograniczające ilość zasobów wykorzystywanych dla pojedynczego żądania pobrania agenta.

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-05-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"
    }
  ],
  "targetIndexes": [
    {
      "indexName": "preview-test",
      "defaultRerankerThreshold": 2.5,
      "defaultIncludeReferenceSourceData": true,
      "defaultMaxDocsForReranker": 100
    }
  ],
  "requestLimits": {
    "maxRuntimeInSeconds": 60,
    "maxOutputSize": 100000
  },
  "@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.",
  "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": "api-key",
        "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>"
    }
  }
}

Kod statusu:: 201

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

Definicje

Nazwa	Opis
AzureActiveDirectoryApplicationCredentials	Poświadczenia zarejestrowanej aplikacji utworzonej dla usługi wyszukiwania używane do uwierzytelnionego dostępu do kluczy szyfrowania przechowywanych w usłudze Azure Key Vault.
AzureOpenAIEmbeddingSkill	Umożliwia wygenerowanie wektora osadzania dla danego tekstu wejściowego przy użyciu zasobu Azure OpenAI.
AzureOpenAIModelName	Nazwa modelu usługi Azure Open AI, która zostanie wywołana.
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ń.
KnowledgeAgentRequestLimits	Bariery ochronne ograniczające ilość zasobów wykorzystywanych dla pojedynczego żądania pobrania agenta.
KnowledgeAgentTargetIndex
OutputFieldMappingEntry	Mapowanie pól wyjściowych 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 do użycia.
SearchResourceEncryptionKey	Klucz szyfrowania zarządzany przez klienta w usłudze Azure Key Vault. Klucze tworzone i zarządzane 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żywane 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óra ma być używana podczas szyfrowania danych magazynowanych. Identyfikator aplikacji nie powinien być mylony z identyfikatorem obiektu aplikacji usługi AAD.
applicationSecret	string	Klucz uwierzytelniania określonej aplikacji usługi AAD.

AzureOpenAIEmbeddingSkill

Sprzeciwiać się

Umożliwia wygenerowanie wektora osadzania dla danego tekstu wejściowego przy użyciu zasobu 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 na potrzeby połączeń wychodzących.
context	string	Reprezentuje poziom, na którym odbywają się operacje, takie jak zawartość katalogu głównego lub dokumentu 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 opisujący dane wejściowe, dane 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 osadzania tekstu-3 i nowszych.
inputs	InputFieldMappingEntry[]	Dane wejściowe umiejętności mogą być kolumną w zestawie danych źródłowych lub danymi wyjściowymi umiejętności nadrzędnych.
modelName	AzureOpenAIModelName	Nazwa modelu osadzania wdrożonego w podanej ścieżce deploymentId.
name	string	Nazwa umiejętności, która jednoznacznie identyfikuje ją w zestawie umiejętności. Umiejętność bez zdefiniowanej nazwy będzie mieć domyślną nazwę swojego 1-opartego na indeksie w tablicy umiejętności, poprzedzoną znakiem "#".
outputs	OutputFieldMappingEntry[]	Dane wyjściowe umiejętności to pole w indeksie wyszukiwania lub wartość, która może być zużywana jako dane wejściowe przez inną umiejętność.
resourceUri	string (uri)	Identyfikator URI zasobu usługi Azure OpenAI.

AzureOpenAIModelName

Wyliczenie

Nazwa modelu usługi Azure Open AI, która zostanie wywołana.

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 na potrzeby połączeń wychodzących.
deploymentId	string	Identyfikator wdrożenia modelu Usługi Azure OpenAI w wyznaczonym zasobie.
modelName	AzureOpenAIModelName	Nazwa modelu osadzania wdrożonego 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[]	Rekursywne 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 cyklicznych 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 dla bezpłatnych usług wyszukiwania i jest dostępne tylko dla płatnych usług utworzonych w dniu 1 stycznia 2019 r. lub po 1 stycznia 2019 r.
models	KnowledgeAgentModel[]: KnowledgeAgentAzureOpenAIModel[]	Zawiera opcje konfiguracji dotyczące sposobu nawiązywania połączenia z modelami AI.
name	string	Nazwa agenta wiedzy.
requestLimits	KnowledgeAgentRequestLimits	Bariery ochronne ograniczające ilość zasobów wykorzystywanych dla pojedynczego żądania pobrania agenta.
targetIndexes	KnowledgeAgentTargetIndex[]

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ń.

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.

KnowledgeAgentTargetIndex

Sprzeciwiać się

Nazwa	Typ	Opis
defaultIncludeReferenceSourceData	boolean	Wskazuje, czy należy uwzględnić dane źródła odniesienia.
defaultMaxDocsForReranker	integer (int32)	Ogranicza liczbę dokumentów branych pod uwagę przy klasyfikowaniu.
defaultRerankerThreshold	number (float) minimum: 0 maximum: 4	Próg ponownego klasyfikowania wyników (zakres: 0–4).
indexName	string	Nazwa indeksu docelowego.

OutputFieldMappingEntry

Sprzeciwiać się

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

Nazwa	Typ	Opis
name	string	Nazwa danych wyjściowych zdefiniowanych przez umiejętności.
targetName	string	Nazwa docelowa danych wyjściowych. Jest to opcjonalne i domyślne nazwa.

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 do użycia.

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 przypisanej przez użytkownika tożsamości zarządzanej zazwyczaj 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 tworzone i zarządzane 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 wymagane, jeśli zamiast tego używasz tożsamości zarządzanej.
identity	SearchIndexerDataIdentity: SearchIndexerDataNoneIdentity SearchIndexerDataUserAssignedIdentity	Jawna tożsamość zarządzana używana 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. Po zaktualizowaniu zasobu, jeśli tożsamość jawna jest nieokreślona, pozostaje niezmieniona. Jeśli określono wartość "none", wartość tej właściwości zostanie wyczyszczone.
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 używany do szyfrowania danych magazynowanych. Przykładowy identyfikator URI może być `https://my-keyvault-name.vault.azure.net`.