Migrar o código de recuperação por meio de agentes para a última versão

Nota

Pesquisa de IA do Azure  está disponível por meio do portal Azure, APIs REST e SDKs do Azure. Ele também sustenta o IQ do Foundry, a camada de conhecimento gerenciado que transforma o conteúdo da empresa em bases de conhecimento reutilizáveis e com reconhecimento de permissão para agentes no portal do Microsoft Foundry.

Importante

Recursos, funcionalidades ou propriedades marcados como (versão prévia) não são cobertos por um contrato de nível de serviço (SLA), não são recomendados para cargas de trabalho de produção e podem mudar ou ser restringidos antes da disponibilidade geral. Os termos de visualização do Pesquisa de IA do Azure  se aplicam a toda funcionalidade em visualização, seja autônoma ou parte de um recurso de disponibilidade geral.

Se o código de recuperação agêntica usa uma versão anterior da API, este artigo explica quando e como migrar para uma versão mais recente. Ele também descreve alterações significativas e não significativas para todas as versões da API que suportam recuperação por meio de agentes.

As instruções de migração destinam-se a ajudá-lo a executar uma solução existente em uma versão mais recente da API. As instruções neste artigo ajudam você a lidar com alterações interruptivas no nível da API para que seu aplicativo seja executado como antes. Para obter ajuda com a adição de novas funcionalidades, comece com O que há de novo no Pesquisa de IA do Azure .

Dica

Usando um SDK do Azure em vez de REST? Antes de atualizar o pacote e aplicar as alterações de migração relevantes, verifique o registro de alterações da linguagem do seu SDK para confirmar o suporte à versão da API de destino.

Quando migrar

A maioria das versões que dão suporte à recuperação agente introduziu alterações significativas. Você pode continuar executando o código mais antigo inalterado mantendo o valor da versão da API, mas para se beneficiar de correções de bug, melhorias e funcionalidades mais recentes, você deve atualizar seu código.

Se o seu código tem como alvo uma versão prévia, recomendamos migrar para a versão estável mais recente somente se o seu caso de uso tiver suporte completo de 2026-04-01. Se você depende de síntese de respostas, esforço de raciocínio não mínimo ou mensagens de múltiplas interações, revise as alterações significativas e não significativas antes de decidir migrar. Esses recursos permanecem em versão prévia.

Antes de migrar

  • Para entender o escopo das alterações, examine as alterações interruptivas e não interruptivas para cada versão.

  • O caminho de migração com suporte é incremental. Se o seu código tiver como destino 2025-05-01-preview, primeiro migre para 2025-08-01-preview e, em seguida, prossiga por cada versão subsequente até chegar à sua versão de destino.

  • Para uma migração lado a lado, crie objetos nomeados exclusivamente que implementem os comportamentos da versão anterior. Essa abordagem preserva objetos existentes enquanto você desenvolve e testa substituições. Se um objeto oferecer suporte à atualização no local, as etapas específicas da versão indicarão essa opção.

  • Para cada objeto que você migrar, comece obtendo a definição atual do serviço de pesquisa para que você possa examinar as propriedades existentes antes de especificar a nova.

  • Exclua versões mais antigas somente depois que sua migração for totalmente testada e implantada.

Como migrar

Esta seção aborda as etapas de migração para as seguintes versões de API:

2026-08-01-preview

Se você estiver migrando de 2026-05-01-preview, poderá migrar diretamente para 2026-08-01-preview. Essa migração requer atualizações nas fontes de conhecimento do Work IQ, na paginação de listas, no processamento de respostas, nas ferramentas do servidor MCP e nas chamadas afetadas do cliente gerado.

  1. Migrar fontes de conhecimento do Work IQ
  2. Atualizar paginação de lista
  3. Processamento da resposta de recuperação da atualização
  4. Atualizar código e clientes

Migrar fontes de conhecimento do Work IQ

Para migrar uma fonte de conhecimento do Work IQ para a nova configuração de autenticação:

  1. Exporte sua definição atual.

  2. Atualize a fonte de conhecimento existente usando Knowledge Sources - Create Or Update ou crie uma substituição com um nome exclusivo para uma migração lado a lado.

  3. Use a versão da 2026-08-01-preview API e configure workIQParameters.entraAppAuthentication. As propriedades applicationId e federatedCredentialId são necessárias. A propriedade tenantId é opcional e usa como padrão o locatário do serviço de pesquisa.

  4. Se você criou uma substituição, atualize cada base de dados de conhecimento que referencie a fonte de conhecimento anterior para usar o nome de substituição.

  5. Atualize as requisições de recuperação para enviar a asserção do usuário no cabeçalho x-ms-query-work-iq-source-authorization.

Para obter configuração e exemplos, consulte Criar uma fonte de conhecimento do Work IQ (versão prévia).

Atualizar paginação de lista

Para substituir a paginação baseada em deslocamento pela paginação baseada em cursor:

  1. Remova $top, $skipe $count das solicitações da lista de fontes de conhecimento. Defina pageSize de 1 a 3.000 para controlar o tamanho da página. Se você omitir, o serviço escolherá o tamanho da página.

  2. Para filtrar por nome, definir search e searchType. O único valor com suporte para searchType é prefix, que também é o padrão. A solicitação a seguir retorna até 100 fontes de conhecimento cujos nomes começam com contoso.

    GET {{search-endpoint}}/knowledgesources?api-version=2026-08-01-preview&pageSize=100&search=contoso&searchType=prefix
Authorization: Bearer {{search-access-token}}

    Reference:Knowledge Sources – List

  3. Se a resposta contiver @odata.nextLink, envie essa URL exatamente como foi retornada. Não analise nem modifique seu estado de continuação.

Processamento da resposta de recuperação da atualização

Para processar a nova referência do Work IQ e os tipos de atividade baseados em modelo:

  1. Remover dependências em attributions, WorkIQAttributione seeMoreWebUrl. Leia metadados de rótulo de confidencialidade de searchSensitivityLabelInfo na referência do Work IQ.

  2. Em registros de atividade de planejamento de consultas, síntese de respostas e sumarização da Web, leia modelName e deploymentId do objeto aninhado model. O objeto aninhado e ambas as propriedades são opcionais.

Os fragmentos a seguir mostram as alterações de forma de resposta.

{
  "references": [
    {
      "type": "workIQ",
      "id": "<reference-id>",
      "activitySource": 1,
      "sourceData": {},
      "attributions": [
        {
          "seeMoreWebUrl": "<attribution-url>"
        }
      ]
    }
  ],
  "activity": [
    {
      "type": "modelAnswerSynthesis",
      "id": 2,
      "modelName": "<model-name>"
    }
  ]
}

Em 2026-08-01-preview, os mesmos fragmentos usam a seguinte forma:

{
  "references": [
    {
      "type": "workIQ",
      "id": "<reference-id>",
      "activitySource": 1,
      "sourceData": {},
      "searchSensitivityLabelInfo": {
        "displayName": "<label-name>",
        "sensitivityLabelId": "<label-id>"
      }
    }
  ],
  "activity": [
    {
      "type": "modelAnswerSynthesis",
      "id": 2,
      "model": {
        "modelName": "<model-name>",
        "deploymentId": "<deployment-id>"
      }
    }
  ]
}

Atualizar código e clientes para 2026-08-01-preview

Para concluir sua migração:

  1. Em cada item do servidor tools MCP, substitua inclusionMode por resultsProcessing. Mapear reranked para rerank e always para none. O valor rerank é o padrão. O valor none ignora a reclassificação e preserva a ordem original dos resultados da ferramenta. Para configurar, consulte Configurar ferramentas para uma fonte de conhecimento do servidor MCP.

  2. Se você usar um SDK do Azure, instale um pacote compatível com 2026-08-01-preview e revise chamadas de lista posicionais para verificar alterações na ordem dos parâmetros. Os chamadores REST não são afetados porque os parâmetros HTTP são chaveados pelo nome. Em C#, prefira argumentos nomeados, como GetKnowledgeSourcesAsync(search: ..., pageSize: ...). Em Python, passe as opções de lista como argumentos de palavra-chave.

  3. Teste a autenticação e as referências do Work IQ, a paginação por cursor, a desserialização de registros de atividade, a ordenação dos resultados do servidor MCP e as chamadas de clientes gerados antes de atualizar o ambiente de produção.

  4. Se você criou fontes de conhecimento substitutas do Work IQ, exclua as fontes anteriores somente depois que a migração passar em todos os testes, seu aplicativo atualizado tiver sido implantado e nenhuma base de conhecimento fizer referência aos nomes anteriores.

Prévia de 2026-05-01-

Se você estiver migrando de 2026-04-01 ou 2025-11-01-preview, poderá mover-se diretamente para 2026-05-01-preview. Solicitações, respostas e objetos persistentes dessas versões permanecem compatíveis. As diferenças são recursos aditivos e renomeações de SDK de idioma.

  1. Atualize a versão da API para 2026-05-01-preview nas solicitações REST. Os clientes do SDK usam a versão padrão da API do pacote, portanto, você não precisa passar um argumento explícito serviceVersion . Em vez disso, atualize para o pacote do 2026-05-01-preview SDK.

  2. Se você usar o Python ou o SDK do JavaScript, atualize o cliente de recuperação para KnowledgeBaseRetrievalClient e chame retrieve(...) em vez do retrieveKnowledge(...) herdado. Para obter o mapeamento completo de formas do SDK, consulte Atualizar código e clientes para 2026-05-01-preview.

  3. (Opcional) Adote os recursos 2026-05-01-preview novos, como recuperação sensível à atualização, limites de documentos por fonte e para o resultado final, configurações padrão persistidas para recuperação, CORS da base de conhecimento e metadados de rótulos de confidencialidade do Purview nas respostas da recuperação. Nenhum desses recursos é necessário para manter uma solução existente funcionando.

Atualizar código e clientes para 2026-05-01-preview

Os 2026-05-01-preview SDKs introduzem alterações de forma de código nos idiomas com suporte:

Linguagem Atualizações de migração
Python Crie o cliente de recuperação como KnowledgeBaseRetrievalClient(endpoint=..., credential=..., knowledge_base_name=...). Construa instâncias de esforço de raciocínio, como KnowledgeRetrievalLowReasoningEffort(), e passe a cadeia output_mode="answerSynthesis" de caracteres na base de dados de conhecimento ou recupere a solicitação. Passe AzureOpenAIVectorizerParameters(resource_url=...) (renomeado de resource_uri), usando o ponto de extremidade raiz do recurso em vez de um ponto de extremidade /openai/v1.
.NET Crie o cliente de recuperação como new KnowledgeBaseRetrievalClient(endpoint, knowledgeBaseName, credential) e passe uma credencial AzureKeyCredential ou de token. Para anexar um modelo openAI Azure baseado em chave a uma base de dados de conhecimento, defina a chave de API do modelo em AzureOpenAIVectorizerParameters.ApiKey.
Java Use KnowledgeBaseRetrievalClientBuilder para criar o cliente de recuperação e ler os resultados como KnowledgeBaseRetrievalResult. KnowledgeBaseRetrievalOptions agora expõe setMessages(...) junto com setIntents(...), além de setRetrievalReasoningEffort, setOutputMode, setMaxOutputSize e setMaxOutputDocuments, de modo que a recuperação baseada em mensagens e a síntese de respostas funcionem sem um contorno de intenção semântica. KnowledgeBase adiciona setOutputMode, setRetrievalReasoningEffort, setRetrievalInstructions, setAnswerInstructionse setCorsOptions. SearchIndexKnowledgeSourceParamsadiciona setAlwaysQuerySource, setFailOnErrore setMaxOutputDocumentssetEnableImageServing.
JavaScript e TypeScript Use KnowledgeRetrievalClient.retrieve({ intents: [{ type: "semantic", search: query }] }). O método anterior retrieveKnowledge(...) é removido em favor de retrieve(...).

Depois de atualizar as estruturas do cliente, execute o fluxo completo que cria o índice, carrega documentos, cria uma fonte de conhecimento, cria uma base de conhecimento, envia uma solicitação de recuperação e limpa os recursos para confirmar a migração de ponta a ponta.

01/04/2026

Se você estiver migrando de 2025-11-01-preview, poderá migrar diretamente para 2026-04-01. Seu índice e conteúdo permanecem inalterados. Você só precisa atualizar o esquema da base de dados de conhecimento e a forma de solicitação de recuperação.

  1. Migrar fontes de conhecimento
  2. Migrar a base de dados de conhecimento
  3. Atualizar a solicitação de recuperação
  4. Atualizar o consentimento de cobrança
  5. Atualizar código e clientes

Migrar fontes de conhecimento

Em 2026-04-01, os tipos de fonte de conhecimento searchIndex, azureBlob, indexedOneLake e web estão geralmente disponíveis. Outros tipos de fonte de dados de conhecimento permanecem em versão prévia.

  1. Use fontes de conhecimento – Obter (API REST) para obter a definição atual.

    GET {{search-endpoint}}/knowledge-sources/{{knowledge-source-name}}?api-version=2025-11-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

  2. Na resposta, identifique o que levar adiante e o que remover:

    • Para searchIndex e web, mantenha todos os valores de propriedade.

    • Para azureBlob e indexedOneLake, transfira todos os valores de propriedade, mas omita o ingestionPermissionOptions de ingestionParameters. Essa propriedade não tem suporte em 2026-04-01.

  3. Use fontes de conhecimento – Criar ou atualizar (API REST) para criar uma nova fonte de conhecimento com um nome exclusivo, a versão da 2026-04-01 API e os valores da propriedade da etapa anterior.

    O exemplo a seguir mostra uma searchIndex fonte de conhecimento. Use um padrão semelhante para azureBlob, indexedOneLakee web fontes de conhecimento.

    PUT {{search-endpoint}}/knowledge-sources/{{new-knowledge-source-name}}?api-version=2026-04-01
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

{
  "name": "{{new-knowledge-source-name}}",
  "description": "Knowledge source backed by a search index.",
  "kind": "searchIndex",
  "searchIndexParameters": {
    "searchIndexName": "{{index-name}}",
    "sourceDataFields": [
      { "name": "id" },
      { "name": "page_chunk" },
      { "name": "page_number" }
    ]
  }
}

Migrar a base de dados de conhecimento

A 2026-04-01 base de dados de conhecimento tem um esquema mais simples do que a 2025-11-01-preview versão: ela mantém knowledgeSources e descarta as configurações de geração de resposta. Examine a definição atual antes de criar um novo objeto.

  1. Use Bases de Conhecimento — Obter (API REST) para obter a definição atual.

    GET {{search-endpoint}}/knowledgebases/{{knowledge-base-name}}?api-version=2025-11-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

  2. Na resposta, identifique o que levar adiante e o que remover:

    • Observe as referências knowledgeSources. Transfira-as para a nova base de conhecimento.

    • Se estiver presente, remova outputMode, answerInstructionse retrievalInstructions. Essas propriedades não têm suporte em 2026-04-01.

    • Se sua base de dados de conhecimento usar uma web fonte de conhecimento, mantenha models. A recuperação de dados da Web requer um resumo apoiado por modelo. Para todos os outros tipos de fonte de conhecimento, remova models.

  3. Use bases de dados de conhecimento – Criar ou atualizar (API REST) para criar uma nova base de dados de conhecimento com um nome exclusivo, a versão da 2026-04-01 API e apenas as propriedades com suporte.

    PUT {{search-endpoint}}/knowledgebases/{{new-knowledge-base-name}}?api-version=2026-04-01
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

{
  "name": "{{new-knowledge-base-name}}",
  "description": "Minimal knowledge base for search index retrieval.",
  "knowledgeSources": [
    { "name": "{{new-knowledge-source-name}}" }
  ]
}

Atualizar a solicitação de recuperação

A 2026-04-01 solicitação de recuperação tem uma forma diferente da versão prévia:

  • Use intents em vez de messages.

  • Use maxOutputSizeInTokens em vez de maxOutputSize.

  • Se estiver presente, remova retrievalReasoningEffort e alwaysQuerySource. Não há suporte para esses parâmetros.2026-04-01

  • Para perguntas de acompanhamento, envie uma nova solicitação de consulta com uma nova intenção semântica. 2026-04-01 não mantém uma transcrição de mensagens em execução.

Para testar a saída da sua base de conhecimento com uma consulta, use a versão 2026-04-01 de Recuperação de Conhecimento - Recuperar (API REST).

POST {{search-endpoint}}/knowledgebases/{{new-knowledge-base-name}}/retrieve?api-version=2026-04-01
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

{
  "intents": [
    {
      "type": "semantic",
      "search": "{{query-text}}"
    }
  ],
  "knowledgeSourceParams": [
    {
      "knowledgeSourceName": "{{new-knowledge-source-name}}",
      "kind": "searchIndex",
      "includeReferences": true,
      "includeReferenceSourceData": true,
      "rerankerThreshold": 2.5
    }
  ],
  "maxRuntimeInSeconds": 30,
  "maxOutputSizeInTokens": 6000
}

Se a resposta tiver um 200 OK código HTTP, sua base de dados de conhecimento recuperou com êxito o conteúdo da fonte de conhecimento.

A partir da versão 2026-04-01 da API, o consentimento de cobrança da recuperação por meio de agentes é controlado por uma propriedade dedicada knowledgeRetrieval, separada de semanticSearch, que agora se aplica apenas à cobrança do classificador semântico. knowledgeRetrieval é uma propriedade do plano de gerenciamento, portanto, você a define por meio da API REST do Gerenciamento de Pesquisa, não da API REST do Serviço de Pesquisa.

Use a versão prévia mais recente dos Serviços – Criar ou Atualizar (API REST) para definir knowledgeRetrieval em seu serviço de pesquisa.

PATCH https://management.azure.com/subscriptions/{{subscription-id}}/resourcegroups/{{resource-group}}/providers/Microsoft.Search/searchServices/{{search-service-name}}?api-version=2026-03-01-preview
Content-Type: application/json
Authorization: Bearer {{management-access-token}}

{
  "properties": {
    "knowledgeRetrieval": "standard"
  }
}

Para valores válidos e detalhes de cobrança, consulte Habilitar ou desabilitar a cobrança por recuperação por meio de agentes.

Atualize o código e os clientes para a versão 01/04/2026

Para concluir sua migração:

  1. Atualize as chamadas do cliente para usar a versão da 2026-04-01 API.

  2. Atualize qualquer base de dados de conhecimento codificada ou nomes de fonte de dados de conhecimento em seu código para fazer referência aos novos objetos criados durante a migração.

  3. Se você migrou azureBlob ou indexedOneLake fontes de conhecimento, atualize qualquer código ou script que faça referência ao índice associado, indexador, fonte de dados ou conjunto de habilidades por nome para apontar para os novos objetos.

  4. Atualize o código que processa respostas recuperadas. As respostas retornam conteúdo de base extrativo com activity e references, não respostas sintetizadas.

  5. Exclua objetos de visualização somente depois que os novos objetos forem totalmente validados e implantados.

2025-11-01-preview

Se você estiver migrando de 2025-08-01-preview, "agente de conhecimento" será renomeado para "base de dados de conhecimento" e várias propriedades serão realocadas para diferentes objetos e níveis dentro de uma definição de objeto.

  1. Atualizar as fontes de conhecimento do searchIndex
  2. Atualizar fontes de conhecimento do azureBlob
  3. Substituir o agente de conhecimento pela base de dados de conhecimento
  4. Atualizar a solicitação de recuperação e enviar uma consulta para testar suas atualizações
  5. Atualizar código do cliente

Atualizar uma fonte de conhecimento de índice de pesquisa

Este procedimento cria uma nova 2025-11-01-previewsearchIndex fonte de conhecimento no mesmo nível funcional da versão anterior 2025-08-01 . O próprio índice subjacente não requer atualizações.

  1. Liste todas as fontes de conhecimento pelo nome para encontrar sua fonte de conhecimento.

    ### List all knowledge sources by name
GET {{search-endpoint}}/knowledge-sources?api-version=2025-08-01-preview&$select=name
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

  2. Obtenha a definição atual para examinar as propriedades existentes.

    ### Get a specific knowledge source
GET {{search-endpoint}}/knowledge-sources/search-index-ks?api-version=2025-08-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

    A resposta deve ser semelhante ao exemplo a seguir.

    {
     "name": "search-index-ks",
     "kind": "searchIndex",
     "description": "This knowledge source pulls from a search index created using the 2025-08-01-preview.",
     "encryptionKey": null,
     "searchIndexParameters": {
     "searchIndexName": "earth-at-night-idx",
     "sourceDataSelect": "id, page_chunk, page_number"
     },
     "azureBlobParameters": null
}

  3. Formular uma solicitação Criar Fonte de Conhecimento como base para sua migração.

    Comece com o JSON 08-01-preview.

    POST {{search-endpoint}}/knowledge-sources/search-index-ks?api-version=2025-08-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

{
    "name": "search-index-ks",
    "kind": "searchIndex",
    "description": "A sample search index knowledge source",
    "encryptionKey": null,
    "searchIndexParameters": {
        "searchIndexName": "my-search-index",
        "sourceDataSelect": "id, page_chunk, page_number"
  }
}

    Faça as seguintes atualizações para uma 2025-11-01-preview migração:

    • Dê um novo nome à fonte de dados de conhecimento.

    • Altere a versão da API para 2025-11-01-preview.

    • Renomeie sourceDataSelect para sourceDataFields e altere a cadeia de caracteres para uma matriz contendo pares nome-valor, para cada campo recuperável que você deseja consultar. Esses são os campos a serem retornados nos resultados da pesquisa, semelhantes a uma select cláusula em uma consulta clássica.

  4. Examine suas atualizações e, em seguida, envie a solicitação para criar o objeto.

    PUT {{search-endpoint}}/knowledge-sources/search-index-ks-11-01?api-version=2025-11-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

{
    "name": "search-index-ks-11-01",
    "kind": "searchIndex",
    "description": "knowledge source migrated to 2025-11-01-preview",
    "encryptionKey": null,
    "searchIndexParameters": {
        "searchIndexName": "my-search-index",
        "sourceDataFields": [
            { "name": "id" }, { "name": "page_chunk" }, { "name": "page_number" }
        ]
    }
}

Agora você tem uma fonte de conhecimento migrada searchIndex, retrocompatível com a versão anterior, usando as especificações de propriedade corretas para o 2025-11-01-preview.

A resposta inclui a definição completa do novo objeto. Para obter mais informações sobre novas propriedades disponíveis para esse tipo de fonte de conhecimento, que agora você pode fazer por meio de atualizações, consulte Como criar uma fonte de conhecimento do índice de pesquisa.

Atualizar uma fonte de conhecimento do azureBlob

Este procedimento cria uma nova 2025-11-01-previewazureBlob fonte de conhecimento no mesmo nível funcional da versão anterior 2025-08-01 . Ele cria um novo conjunto de objetos gerados: fonte de dados, conjunto de habilidades, indexador, índice.

  1. Liste todas as fontes de conhecimento pelo nome para encontrar sua fonte de conhecimento.

    ### List all knowledge sources by name
GET {{search-endpoint}}/knowledge-sources?api-version=2025-08-01-preview&$select=name
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

  2. Obtenha a definição atual para examinar as propriedades existentes.

    ### Get a specific knowledge source
GET {{search-endpoint}}/knowledge-sources/azure-blob-ks?api-version=2025-08-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

    Se o fluxo de trabalho incluir um modelo, a resposta deverá ser semelhante ao exemplo a seguir. Observe que uma resposta inclui os nomes dos objetos gerados. Esses objetos são totalmente independentes da fonte de conhecimento e permanecem operacionais mesmo se você atualizar ou excluir sua fonte de conhecimento.

     {
   "name": "azure-blob-ks",
   "kind": "azureBlob",
   "description": "A sample azure blob knowledge source.",
   "encryptionKey": null,
   "searchIndexParameters": null,
   "azureBlobParameters": {
     "connectionString": "<redacted>",
     "containerName": "blobcontainer",
     "folderPath": null,
     "disableImageVerbalization": false,
     "identity": null,
     "embeddingModel": {
       "name": "embedding-model",
       "kind": "azureOpenAI",
       "azureOpenAIParameters": {
         "resourceUri": "<redacted>",
         "deploymentId": "text-embedding-3-large",
         "apiKey": "<redacted>",
         "modelName": "text-embedding-3-large",
         "authIdentity": null
       },
       "customWebApiParameters": null,
       "aiServicesVisionParameters": null,
       "amlParameters": null
     },
     "chatCompletionModel": {
       "kind": "azureOpenAI",
       "azureOpenAIParameters": {
         "resourceUri": "<redacted>",
         "deploymentId": "gpt-4o-mini",
         "apiKey": "<redacted>",
         "modelName": "gpt-4o-mini",
         "authIdentity": null
       }
 },
     "ingestionSchedule": null,
     "createdResources": {
       "datasource": "azure-blob-ks-datasource",
       "indexer": "azure-blob-ks-indexer",
       "skillset": "azure-blob-ks-skillset",
       "index": "azure-blob-ks-index"
     }
   }
 }

  3. Formular uma solicitação Criar Fonte de Conhecimento como base para sua migração.

    Comece com o JSON 08-01-preview.

    POST {{search-endpoint}}/knowledge-sources/azure-blob-ks?api-version=2025-08-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

{
    "name": "azure-blob-ks",
    "kind": "azureBlob",
    "description": "A sample azure blob knowledge source.",
    "encryptionKey": null,
    "azureBlobParameters": {
        "connectionString": "<redacted>",
        "containerName": "blobcontainer",
        "folderPath": null,
        "disableImageVerbalization": false,
        "identity": null,
        "embeddingModel": {
            "name": "embedding-model",
            "kind": "azureOpenAI",
            "azureOpenAIParameters": {
            "resourceUri": "<redacted>",
            "deploymentId": "text-embedding-3-large",
            "apiKey": "<redacted>",
            "modelName": "text-embedding-3-large",
            "authIdentity": null
            },
            "customWebApiParameters": null,
            "aiServicesVisionParameters": null,
            "amlParameters": null
        },
        "chatCompletionModel": null,
        "ingestionSchedule": null
  }
}

    Faça as seguintes atualizações para uma 2025-11-01-preview migração:

    • Dê um novo nome à fonte de dados de conhecimento.

    • Altere a versão da API para 2025-11-01-preview.

    • Adicione ingestionParameters como um contêiner para as seguintes propriedades filho: "embeddingModel", "chatCompletionModel", "ingestionSchedule", "contentExtractionMode".

  4. Examine suas atualizações e, em seguida, envie a solicitação para criar o objeto. Novos objetos gerados são criados para o pipeline do indexador.

    PUT {{search-endpoint}}/knowledge-sources/azure-blob-ks-11-01?api-version=2025-11-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

{
    "name": "azure-blob-ks",
    "kind": "azureBlob",
    "description": "A sample azure blob knowledge source",
    "encryptionKey": null,
    "azureBlobParameters": {
        "connectionString": "{{blob-connection-string}}",
        "containerName": "blobcontainer",
        "folderPath": null,
        "ingestionParameters": {
            "embeddingModel": {
                "kind": "azureOpenAI",
                "azureOpenAIParameters": {
                    "deploymentId": "text-embedding-3-large",
                    "modelName": "text-embedding-3-large",
                    "resourceUri": "{{aoai-endpoint}}",
                    "apiKey": "{{aoai-key}}"
                }
            },
            "chatCompletionModel": null,
            "disableImageVerbalization": false,
            "ingestionSchedule": null,
            "contentExtractionMode": "minimal"
        }
    }
}

Agora você tem uma fonte de conhecimento migrada azureBlob, retrocompatível com a versão anterior, usando as especificações de propriedade corretas para o 2025-11-01-preview.

A resposta inclui a definição completa do novo objeto. Para obter mais informações sobre novas propriedades disponíveis para esse tipo de fonte de conhecimento, que agora você pode fazer por meio de atualizações, consulte Criar uma fonte de conhecimento de blob.

Substituir o agente de conhecimento pela base de conhecimento

  1. As bases de dados de conhecimento exigem uma fonte de conhecimento. Verifique se você tem uma fonte de conhecimento direcionada a 2025-11-01-preview antes de começar.

  2. Obtenha a definição atual para examinar as propriedades existentes.

    ### Get a knowledge agent by name
GET {{search-endpoint}}/agents/earth-at-night?api-version=2025-08-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

    A resposta deve ser semelhante ao exemplo a seguir.

    {
  "name": "earth-at-night",
  "description": "A sample knowledge agent that retrieves from the earth-at-night knowledge source.",
  "retrievalInstructions": null,
  "requestLimits": null,
  "encryptionKey": null,
  "knowledgeSources": [
    {
      "name": "earth-at-night",
      "alwaysQuerySource": null,
      "includeReferences": null,
      "includeReferenceSourceData": null,
      "maxSubQueries": null,
      "rerankerThreshold": 2.5
    }
  ],
  "models": [
    {
      "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "<redacted>",
        "deploymentId": "gpt-5-mini",
        "apiKey": "<redacted>",
        "modelName": "gpt-5-mini",
        "authIdentity": null
      }
    }
  ],
  "outputConfiguration": {
    "modality": "answerSynthesis",
    "answerInstructions": null,
    "attemptFastPath": false,
    "includeActivity": null
  }
}

  3. Formular uma solicitação Criar Base de Dados de Conhecimento como base para sua migração.

    Comece com o JSON 08-01-preview.

    PUT {{search-endpoint}}/knowledgebases/earth-at-night?api-version=2025-08-01-preview  HTTP/1.1
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

{
    "name": "earth-at-night",
    "description": "A sample knowledge agent that retrieves from the earth-at-night knowledge source.",
    "retrievalInstructions": null,
    "encryptionKey": null,
    "knowledgeSources": [
        {
          "name": "earth-at-night",
          "alwaysQuerySource": null,
          "includeReferences": null,
          "includeReferenceSourceData": null,
          "maxSubQueries": null,
          "rerankerThreshold": 2.5
        }
    ],
    "models": [
        {
            "kind": "azureOpenAI",
            "azureOpenAIParameters": {
                "resourceUri": "<redacted>",
                "apiKey": "<redacted>",
                "deploymentId": "gpt-5-mini",
                "modelName": "gpt-5-mini"
            }
        }
    ],
    "outputConfiguration": {
        "modality": "answerSynthesis"
    }
}

    Faça as seguintes atualizações para uma 2025-11-01-preview migração:

    • Substitua o ponto de extremidade: /knowledgebases/{{knowledge-base-name}}. Dê à base de dados de conhecimento um nome exclusivo.

    • Altere a versão da API para 2025-11-01-preview.

    • Excluir requestLimits. As propriedades maxOutputSize e maxRuntimeInSeconds agora são especificadas diretamente na solicitação de recuperação.

    • Atualização knowledgeSources:

    • Mover alwaysQuerySource, includeReferenceSourceData, includeReferences e rerankerThreshold para a seção knowledgeSourceParams de uma ação de recuperação.

    • Nenhuma alteração para models.

    • Atualização outputConfiguration:

      • Substitua outputConfiguration por outputMode.

      • Excluir attemptFastPath. Ele não existe mais. O comportamento equivalente é implementado com retrievalReasoningEffort definido como mínimo (consulte Definir o esforço de raciocínio para recuperação (versão prévia)).

      • Se a modalidade estiver definida como answerSynthesis, defina o esforço de raciocínio de recuperação como baixo (padrão) ou médio.

    • Adicione ingestionParameters como um requisito para criar uma 2025-11-01-preview fonte de conhecimento do azureBlob.

  4. Examine suas atualizações e, em seguida, envie a solicitação para criar o objeto. Novos objetos gerados são criados para o pipeline do indexador.

     PUT {{search-endpoint}}/knowledgebases/earth-at-night-11-01?api-version={{api-version}}
 Authorization: Bearer {{search-access-token}}
 Content-Type: application/json

 {
   "name": "earth-at-night-11-01",
   "description": "A sample knowledge base at the same functional level as the previous knowledge agent.",
   "retrievalInstructions": null,
   "encryptionKey": null,
   "knowledgeSources": [
     {
         "name": "earth-at-night-ks"
     }
   ],
   "models": [
     {
       "kind": "azureOpenAI",
       "azureOpenAIParameters": {
           "resourceUri": "<redacted>",
           "apiKey": "<redacted>",
           "deploymentId": "gpt-5-mini",
           "modelName": "gpt-5-mini"
         }
     }
   ],
   "retrievalReasoningEffort": null,
   "outputMode": "answerSynthesis",
   "answerInstructions": "Provide a concise and accurate answer based on the retrieved information."
 }

Agora você tem uma base de dados de conhecimento em vez de um agente de conhecimento e o objeto é compatível com versões anteriores.

A resposta inclui a definição completa do novo objeto. Para obter mais informações sobre novas propriedades disponíveis para uma base de dados de conhecimento, que agora você pode fazer por meio de atualizações, consulte Como criar uma base de dados de conhecimento.

Atualizar e testar a recuperação para atualizações de 2025-11-01-preview

A solicitação de recuperação foi modificada para que o 2025-11-01-preview ofereça suporte a mais formatos, incluindo uma solicitação mais simples que minimiza o processamento do LLM. Para obter mais informações sobre recuperação nesta versão prévia, consulte Recuperar dados usando uma base de dados de conhecimento. Esta seção explica como atualizar seu código.

  1. Altere o /agents/retrieve ponto de extremidade para /knowledgebases/retrieve.

  2. Altere a versão da API para 2025-11-01-preview.

  3. Nenhuma alteração em messages será necessária se você estiver usando o esforço de raciocínio de recuperação low ou medium. Substitua messages por minimal se você usar o raciocínio (consulte intents).

  4. Modifique knowledgeSourceParams para incluir as propriedades que foram removidas do agente: rerankerThreshold, , alwaysQuerySource, includeReferenceSourceData, . includeReferences

  5. Adicione retrievalReasoningEffort definido para minimum se você estiver usando attemptFastPath. Se você estava usando maxSubQueries, ele não existe mais. Use a retrievalReasoningEffort configuração para especificar o processamento de subconsultas (consulte Definir o esforço de raciocínio de recuperação (versão prévia)).

Para testar o resultado da sua base de conhecimento usando uma consulta, use a operação 2025-11-01-preview de Knowledge Retrieval - Retrieve (REST API).

### Send a query to the knowledge base
POST {{search-endpoint}}/knowledgebases/earth-at-night-11-01/retrieve?api-version=2025-11-01-preview
Authorization: Bearer {{search-access-token}}
Content-Type: application/json

{
    "messages": [
        {
            "role": "user",
            "content": [
                { "type": "text", "text": "What are some light sources on the ocean at night" }
            ]
        }
    ],
    "includeActivity": true,
    "retrievalReasoningEffort": { "kind": "medium" },
    "outputMode": "answerSynthesis",
    "maxRuntimeInSeconds": 30,
    "maxOutputSize": 6000
}

Se a resposta tiver um 200 OK código HTTP, sua base de dados de conhecimento recuperou com êxito o conteúdo da fonte de conhecimento.

Atualizar código e clientes para 2025-11-01-preview

Para concluir a migração, siga estas etapas de limpeza:

  1. Somente para fontes de conhecimento do tipo blob, atualize os clientes para usar o novo índice. Se você tiver código ou script que execute um indexador ou faça referência a uma fonte de dados, índice ou conjunto de habilidades, atualize as referências para os novos objetos.

  2. Substitua todas as referências de agente por knowledgeBases arquivos de configuração, código, scripts e testes.

  3. Atualizar chamadas de cliente para usar o 2025-11-01-preview.

  4. Limpar ou regenerar definições armazenadas em cache que foram criadas usando as formas antigas.

2025-08-01-preview

Se você criou um agente de conhecimento usando a versão prévia 2025-05-01, a definição do agente inclui uma matriz embutida targetIndexes e uma propriedade opcional defaultMaxDocsForReranker .

A partir da versão da API 2025-08-01-preview , as fontes de conhecimento reutilizáveis substituem targetIndexese defaultMaxDocsForReranker não têm mais suporte. Essas alterações interruptivas exigem que você:

  1. Obter a configuração atual targetIndexes
  2. Criar uma fonte de conhecimento equivalente
  3. Atualizar o agente para usar knowledgeSources em vez de targetIndexes
  4. Enviar uma consulta para testar a recuperação
  5. Remover código que usa targetIndexes e atualizar clientes

Obter a configuração atual

Para obter a definição do seu agente, use o 2025-05-01-preview de Agentes de Conhecimento - Obter (API REST).

@search-endpoint = <search-endpoint>
@agent-name = <agent-name>
@search-access-token = <search-access-token>

### Get agent definition
GET {{search-endpoint}}/agents/{{agent-name}}?api-version=2025-05-01-preview  HTTP/1.1
    Authorization: Bearer {{search-access-token}}

A resposta deve ser semelhante ao exemplo a seguir. Copie os valores indexName, defaultRerankerThreshold e defaultIncludeReferenceSourceData para uso nas próximas etapas. defaultMaxDocsForReranker é obsoleto, você pode ignorar seu valor.

{
  "@odata.etag": "0x1234568AE7E58A1",
  "name": "my-knowledge-agent",
  "description": "My description of the agent",
  "targetIndexes": [
    {
      "indexName": "my-index",
      "defaultRerankerThreshold": 2.5,
      "defaultIncludeReferenceSourceData": true,
      "defaultMaxDocsForReranker": 100
    }
  ]
}

Criar uma fonte de conhecimento

Para criar uma searchIndex fonte de conhecimento, use o 2025-08-01-preview de Fontes de conhecimento - Criar (API REST). Defina searchIndexName para o valor copiado anteriormente.

@source-name = <source-name>

### Create a knowledge source
PUT {{search-endpoint}}/knowledgeSources/{{source-name}}?api-version=2025-08-01-preview  HTTP/1.1
    Content-Type: application/json
    Authorization: Bearer {{search-access-token}}

    {
        "name": "{{source-name}}",
        "description": "My description of the knowledge source",
        "kind": "searchIndex",
        "searchIndexParameters": {
            "searchIndexName": "my-index"
        }
    }

O exemplo anterior cria uma fonte de conhecimento que representa um índice, mas você pode direcionar vários índices ou um blob Azure. Para obter mais informações, consulte Criar uma fonte de conhecimento.

Atualizar o agente

Para substituir targetIndexesknowledgeSources na definição do agente, use os 2025-08-01-previewAgentes de Conhecimento – Criar ou Atualizar (API REST). Defina rerankerThreshold e includeReferenceSourceData para os valores copiados anteriormente.

### Replace targetIndexes with knowledgeSources
POST {{search-endpoint}}/agents/{{agent-name}}?api-version=2025-08-01-preview  HTTP/1.1
    Content-Type: application/json
    Authorization: Bearer {{search-access-token}}

    {
        "name": "{{agent-name}}",
        "knowledgeSources": [
            {
                "name": "{{source-name}}",
                "rerankerThreshold": 2.5,
                "includeReferenceSourceData": true
            }
        ]
    }

O exemplo anterior atualiza a definição para fazer referência a uma fonte de conhecimento, mas você pode direcionar várias fontes de conhecimento. Você também pode usar outras propriedades para controlar o comportamento de recuperação, como alwaysQuerySource. Para obter mais informações, consulte Criar um agente de conhecimento.

Testar a recuperação para atualizações de 2025-08-01-preview

Para testar a saída do agente com uma consulta, use o 2025-08-01-preview de Recuperação de conhecimento - Recuperar (API REST).

### Send a query to the agent
POST {{search-endpoint}}/agents/{{agent-name}}/retrieve?api-version=2025-08-01-preview  HTTP/1.1
    Content-Type: application/json
    Authorization: Bearer {{search-access-token}}

    {
      "messages": [
            {
                "role": "user",
                "content" : [
                    {
                        "text": "<query-text>",
                        "type": "text"
                    }
                ]
            }
        ]
    }

Se a resposta tiver um 200 OK código HTTP, o agente recuperará com êxito o conteúdo da fonte de conhecimento.

Atualizar código e clientes para 2025-08-01-preview

Para concluir a migração, siga estas etapas de limpeza:

  • Substitua todas as referências targetIndexes por knowledgeSources nos arquivos de configuração, códigos, scripts e testes.
  • Atualizar chamadas de cliente para usar o 2025-08-01-preview.
  • Limpar ou regenerar definições de agente em cache que foram criadas usando a forma antiga.

Alterações específicas à versão

Esta seção aborda alterações significativas e não significativas para as seguintes versões da API:

2026-08-01-preview

A 2026-08-01-preview versão baseia-se na versão prévia 2026-05-01 e inclui alterações significativas para aplicativos que usam fontes de conhecimento de Qi de Trabalho, paginação de lista baseada em deslocamento, registros de atividade com suporte de modelo, processamento de resultados do servidor MCP ou chamadas de cliente gerado posicional.

Para examinar a documentação de referência da API REST para esta versão, selecione o 2026-08-01-preview filtro de versão da API na parte superior da página.

  • workIQParameters é obrigatório em uma fonte de conhecimento do Work IQ e deve conter entraAppAuthentication. Atualize a fonte no local, ou crie um substituto para uma migração lado a lado. Passe a asserção do usuário no cabeçalho x-ms-query-work-iq-source-authorization em solicitações de recuperação.

  • As referências do Work IQ removem attributions, a forma WorkIQAttribution e seeMoreWebUrl. A referência reformulada expõe searchSensitivityLabelInfo. Remova as dependências dos campos excluídos e atualize o processamento das referências para a nova estrutura do rótulo de confidencialidade.

  • Os parâmetros $top, $skip e $count, exclusivos de visualização, foram removidos. As operações de lista de coleção usam search, pageSize e searchType. As respostas usam @odata.nextLink para paginação de continuação. Atualize as solicitações de listagem e siga cada item @odata.nextLink exatamente conforme retornado.

  • Os registros de atividade de planejamento de consultas, síntese de respostas e sumarização da Web removem o escalar modelName. O objeto de substituição model contém modelName e deploymentId. Desserialize o objeto aninhado model para registros de atividade baseados em modelo.

  • McpServerTool.inclusionMode é removido. Em cada item do servidor tools MCP, mapeie reranked para resultsProcessing: "rerank" e always para resultsProcessing: "none". Se for omitido, resultsProcessing assume o padrão rerank; none ignora a reclassificação e preserva a ordem subjacente dos resultados.

  • Os novos parâmetros de lista alteram a ordem de parâmetro do método gerado, mas não afetam a associação de parâmetro REST. Revise as chamadas posicionais após instalar um pacote do SDK compatível com 2026-08-01-preview. Prefira argumentos nomeados ou opções quando disponível.

Prévia de 2026-05-01-

2026-05-01-preview adiciona base de dados de conhecimento, fonte de conhecimento e recursos de recuperação em cima de 2025-11-01-preview sem remover propriedades persistidas anteriormente. As bases de dados de conhecimento existentes e as fontes de conhecimento que você criou em versões prévias anteriores continuam funcionando. Esta versão introduz principalmente novas funcionalidades e remove algumas limitações que existiam apenas na versão prévia.

Para examinar a documentação de referência da API REST para esta versão, selecione o 2026-05-01-preview filtro de versão da API na parte superior da página.

Não há alterações significativas entre 2025-11-01-preview e 2026-05-01-preview. As solicitações existentes direcionadas 2025-11-01-preview continuam funcionando quando você altera a versão da API para 2026-05-01-preview.

Os SDKs de linguagem que incluem o suporte a 2026-05-01-preview apresentam alterações na estrutura do código que causam quebra na camada do SDK. Consulte Atualizar o código e os clientes para 2026-05-01-preview para o mapeamento completo de formas do SDK.

01/04/2026

2026-04-01 é a primeira versão estável da API para recuperação agêntica. Ela estabelece um contrato de recuperação extrativa mínimo e remove os recursos de planejamento de consultas baseado em mensagens e síntese de respostas da era de pré-visualização.

Para examinar a documentação de referência da API REST para esta versão, selecione o 2026-04-01 filtro de versão da API na parte superior da página.

As alterações a seguir afetam o esquema da base de dados de conhecimento e a solicitação de recuperação:

  • retrievalReasoningEffort é removido. As bases de conhecimento configuradas anteriormente com esforço de raciocínio low ou medium não são compatíveis com 2026-04-01 e devem ser recriadas.

  • outputMode é removido. A recuperação retorna conteúdo extraído contextualizado por padrão. Não há suporte para síntese de resposta.

As seguintes alterações afetam somente a solicitação de recuperação:

  • intents substitui messages.

  • alwaysQuerySource é removido de knowledgeSourceParams.

  • maxOutputSize é renomeado para maxOutputSizeInTokens.

  • O estado de conversação não é mantido entre solicitações. O padrão de múltiplas etapas baseado em messagesnão é permitido.

A seguinte alteração afeta azureBlob e indexedOneLake fontes de conhecimento:

  • ingestionPermissionOptions é removido de ingestionParameters. Fontes de conhecimento azureBlob e indexedOneLake que incluem esta propriedade devem ser recriadas sem ela.

Nota

O envio de campos removidos retorna um 400 Bad Request código HTTP. A solicitação de recuperação não descarta nem tolera campos que não existem mais nesta versão.

2025-11-01-preview

Para examinar a documentação de referência da API REST para esta versão, selecione o 2025-11-01-preview filtro de versão da API na parte superior da página.

  • O agente de conhecimento é renomeado para base de dados de conhecimento.

    Rota anterior Nova rota
    /agents /knowledgebases
    /agents/agent-name /knowledgebases/knowledge-base-name
    /agents/agent-name/retrieve /knowledgebases/knowledge-base-name/retrieve

  • O agente de conhecimento (base) outputConfiguration é renomeado outputMode e alterado de um objeto para um enumerador de cadeia de caracteres. Várias propriedades são afetadas:

    • includeActivity é movido de outputConfiguration diretamente para a solicitação de recuperação.
    • attemptFastPath in outputConfiguration é totalmente removido. O novo esforço de raciocínio minimal é a substituição.

  • O agente de conhecimento (base) requestLimits é removido. Suas propriedades filhas de maxRuntimeInSeconds e maxOutputSize são movidas diretamente para a solicitação de recuperação.

  • Os parâmetros do agente de conhecimento (base) knowledgeSources agora listam apenas os nomes da fonte de conhecimento usada por uma base de dados de conhecimento. Outras propriedades filho que costumavam estar sob knowledgeSources são movidas para as propriedades knowledgeSourceParams da solicitação de recuperação:

    • rerankerThreshold
    • alwaysQuerySource
    • includeReferenceSourceData
    • includeReferences

    A propriedade maxSubQueries se foi. A sua substituição é a nova propriedade de esforço de raciocínio de recuperação.

  • Solicitação de recuperação do agente de conhecimento (base): o registro de atividade semanticReranker é substituído pelo tipo de registro de atividade agenticReasoning.

  • Fontes de conhecimento para tanto azureBlob quanto searchIndex: propriedades de nível superior para identity, embeddingModel, chatCompletionModel, disableImageVerbalization e ingestionSchedule agora fazem parte de um objeto ingestionParameters na fonte de conhecimento. Todas as fontes de conhecimento que extraem de um índice de pesquisa têm um ingestionParameters objeto.

  • Somente para as fontes de conhecimento searchIndex: sourceDataSelect é renomeado para sourceDataFields e é uma matriz que aceita fieldName e fieldToSearch.

2025-08-01-preview

Para examinar a documentação de referência da API REST para esta versão, selecione o 2025-08-01-preview filtro de versão da API na parte superior da página.

  • Apresenta as fontes de conhecimento como a nova maneira de definir fontes de dados, dando suporte às variantes searchIndex (um ou vários índices) e azureBlob. Para obter mais informações, veja Criar uma fonte de conhecimento de índice de pesquisa e Criar uma fonte de conhecimento de blob.

  • Requer knowledgeSources em vez de targetIndexes nas definições do agente. Para obter as etapas de migração, consulte Como migrar.

  • Remove o suporte de defaultMaxDocsForReranker. Essa propriedade existia anteriormente em targetIndexes, mas não há equivalente em knowledgeSources.

2025-05-01-preview

Esta versão da API introduz a recuperação agêntica e os agentes de conhecimento. Cada definição de agente requer uma targetIndexes matriz que especifica um único índice e propriedades opcionais, como defaultRerankerThreshold e defaultIncludeReferenceSourceData.

Para examinar a documentação de referência da API REST para esta versão, selecione o 2025-05-01-preview filtro de versão da API na parte superior da página.

Conteúdo relacionado

  • Last updated on