Migrar código de recuperação agêntica para a versão mais recente

Se o seu código de recuperação agente tem como alvo uma versão anterior da API, este artigo explica quando e como migrar para uma versão mais recente. Descreve também alterações de rutura e não disruptivas para todas as versões da API que suportam recuperação através de agente.

As instruções de migração destinam-se a ajudar a executar uma solução existente numa versão mais recente da API. As instruções deste artigo ajudam-no a abordar alterações urgentes ao nível da API para que a sua aplicação corra como antes. Para ajuda na adição de novas funcionalidades, comece por O que há de novo em Pesquisa de IA do Azure.

Quando migrar

A maioria das versões que suportam recuperação agentica introduziu alterações de quebra. Pode continuar a executar código mais antigo sem alterações, mantendo o valor da versão da API, mas para beneficiar de correções de bugs, melhorias e funcionalidades mais recentes, deve atualizar o seu código.

Se o seu código tem como objetivo uma versão de pré-visualização, recomendamos migrar para a versão estável mais recente apenas se o seu caso de uso for totalmente suportado por 2026-04-01. Se depender da síntese de respostas, esforço de raciocínio significativo ou mensagens de múltiplos turnos, reveja as mudanças disruptivas e não disruptivas antes de decidir migrar. Essas capacidades permanecem em versão de pré-visualização.

Antes de migrar

• Para compreender o âmbito das alterações, reveja as alterações disruptivas e não disruptivas para cada versão.

• O caminho de migração suportado é incremental. Se o teu código tem como alvo 2025-05-01-preview, primeiro migra para 2025-08-01-preview, depois continua em cada versão subsequente até chegares à versão alvo.

• Para uma migração lado a lado, crie objetos com nomes únicos que implementem os comportamentos da versão anterior. Esta abordagem preserva objetos existentes enquanto desenvolve e testa substitutos. Se um objeto suporta atualização no local, os passos específicos da versão indicam essa opção.

• Para cada objeto que migrar, comece por obter a definição atual do serviço de pesquisa para que possa rever as propriedades existentes antes de especificar a nova.

• Apague versões antigas apenas depois de a sua migração estar totalmente testada e implementada.

Como migrar

Esta secção cobre os passos de migração para as seguintes versões da API:

• 2026-08-01-preview
• 2026-05-01-preview
• 2026-04-01
• 2025-11-01-preview
• 2025-08-01-preview

2026-08-01-preview

Se estiver a migrar de 2026-05-01-preview, pode passar diretamente para 2026-08-01-preview. Esta migração requer atualizações às fontes de conhecimento do Work IQ, à paginação de listas, ao processamento de respostas, às ferramentas do servidor MCP e às chamadas afetadas do cliente gerado.

1. Migrar fontes de conhecimento sobre QI de trabalho
2. Atualizar paginação da lista
3. Atualização e recuperação do processamento de resposta
4. Atualizar código e clientes

Migrar fontes de conhecimento sobre QI de trabalho

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

1. Exporte a sua definição atual.

2. Atualize a fonte de conhecimento existente usando Fontes de Conhecimento - Criar ou Atualizar, ou criar uma substituição com um nome único para uma migração lado a lado.

3. Usa a 2026-08-01-preview versão da API e configura workIQParameters.entraAppAuthentication. As applicationId propriedades e federatedCredentialId são obrigatórias. A propriedade tenantId é opcional e, por predefinição, utiliza o tenant do serviço de pesquisa.

4. Se criou um substituto, atualize cada base de conhecimento que referencia a fonte de conhecimento anterior para usar o nome de substituição.

5. Atualize os pedidos de recuperação para incluir a asserção do utilizador no cabeçalho x-ms-query-work-iq-source-authorization.

Para configuração e exemplos, veja Criar uma fonte de conhecimento de QI de trabalho (pré-visualização).

Atualizar paginação da lista

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

1. Remover $top, $skip e $count dos pedidos de lista de fontes de conhecimento. Define pageSize de 1 a 3.000 para controlar o tamanho da página. Se o omitir, o serviço escolhe o tamanho da página.

2. Para filtrar por nome, defina search e searchType. O único valor suportado searchType é prefix, que também é o padrão. O pedido seguinte devolve até 100 fontes de conhecimento cujos nomes começam por contoso.

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

   Referência:Fontes de Conhecimento - Lista

3. Se a resposta contiver @odata.nextLink, envie o URL exatamente como foi devolvido. Não analises nem modifiques o seu estado de continuação.

Atualização e recuperação do processamento de resposta

Para tratar a nova referência do Work IQ e as formas de atividade suportadas por modelos:

1. Remover dependências em attributions, WorkIQAttribution, e seeMoreWebUrl. Ler os metadados do rótulo de sensibilidade da referência Work IQ em searchSensitivityLabelInfo.

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

Os fragmentos seguintes mostram as mudanças na forma da 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>"
      }
    }
  ]
}

Atualize o código e os clientes para 2026-08-01-preview

Para completar a sua migração:

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

2. Se utilizar o SDK do Azure, instale um pacote que seja compatível com 2026-08-01-preview e reveja as chamadas a listas posicionais devido a alterações na ordem dos parâmetros. Os chamadores REST não são afetados porque os parâmetros HTTP são codificados pelo nome. Em C#, preferem argumentos nomeados, como GetKnowledgeSourcesAsync(search: ..., pageSize: ...). Em Python, passa opções de lista como argumentos-chave.

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

4. Se criou fontes de conhecimento substitutas do Work IQ, apague as fontes anteriores apenas depois de a migração passar em todos os testes, a sua aplicação atualizada ser implementada e nenhuma base de conhecimento referenciar os nomes anteriores.

2026-05-01-preview

Se estiver a migrar de 2026-04-01 ou 2025-11-01-preview, pode passar diretamente para 2026-05-01-preview. Pedidos, respostas e objetos persistentes dessas versões continuam compatíveis. As diferenças são funcionalidades aditivas e renomeações de SDKs de linguagem.

1. Atualize a versão da API para 2026-05-01-preview nos pedidos REST. Os clientes SDK usam a versão padrão da API do pacote, por isso não precisas de passar um argumento explícito serviceVersion . Em vez disso, atualize para o pacote SDK 2026-05-01-preview.

2. Se usares o SDK Python ou JavaScript, atualiza o cliente de recuperação para KnowledgeBaseRetrievalClient e chama retrieve(...) em vez do antigo retrieveKnowledge(...). Para o mapeamento completo das estruturas do SDK, consulte Atualizar o código e os clientes para a pré-visualização de 2026-05-01.

3. (Opcional) Adote as novas 2026-05-01-preview funcionalidades, como a obtenção sensível à atualização, limites de documentos por origem e para o resultado final, predefinições persistentes de obtenção, CORS da base de conhecimento e metadados de etiquetas de sensibilidade do Purview nas respostas de obtenção. Nenhuma destas funcionalidades é necessária para manter uma solução existente a funcionar.

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

Os 2026-05-01-preview SDKs introduzem alterações na forma do código entre as linguagens suportadas:

Depois de atualizares as formas do cliente, executa o fluxo completo que cria o índice, carrega documentos, cria uma fonte de conhecimento, cria uma base de conhecimento, emite um pedido de recuperação e limpa recursos para confirmar a migração de ponta a ponta.

01-04-2026

Se estiver a migrar de 2025-11-01-preview, pode migrar diretamente para 2026-04-01. O seu índice e conteúdo mantêm-se inalterados. Só precisas de atualizar o esquema da base de conhecimento e a forma do pedido de recuperação.

1. Migrar fontes de conhecimento
2. Migrar a base de conhecimento
3. Atualize o pedido de recuperação
4. Atualização do consentimento de faturação
5. Atualizar código e clientes

Migrar fontes de conhecimento

Em 2026-04-01, os tipos de origem de conhecimento searchIndex, azureBlob, indexedOneLake e web estão geralmente disponíveis. Outros tipos de fontes de conhecimento permanecem em versão de visualização.

1. Use Knowledge Sources - Get (REST API) 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 deve transferir e o que deve remover:

   • Para searchIndex e web, transfere todos os valores das propriedades.

   • Para azureBlob e indexedOneLake, transfere todos os valores das propriedades, mas omite ingestionPermissionOptions de ingestionParameters. Esta propriedade não é suportada em 2026-04-01.

3. Use Fontes de Conhecimento - Criar ou Atualizar (API REST) para criar uma nova fonte de conhecimento com um nome único, a 2026-04-01 versão da API e os valores das propriedades do passo anterior.

   O exemplo seguinte mostra uma searchIndex fonte de conhecimento. Use um padrão semelhante para azureBlob, indexedOneLake, e 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 conhecimento

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

1. Use Knowledge Bases - Get (REST API) 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 deve transferir e o que deve remover:

   • Repare nas knowledgeSources referências. Transportem estas informações para a nova base de conhecimentos.

   • Se presente, remova outputMode, answerInstructions, e retrievalInstructions. Estas propriedades não são suportadas em 2026-04-01.

   • Se a tua base de conhecimento usar uma web fonte de conhecimento, mantém models. A recuperação na web requer sumarização baseada em modelos. Para todos os outros tipos de fonte de conhecimento, remova models.

3. Use Knowledge Bases - Create Or Update (API REST) para criar uma nova base de conhecimento com um nome único, a 2026-04-01 versão da API e apenas as propriedades suportadas.

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

Atualize o pedido de recuperação

O 2026-04-01 pedido de recuperação tem uma forma diferente da versão de pré-visualização:

• Use intents em vez de messages.

• Use maxOutputSizeInTokens em vez de maxOutputSize.

• Se presente, remova retrievalReasoningEffort e alwaysQuerySource. Estes parâmetros não são suportados em 2026-04-01.

• Para perguntas de seguimento, envie um novo pedido de recuperação com uma nova intenção semântica. 2026-04-01 não mantém uma transcrição de mensagens em curso.

Para testar a saída da sua base de conhecimento com uma consulta, use a 2026-04-01 versão do Knowledge Retrieval - Retrieve (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, a sua base de conhecimento recuperou com sucesso o conteúdo da fonte de conhecimento.

Atualização do consentimento de faturação

A partir da versão 2026-04-01 da API, o consentimento para faturação da recuperação agêntica é controlado por uma propriedade dedicada knowledgeRetrieval, separada de semanticSearch, que agora se aplica apenas à faturação do classificador semântico. knowledgeRetrieval é uma propriedade de plano de gestão, por isso configura-se através da API REST de Gestão de Pesquisa, não da API REST do Serviço de Pesquisa.

Use a versão pré-visualizada mais recente de Services - Create Or Update (API REST) para definir knowledgeRetrieval no 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 faturação, consulte Ativar ou desativar a faturação de recuperação agente.

Atualizar código e clientes para 2026-04-01

Para completar a sua migração:

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

2. Atualize quaisquer bases de conhecimento ou nomes de fonte de conhecimento codificados no seu código para referenciar os novos objetos criados durante a migração.

3. Se migrou azureBlob ou indexedOneLake fontes de conhecimento, atualize qualquer código ou scripts que façam referência ao índice, indexador, fonte de dados ou conjunto de competências associados pelo nome para apontar para os novos objetos.

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

5. Eliminar objetos de pré-visualização apenas depois de os novos objetos estarem totalmente validados e implementados.

2025-11-01-preview

Se estiver a migrar de 2025-08-01-preview, "knowledge agent" é renomeado para "knowledge base" e várias propriedades são realocadas para diferentes objetos e níveis dentro de uma definição de objeto.

1. Atualizar fontes de conhecimento do índice de pesquisa
2. Atualizar as fontes de conhecimento do azureBlob
3. Substituir o agente de conhecimento por base de conhecimento
4. Atualize o pedido de recuperação e envie uma consulta para testar as suas atualizações
5. Atualizar código do cliente

Atualizar uma fonte de conhecimento searchIndex

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

1. Liste todas as fontes de conhecimento por nome para encontrar a 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 rever 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 seguinte exemplo.

   {
        "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. Formule um pedido de Criar Fonte de Conhecimento como base para a 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 conhecimento.

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

   • Renomeie sourceDataSelect para sourceDataFields e mude a cadeia para um array com pares nome-valor para cada campo recuperável que queira consultar. Estes são os campos a devolver nos resultados de pesquisa, semelhantes a uma select cláusula numa consulta clássica.

4. Revê as tuas atualizações e depois envia o pedido 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 tem uma fonte de conhecimento migrada searchIndex que é retrocompatível com a versão anterior, usando as especificações corretas de propriedades para o 2025-11-01-preview.

A resposta inclui a definição completa do novo objeto. Para mais informações sobre novas propriedades disponíveis para este tipo de fonte de conhecimento, que agora estão disponíveis através de atualizações, veja Como criar uma fonte de conhecimento de índice de pesquisa.

Atualizar uma fonte de conhecimento do azureBlob

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

1. Liste todas as fontes de conhecimento por nome para encontrar a 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 rever 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 seu fluxo de trabalho incluir um modelo, a resposta deverá ser semelhante ao exemplo seguinte. Note que uma resposta inclui os nomes dos objetos gerados. Estes objetos são totalmente independentes da fonte de conhecimento e mantêm-se operacionais mesmo que atualize ou elimine a 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. Formule um pedido de Criar Fonte de Conhecimento como base para a 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 conhecimento.

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

   • Adicione ingestionParameters como um contentor para as seguintes propriedades filhas: "embeddingModel", "chatCompletionModel", "ingestionSchedule", "contentExtractionMode".

4. Revê as tuas atualizações e depois envia o pedido 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 tem uma fonte de conhecimento migrada azureBlob que é retrocompatível com a versão anterior, usando as especificações corretas de propriedades para o 2025-11-01-preview.

A resposta inclui a definição completa do novo objeto. Para mais informações sobre novas propriedades disponíveis para este tipo de fonte de conhecimento, que agora pode fazer através de atualizações, consulte Criar uma fonte de conhecimento em blob.

Substituir o agente de conhecimento pela base de conhecimento

1. As bases de conhecimento requerem uma fonte de conhecimento. Certifique-se de que tem uma fonte de conhecimento que atenda 2025-11-01-preview antes de começar.

2. Obtenha a definição atual para rever 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 seguinte exemplo.

   {
     "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. Formule um pedido de Criação de Base de Conhecimento como base para a 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:

   • Substituir o endpoint: /knowledgebases/{{knowledge-base-name}}. Dê à base de conhecimento um nome único.

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

   • Apagar requestLimits. As propriedades maxRuntimeInSeconds e maxOutputSize são agora especificadas diretamente no pedido de obtenção.

   • Atualização knowledgeSources:

     • Apague-o maxSubQueries e substitua-o por retrievalReasoningEffort (ver Definir o esforço de raciocínio de recuperação (pré-visualização)).

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

   • Sem alterações para models.

   • Atualização outputConfiguration:

     • Substitua outputConfiguration por outputMode.

     • Apagar attemptFastPath. Já não existe. O comportamento equivalente é implementado com retrievalReasoningEffort definido para o mínimo (ver Definir o esforço de raciocínio da recuperação (pré-visualização)).

     • Se a modalidade estiver definida para answerSynthesis, certifica-te de que defines o esforço de raciocínio de recuperação para baixo (padrão) ou médio.

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

4. Revê as tuas atualizações e depois envia o pedido 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 tem uma base de conhecimento em vez de um agente de conhecimento, e o objeto é compatível com a versão anterior.

A resposta inclui a definição completa do novo objeto. Para mais informações sobre novas propriedades disponíveis numa base de conhecimento, que agora pode fazer através de atualizações, consulte Como criar uma base de conhecimento.

Atualizar e testar a recuperação de dados para as atualizações de pré-visualização de 2025-11-01

O pedido de obtenção para o 2025-11-01-preview é modificado para suportar mais formatos, incluindo um pedido mais simples que minimiza o processamento do LLM. Para mais informações sobre a recuperação nesta pré-visualização, consulte Recuperar dados usando uma base de conhecimento. Esta secção explica como atualizar o seu código.

1. Mude o /agents/retrieve endpoint para /knowledgebases/retrieve.

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

3. Não são necessárias alterações a messages se estiveres a usar o nível de esforço de raciocínio de recuperação low ou medium. Substitua minimal por se usar raciocínio intents (ver messages).

4. Modificar knowledgeSourceParams para incluir quaisquer propriedades que tenham sido removidas do agente: rerankerThreshold, alwaysQuerySource, includeReferenceSourceData, includeReferences.

5. Adicionar retrievalReasoningEffort definir a minimum se estivesse a usar attemptFastPath. Se estava a usar maxSubQueries, já não existe. Utilize a definição retrievalReasoningEffort para especificar o processamento de subconsultas (consulte Definir o esforço de raciocínio para a recuperação (pré-visualização)).

Para testar a saída da sua base de conhecimento com uma consulta, use o 2025-11-01-previewKnowledge 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, a sua base de conhecimento recuperou com sucesso o conteúdo da fonte de conhecimento.

Atualizar código e clientes para pré-visualização de 2025-11-01

Para completar a sua migração, siga estes passos de limpeza:

1. Apenas para origens de conhecimento de blobs, actualize os clientes para utilizarem o novo índice. Se tiveres código ou script que executa um indexador ou referencia uma fonte de dados, índice ou conjunto de competências, certifica-te de que atualizas as referências para os novos objetos.

2. Substitua todas as referências aos agentes por knowledgeBases nos ficheiros de configuração, código, scripts e testes.

3. Atualize as chamadas do cliente para usar o 2025-11-01-preview.

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

01-08-2025-antevisão

Se tiver criado um agente de conhecimento usando a 2025-05-01-preview, a definição do seu agente inclui um array inline targetIndexes e uma propriedade opcional defaultMaxDocsForReranker .

A partir da versão da API 2025-08-01-preview, as fontes de conhecimento reutilizáveis substituem targetIndexes, e defaultMaxDocsForReranker deixa de ser suportado. Estas alterações urgentes exigem que:

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

Obtenha a configuração atual

Para obter a definição do seu agente, utilize a 2025-05-01-preview de Knowledge Agents - Get (REST API).

@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 seguinte exemplo. Copie os indexNamevalores , defaultRerankerThreshold, e defaultIncludeReferenceSourceData para uso nos próximos passos. defaultMaxDocsForReranker está obsoleto, por isso podes ignorar o 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, utilize as 2025-08-01-previewFontes de Conhecimento - Criar (API REST). Define searchIndexName para o valor que copiaste 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 único índice, mas podes direcionar múltiplos índices ou um blob do Azure. Para mais informações, consulte Criar uma fonte de conhecimento.

Atualize o agente

Para substituir targetIndexes por knowledgeSources na definição do seu agente, utilize o 2025-08-01-preview de Knowledge Agents - Create or Update (REST API). Define rerankerThreshold e includeReferenceSourceData para os valores que copiaste 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 referenciar uma fonte de conhecimento, mas podes direcionar várias fontes de conhecimento. Também pode usar outras propriedades para controlar o comportamento de recuperação, como alwaysQuerySource. Para mais informações, consulte Criar um agente de conhecimento.

Teste a obtenção para atualizações de versão prévia de 2025-08-01

Para testar a saída do seu agente utilizando uma consulta, use o 2025-08-01-preview de Knowledge Retrieval - Retrieve (REST API).

### 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 seu agente recuperou com sucesso o conteúdo da fonte de conhecimento.

Atualizar código e clientes para pré-visualização de 01-08-2025

Para completar a sua migração, siga estes passos de limpeza:

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

Alterações específicas da versão

Esta secção cobre alterações interrompidas e não interrompidas para as seguintes versões da API:

• 2026-08-01-preview
• 2026-05-01-preview
• 2026-04-01
• 2025-11-01-preview
• 2025-08-01-preview
• 2025-05-01-preview

2026-08-01-preview

A 2026-08-01-preview versão baseia-se na 2026-05-01-preview e inclui alterações interruptivas para aplicações que utilizam fontes de conhecimento do Work IQ, paginação de listas baseada em deslocamento, registos de atividade suportados por modelo, processamento de resultados de servidores MCP ou chamadas posicionais do cliente gerado.

Para rever a documentação de referência da API REST para esta versão, selecione o 2026-08-01-preview filtro de versões da API no topo da página.

2026-05-01-preview

2026-05-01-preview adiciona base de conhecimento, fonte de conhecimento e funcionalidades de obtenção sobre 2025-11-01-preview sem remover propriedades previamente persistidas. As bases de conhecimento e fontes de conhecimento existentes que criou em versões anteriores continuam a funcionar. Esta versão expõe maioritariamente novas funcionalidades e reverte alguns limites apenas de pré-visualização.

Para rever a documentação de referência da API REST para esta versão, selecione o 2026-05-01-preview filtro de versões da API no topo da página.

01-04-2026

2026-04-01 é a primeira versão estável da API para recuperação agêntica. Estabelece um contrato mínimo de recuperação extrativa e remove as capacidades de planeamento de consultas baseadas em mensagens e de síntese de respostas da fase de pré-visualização.

Para rever a documentação de referência da API REST para esta versão, selecione o 2026-04-01 filtro de versões da API no topo da página.

2025-11-01-preview

Para rever a documentação de referência da API REST para esta versão, selecione o 2025-11-01-preview filtro de versões da API no topo da página.

01-08-2025-antevisão

Para rever a documentação de referência da API REST para esta versão, selecione o 2025-08-01-preview filtro de versões da API no topo da página.

2025-05-01-preview

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

Para rever a documentação de referência da API REST para esta versão, selecione o 2025-05-01-preview filtro de versões da API no topo da página.

Conteúdo relacionado

• Busca de agência no Pesquisa de IA do Azure
• Crie uma base de conhecimento
• Consultar uma base de conhecimento