에이전트 검색 코드를 최신 버전으로 마이그레이션

에이전트 검색 코드가 이전 API 버전을 대상으로 하는 경우 이 문서에서는 최신 버전으로 마이그레이션하는 시기와 방법을 설명합니다. 또한 에이전틱 검색을 지원하는 모든 API 버전에 대해 깨지는 변경과 호환되는 변경을 구분해 설명합니다.

마이그레이션 지침은 최신 API 버전에서 기존 솔루션을 실행하는 데 도움이 됩니다. 이 문서의 지침은 앱이 이전과 같이 실행되도록 API 수준에서 호환성이 손상되는 변경 내용을 해결하는 데 도움이 됩니다. 새 기능을 추가하는 방법에 대한 도움말은 Azure AI 검색의 새로운 기능에서 시작하세요.

마이그레이션 시기

에이전트 검색을 지원하는 대부분의 버전에는 호환성이 손상되는 변경이 도입되었습니다. API 버전 값을 유지하여 변경되지 않은 이전 코드를 계속 실행할 수 있지만 버그 수정, 개선 및 최신 기능을 활용하려면 코드를 업데이트해야 합니다.

코드가 미리 보기 버전을 대상으로 하는 경우 사용 사례가 완전히 지원되는 경우에만 안정적인 최신 버전으로 2026-04-01마이그레이션하는 것이 좋습니다. 응답 합성이나 고도의 추론 작업, 혹은 다중 턴 대화가 포함된 경우라면 마이그레이션 실행에 앞서 호환성 단절 및 유지 변경 사항을 검토해야 합니다. 이러한 기능은 미리 보기로 유지합니다.

마이그레이션하기 전에

• 변경 범위를 이해하려면 각 버전에 대한 호환성이 손상되는 변경 내용과 손상되지 않는 변경 내용을 검토하십시오.

• 지원되는 마이그레이션 경로는 증분입니다. 코드가 2025-05-01-preview대상인 경우 먼저 마이그레이션한 다음 대상 버전에 2025-08-01-preview도달할 때까지 각 후속 버전을 계속 진행합니다.

• 병렬 마이그레이션의 경우 이전 버전의 동작을 구현하는 고유하게 명명된 개체를 만듭니다. 이 방법은 교체를 개발하고 테스트하는 동안 기존 개체를 유지합니다. 개체가 현재 위치에서 업데이트를 지원하는 경우 버전별 단계에서 해당 옵션을 호출합니다.

• 마이그레이션하는 각 개체에 대해 새 속성을 지정하기 전에 기존 속성을 검토할 수 있도록 검색 서비스에서 현재 정의를 가져오는 것부터 시작합니다.

• 마이그레이션이 완전히 테스트되고 배포된 후에만 이전 버전을 삭제합니다.

마이그레이션 방법

이 섹션에서는 다음 API 버전에 대한 마이그레이션 단계를 설명합니다.

• 2026-08-01-preview
• 2026-05-01-미리보기
• 2026-04-01
• 2025-11-01-preview
• 2025-08-01-preview

2026-08-01-preview

2026-05-01-preview에서 마이그레이션하는 경우 직접 2026-08-01-preview이동할 수 있습니다. 이 마이그레이션을 수행하려면 Work IQ 기술 원본, 목록 페이징, 응답 처리, MCP 서버 도구 및 영향을 받는 생성된 클라이언트 호출에 대한 업데이트가 필요합니다.

1. Work IQ 기술 자료 마이그레이션
2. 목록 페이징 업데이트
3. 가져오기 응답 처리 업데이트
4. 코드 및 클라이언트 업데이트

Work IQ 기술 자료 마이그레이션

Work IQ 기술 원본을 새 인증 구성으로 마이그레이션하려면 다음을 수행합니다.

1. 현재 정의를 내보냅니다.

2. Knowledge Sources - Create Or Update를 사용하여 기존 지식 원본을 업데이트하거나, 병렬 마이그레이션을 위해 고유한 이름의 대체 항목을 만드세요.

3. 2026-08-01-preview API 버전을 사용하고 workIQParameters.entraAppAuthentication을 구성합니다. applicationId 및 federatedCredentialId 속성은 필수입니다. 이 속성은 tenantId 선택 사항이며 기본적으로 검색 서비스의 테넌트에 적용됩니다.

4. 대체를 만든 경우 이전 기술 원본을 참조하는 각 기술 자료를 업데이트하여 대체 이름을 사용합니다.

5. 사용자 어설션을 x-ms-query-work-iq-source-authorization 헤더에 전달하도록 retrieve 요청을 업데이트합니다.

설정 및 예제는 Work IQ 기술 원본 만들기(미리 보기)를 참조하세요.

목록 페이지 매김 업데이트

오프셋 기반 페이징을 커서 기반 페이징으로 바꾸려면 다음을 수행합니다.

1. 지식 원본 목록 요청에서 $skip, $count 및 $top를 제거합니다. 페이지 크기를 제어하려면 1에서 3,000까지 설정합니다 pageSize . 생략하면 서비스에서 페이지 크기를 선택합니다.

2. 이름으로 필터링하려면 다음을 설정합니다 searchsearchType. 지원되는 searchType 유일한 값은 prefix기본값이기도 합니다. 다음 요청은 이름이 .로 시작하는 최대 100개의 기술 원본을 contoso반환합니다.

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

   참조:기술 자료 - 목록

3. 응답에 @odata.nextLink이(가) 포함되어 있으면, 반환된 그대로 해당 URL을 정확하게 전송하세요. 연속 상태를 구문 분석하거나 수정하지 마세요.

조회 응답 처리 업데이트

새 Work IQ 참조 및 모델 기반 작업 셰이프를 처리하려면 다음을 수행합니다.

1. WorkIQAttribution, seeMoreWebUrl, 및 attributions에 대한 종속성을 제거합니다. Work IQ 참조에서 searchSensitivityLabelInfo 민감도 레이블 메타데이터를 읽습니다.

2. 쿼리 계획, 응답 합성 및 웹 요약 활동 레코드에서 중첩된 model 개체의 modelName 및 deploymentId을 읽습니다. 중첩된 개체와 두 속성은 모두 선택 사항입니다.

다음 조각에서는 응답 셰이프 변경 내용을 보여 줍니다.

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

2026-08-01-preview에서 동일한 프래그먼트는 다음과 같은 형태를 사용합니다.

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

2026-08-01-preview에 대한 코드 및 클라이언트 업데이트

마이그레이션을 완료하려면 다음을 수행합니다.

1. 각 MCP 서버 tools 항목에서 inclusionMode을 resultsProcessing(으)로 바꾸세요. reranked을(를) rerank(으)로 매핑하고 always을(를) none(으)로 매핑합니다. rerank 값이 기본값입니다. none 값은 재순위 지정을 건너뛰고 도구의 기본 결과 순서를 유지합니다. 설치의 경우 MCP 서버 지식 원본에 대한 도구 구성을 참조하세요.

2. Azure SDK 사용하는 경우 지원하는 2026-08-01-preview패키지를 설치하고 매개 변수 순서 변경에 대한 위치 목록 호출을 검토합니다. HTTP 매개 변수는 이름으로 키가 지정되므로 REST 호출자는 영향을 받지 않습니다. C#에서는 .와 같은 GetKnowledgeSourcesAsync(search: ..., pageSize: ...)명명된 인수를 선호합니다. Python 목록 옵션을 키워드 인수로 전달합니다.

3. 프로덕션을 업데이트하기 전에 Work IQ 인증 및 참조, 커서 페이징, 활동 레코드 역직렬화, MCP 서버 결과 순서 지정 및 생성된 클라이언트 호출을 테스트합니다.

4. 대체 Work IQ 기술 원본을 만든 경우 마이그레이션이 모든 테스트를 통과한 후에만 이전 원본을 삭제하고, 업데이트된 애플리케이션이 배포되고, 이전 이름을 참조하는 기술 자료가 없습니다.

2026-05-01-미리보기

2026-04-01 또는 2025-11-01-preview에서 마이그레이션하는 경우 직접 2026-05-01-preview이동할 수 있습니다. 해당 버전의 요청, 응답 및 지속형 개체는 호환됩니다. 차이점은 추가 기능과 언어 SDK의 이름 바꾸기입니다.

1. REST 요청에서 API 버전을 2026-05-01-preview 업데이트합니다. SDK 클라이언트는 패키지의 기본 API 버전을 사용하므로 명시적 serviceVersion 인수를 전달할 필요가 없습니다. 대신 SDK 패키지로 2026-05-01-preview 업그레이드합니다.

2. Python 또는 JavaScript SDK를 사용하는 경우 검색 클라이언트를 KnowledgeBaseRetrievalClient 업데이트하고 레거시 retrieve(...) 대신 retrieveKnowledge(...) 호출합니다. 전체 SDK 셰이프 매핑은 2026-05-01-preview에 대한 업데이트 코드 및 클라이언트를 참조하세요.

3. (선택 사항) 2026-05-01-preview, 원본별 및 최종 결과의 문서 수 상한, 저장된 retrieve 기본값, 기술 자료 CORS, retrieve 응답의 Purview 민감도 레이블 메타데이터와 같은 새로운 기능을 도입합니다. 기존 솔루션을 계속 작동하려면 이러한 기능이 필요하지 않습니다.

2026-05-01-preview에 대한 코드 및 클라이언트 업데이트

SDK는 2026-05-01-preview 지원되는 언어에서 코드 셰이프 변경을 도입합니다.

클라이언트 셰이프를 업데이트한 후, 인덱스를 생성하고, 문서를 업로드하고, 지식 소스를 생성하고, 지식 베이스를 생성하고, 검색 요청을 보내고, 리소스를 정리하는 전체 흐름을 실행하여 마이그레이션이 처음부터 끝까지 제대로 수행되는지 확인하세요.

2026년 4월 1일

2025-11-01-preview에서 마이그레이션하는 경우 2026-04-01로 직접 마이그레이션할 수 있습니다. 인덱스와 콘텐츠는 변경되지 않은 상태로 유지됩니다. 기술 자료 스키마 및 검색 요청 셰이프만 업데이트하면 됩니다.

1. 지식 원본 마이그레이션
2. 기술 자료 마이그레이션
3. 검색 요청 업데이트
4. 청구 동의 업데이트
5. 코드 및 클라이언트 업데이트

지식 원본 마이그레이션

에서 2026-04-01, searchIndex, azureBlobindexedOneLake및 web 기술 자료 형식을 일반적으로 사용할 수 있습니다. 다른 기술 자료 유형은 미리 보기로 유지합니다.

1. 기술 자료 사용 - Get(REST API)을 사용하여 현재 정의를 가져옵니다.

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

2. 응답에서 수행할 작업과 제거할 대상을 식별합니다.

   • searchIndex 및 web에 대해 모든 속성 값을 유지합니다.

   • azureBlob 및 indexedOneLake에 대해 모든 속성 값을 전달하되, ingestionPermissionOptions에서는 ingestionParameters를 생략합니다. 이 속성은 2026-04-01에서 지원되지 않습니다.

3. 기술 자료 사용 - REST API( 만들기 또는 업데이트 )를 사용하여 이전 단계의 고유한 이름, 2026-04-01 API 버전 및 속성 값을 사용하여 새 지식 원본을 만듭니다.

   다음 예제는 지식 소스를 나타내는 searchIndex입니다. azureBlob, indexedOneLake, 및 web 지식 원천에 대해 유사한 패턴을 사용합니다.

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

기술 자료 마이그레이션

기술 자료에는 2026-04-01 버전보다 간단한 스키마가 2025-11-01-preview 있습니다. 이 스키마는 응답 생성 설정을 유지하고 knowledgeSources 삭제합니다. 새 개체를 만들기 전에 현재 정의를 검토합니다.

1. 기술 자료 - Get(REST API)을 사용하여 현재 정의를 가져옵니다.

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

2. 응답에서 수행할 작업과 제거할 대상을 식별합니다.

   • knowledgeSources 참조를 주의하세요. 이러한 것들을 새 지식 기반으로 옮깁니다.

   • 있는 경우 제거 outputMode, answerInstructions및 retrievalInstructions. 이러한 속성은 .에서 2026-04-01지원되지 않습니다.

   • 다음과 같은 web 지식 소스를 사용하는 경우, models을(를) 유지하십시오. 웹 검색에는 모델 기반 요약이 필요합니다. 다른 모든 지식 소스 유형에 대해 models을 제거합니다.

3. 기술 자료 - REST API(만들기 또는 업데이트)를 사용하여 고유한 이름, 2026-04-01 API 버전 및 지원되는 속성만 사용하여 새 기술 자료를 만듭니다.

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

검색 요청 업데이트

검색 요청의 2026-04-01 모양은 미리 보기 버전과 다릅니다.

• 대신 intents사용합니다messages.

• 대신 maxOutputSizeInTokens사용합니다maxOutputSize.

• 있는 경우 제거 retrievalReasoningEffort 및 alwaysQuerySource. 이러한 매개 변수는 .에서 2026-04-01지원되지 않습니다.

• 후속 질문의 경우 새 의미 체계 의도를 사용하여 새 검색 요청을 보냅니다. 2026-04-01 는 실행 중인 메시지 기록을 유지 관리하지 않습니다.

쿼리를 사용하여 기술 자료 출력을 테스트하려면 기술 자료 검색 - 검색(REST API) 버전을 사용합니다2026-04-01.

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
}

응답에 HTTP 코드가 있는 200 OK 경우 기술 자료는 지식 원본에서 콘텐츠를 성공적으로 검색했습니다.

청구 동의 업데이트

2026-04-01 API 버전부터 에이전트형 검색 청구 동의는 knowledgeRetrieval와는 별개의 전용 semanticSearch 속성으로 제어되며, knowledgeRetrieval는 이제 시맨틱 랭커 청구에만 적용됩니다. knowledgeRetrieval 는 관리 평면 속성이므로 Search Service REST API가 아닌 Search Management REST API를 통해 설정합니다.

최신 미리 보기 버전의 서비스 - REST API(만들기 또는 업데이트 )를 사용하여 검색 서비스에 설정합니다 knowledgeRetrieval .

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

유효한 값 및 청구 세부 정보는 에이전트 검색 청구 사용 또는 사용 안 함을 참조하세요.

2026-04-01에 대한 코드 및 클라이언트 업데이트

마이그레이션을 완료하려면 다음을 수행합니다.

1. 클라이언트 호출을 2026-04-01 API 버전을 사용하도록 업데이트합니다.

2. 마이그레이션 중에 만든 새 개체를 참조하도록 코드에서 하드 코딩된 기술 자료 또는 기술 원본 이름을 업데이트합니다.

3. 마이그레이션한 azureBlob 또는 indexedOneLake 지식 소스를 사용하는 경우, 관련 인덱스, 인덱서, 데이터 원본 또는 기술 세트를 참조하는 코드나 스크립트를 이름을 기준으로 업데이트하여 새 개체를 가리키도록 하세요.

4. 응답을 검색하는 프로세스를 처리하는 코드를 업데이트합니다. 응답은 합성된 답변이 아니라 추출된 activity 및 references 접지 콘텐츠를 반환합니다.

5. 새 개체의 유효성을 완전히 검사하고 배포한 후에만 미리 보기 개체를 삭제합니다.

2025-11-01-preview

2025-08-01-preview에서 마이그레이션하는 경우 "지식 에이전트"의 이름이 "기술 자료"로 바뀌고 여러 속성이 개체 정의 내의 다른 개체 및 수준으로 재배치됩니다.

1. searchIndex 기술 자료 업데이트
2. azureBlob 기술 자료 업데이트
3. 지식 에이전트를 지식 베이스로 교체하기
4. 검색 요청을 업데이트하고 쿼리를 보내 업데이트를 테스트합니다.
5. 클라이언트 코드 업데이트

searchIndex 기술 자료 업데이트

이 절차에서는 이전 2025-08-01 버전과 동일한 기능 수준에서 새 2025-11-01-previewsearchIndex 기술 원본을 만듭니다. 기본 인덱스 자체에는 업데이트가 필요하지 않습니다.

1. 모든 기술 자료를 이름으로 나열하여 지식 원본을 찾습니다.

   ### 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. 기존 속성을 검토하려면 현재 정의를 가져옵니다.

   ### 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
   

   응답은 다음 예제와 유사해야 합니다.

   {
        "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. 마이그레이션의 기초로 기술 자료 만들기 요청을 작성합니다.

   08-01-preview JSON으로 시작합니다.

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

   2025-11-01-preview 마이그레이션에 대해 다음과 같이 업데이트합니다.

   • 지식 원본에 새 이름을 지정합니다.

   • API 버전을 .로 2025-11-01-preview변경합니다.

   • sourceDataSelect 이름을 sourceDataFields로 변경하고, 쿼리할 검색 가능한 각 필드에 대한 이름-값 쌍을 포함하는 배열로 문자열을 변환합니다. 검색 결과에서 반환할 필드는 클래식 쿼리의 select 절과 유사합니다.

4. 업데이트를 검토한 다음 요청을 보내 개체를 만듭니다.

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

이제 2025-11-01-preview에 대한 올바른 속성 사양을 사용하는, 이전 버전과 호환되는 마이그레이션된 searchIndex 지식 소스를 갖게 되었습니다.

응답에는 새 개체의 전체 정의가 포함됩니다. 이제 업데이트를 통해 수행할 수 있는 이 기술 자료 유형에 사용할 수 있는 새 속성에 대한 자세한 내용은 검색 인덱스 지식 원본을 만드는 방법을 참조하세요.

azureBlob 기술 자료 업데이트

이 절차에서는 이전 2025-08-01 버전과 동일한 기능 수준에서 새 2025-11-01-previewazureBlob 기술 원본을 만듭니다. 데이터 원본, 기술 세트, 인덱서, 인덱스 등 생성된 개체의 새 집합을 만듭니다.

1. 모든 기술 자료를 이름으로 나열하여 지식 원본을 찾습니다.

   ### 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. 기존 속성을 검토하려면 현재 정의를 가져옵니다.

   ### 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
   

   워크플로에 모델이 포함된 경우 응답은 다음 예제와 유사해야 합니다. 응답에는 생성된 개체의 이름이 포함됩니다. 이러한 개체는 지식 원본과 완전히 독립적이며 기술 자료를 업데이트하거나 삭제하는 경우에도 작동 상태를 유지합니다.

    {
      "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. 마이그레이션의 기초로 기술 자료 만들기 요청을 작성합니다.

   08-01-preview JSON으로 시작합니다.

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

   2025-11-01-preview 마이그레이션에 대해 다음과 같이 업데이트합니다.

   • 지식 원본에 새 이름을 지정합니다.

   • API 버전을 .로 2025-11-01-preview변경합니다.

   • ingestionParameters을(를) 다음 자식 속성들의 컨테이너로 추가하세요: "embeddingModel", "chatCompletionModel", "ingestionSchedule", "contentExtractionMode".

4. 업데이트를 검토한 다음 요청을 보내 개체를 만듭니다. 인덱서 파이프라인에 대해 생성된 새 개체가 만들어집니다.

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

이제 2025-11-01-preview에 대한 올바른 속성 사양을 사용하는, 이전 버전과 호환되는 마이그레이션된 azureBlob 지식 소스를 갖게 되었습니다.

응답에는 새 개체의 전체 정의가 포함됩니다. 이제 업데이트를 통해 수행할 수 있는 이 기술 자료 유형에 사용할 수 있는 새 속성에 대한 자세한 내용은 Blob 지식 원본 만들기를 참조하세요.

지식 에이전트를 지식 기반으로 바꾸기

1. 지식 베이스에는 지식 소스가 필요합니다. 시작하기 전에 대상으로 하는 지식 원본이 있는지 확인합니다 2025-11-01-preview .

2. 기존 속성을 검토하려면 현재 정의를 가져옵니다.

   ### 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
   

   응답은 다음 예제와 유사해야 합니다.

   {
     "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. 마이그레이션의 기준으로 기술 자료 만들기 요청을 작성합니다.

   08-01-preview JSON으로 시작합니다.

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

   2025-11-01-preview 마이그레이션에 대해 다음과 같이 업데이트합니다.

   • 엔드포인트를 바꿉다. /knowledgebases/{{knowledge-base-name}}. 기술 자료에 고유한 이름을 지정합니다.

   • API 버전을 .로 2025-11-01-preview변경합니다.

   • 를 삭제합니다 requestLimits. 이제 maxRuntimeInSeconds 및 maxOutputSize 속성은 retrieve 요청에 직접 지정됩니다.

   • 업데이트 knowledgeSources:

     • maxSubQueries를 삭제하고 retrievalReasoningEffort로 바꿉니다(검색 추론 노력 설정(미리 보기) 참조).

   • alwaysQuerySource, includeReferenceSourceData, includeReferences, 및 rerankerThreshold를 knowledgeSourceParams의 섹션으로 이동합니다.

   • 에 대한 models변경 내용이 없습니다.

   • 업데이트 outputConfiguration:

     • outputConfiguration를 outputMode으로 대체합니다.

     • 를 삭제합니다 attemptFastPath. 더 이상 존재하지 않습니다. 동등한 동작은 최소로 설정하여 retrievalReasoningEffort 구현됩니다( 검색 추론 작업 설정(미리 보기) 참조).

     • 형식이 설정된 answerSynthesis경우 검색 추론 노력을 낮음(기본값) 또는 보통으로 설정해야 합니다.

   • ingestionParameters azureBlob 지식 원본을 만들기 위한 요구 사항으로 2025-11-01-preview를 추가합니다.

4. 업데이트를 검토한 다음 요청을 보내 개체를 만듭니다. 인덱서 파이프라인에 대해 생성된 새 개체가 만들어집니다.

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

이제는 지식 에이전트 대신 지식 베이스를 사용하며, 해당 객체는 이전 버전과 하위 호환됩니다.

응답에는 새 개체의 전체 정의가 포함됩니다. 이제 업데이트를 통해 수행할 수 있는 기술 자료에서 사용할 수 있는 새 속성에 대한 자세한 내용은 기술 자료를 만드는 방법을 참조하세요.

2025-11-01-preview 업데이트에 대한 검색 업데이트 및 테스트

LLM 처리를 최소화하는 간단한 요청을 포함하여 더 많은 셰이프를 지원하기 위해 2025-11-01-preview 검색 요청이 수정됩니다. 이 미리 보기의 검색에 대한 자세한 내용은 기술 자료를 사용하여 데이터 검색을 참조하세요. 이 섹션에서는 코드를 업데이트하는 방법을 설명합니다.

1. 엔드포인트를 /agents/retrieve .로 /knowledgebases/retrieve변경합니다.

2. API 버전을 .로 2025-11-01-preview변경합니다.

3. medium 또는 messages를 사용하는 경우 low는 변경할 필요가 없습니다. messages 추론을 사용하는 경우 minimal를 intents로 바꾸세요(검색 추론 수준 설정(미리 보기) 참조).

4. 에이전트에서 제거된 속성인 knowledgeSourceParams, rerankerThreshold, alwaysQuerySource, includeReferenceSourceData를 포함하도록 includeReferences을 수정하십시오.

5. retrievalReasoningEffort을(를) 사용 중이라면 minimum을(를) attemptFastPath로 설정하십시오. maxSubQueries을(를) 사용하고 있었다면, 이제 더 이상 존재하지 않습니다. 설정을 retrievalReasoningEffort 사용하여 하위 쿼리 처리를 지정합니다( 검색 추론 작업 설정(미리 보기) 참조).

쿼리를 사용하여 기술 자료의 출력을 테스트하려면 기술 자료 검색 - 검색(REST API)을 사용합니다2025-11-01-preview.

### 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
}

응답에 HTTP 코드가 있는 200 OK 경우 기술 자료는 지식 원본에서 콘텐츠를 성공적으로 검색했습니다.

2025-11-01-preview에 대한 코드 및 클라이언트 업데이트

마이그레이션을 완료하려면 다음 정리 단계를 수행합니다.

1. Blob 지식 원본의 경우에만 새 인덱스를 사용하도록 클라이언트를 업데이트합니다. 인덱서를 실행하거나 데이터 원본, 인덱스 또는 기술 세트를 참조하는 코드 또는 스크립트가 있는 경우 새 개체에 대한 참조를 업데이트해야 합니다.

2. 모든 에이전트 참조를 knowledgeBases 구성 파일, 코드, 스크립트 및 테스트로 대체합니다.

3. 를 사용하도록 클라이언트 호출을 업데이트합니다 2025-11-01-preview.

4. 이전 셰이프를 사용하여 만든 캐시된 정의를 지우거나 다시 생성합니다.

2025-08-01-preview

2025-05-01-preview를 사용하여 지식 에이전트를 만든 경우 에이전트의 정의에는 인라인 targetIndexes 배열과 선택적 defaultMaxDocsForReranker 속성이 포함됩니다.

2025-08-01-preview API 버전부터 재사용 가능한 지식 원본이 대체targetIndexes되며 defaultMaxDocsForReranker 더 이상 지원되지 않습니다. 이러한 호환성이 손상되는 변경을 적용하려면 다음을 수행해야 합니다.

1. 현재 targetIndexes 구성 가져오기
2. 동등한 기술 자료 만들기
3. 에이전트를 knowledgeSources 대신 targetIndexes을 사용하도록 업데이트
4. 쿼리를 보내 검색 테스트
5. 클라이언트에서 targetIndexes를 사용하는 코드를 제거하고 업데이트하십시오

현재 구성 가져오기

에이전트의 정의를 검색하려면 기술 자료 에이전트 - Get(REST API)을 사용합니다2025-05-01-preview.

@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}}

응답은 다음 예제와 유사해야 합니다. 다음 단계에서 사용할 indexName, defaultRerankerThreshold, 및 defaultIncludeReferenceSourceData 값을 복사하십시오. defaultMaxDocsForReranker 는 더 이상 사용되지 않으므로 해당 값을 무시할 수 있습니다.

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

기술 자료 만들기

기술 자료를 만들 searchIndex 려면 기술 자료 - 만들기(REST API)를 사용합니다2025-08-01-preview. 이전에 복사한 값으로 설정합니다 searchIndexName .

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

이전 예제에서는 하나의 인덱스를 나타내는 기술 원본을 만들지만 여러 인덱스 또는 Azure Blob을 대상으로 지정할 수 있습니다. 자세한 내용은 기술 자료 만들기를 참조하세요.

에이전트 업데이트

에이전트 정의에서 targetIndexes을(를) knowledgeSources으로 바꾸려면 2025-08-01-preview의 를 사용하세요. rerankerThreshold 및 includeReferenceSourceData을 이전에 복사한 값으로 설정합니다.

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

이전 예제에서는 하나의 지식 원본을 참조하도록 정의를 업데이트하지만 여러 기술 원본을 대상으로 지정할 수 있습니다. 다른 속성을 사용하여 검색 동작(예: alwaysQuerySource.)을 제어할 수도 있습니다. 자세한 내용은 기술 자료 에이전트 만들기를 참조하세요.

2025-08-01-preview 업데이트에 대한 검색 테스트

쿼리를 사용하여 에이전트의 출력을 테스트하려면 기술 자료 검색 - 검색(REST API)을 사용합니다2025-08-01-preview.

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

응답에 HTTP 코드가 있는 200 OK 경우 에이전트는 지식 원본에서 콘텐츠를 성공적으로 검색했습니다.

2025-08-01-preview에 대한 코드 및 클라이언트 업데이트

마이그레이션을 완료하려면 다음 정리 단계를 수행합니다.

• 모든 targetIndexes 참조를 knowledgeSources 구성 파일, 코드, 스크립트 및 테스트로 대체합니다.
• 를 사용하도록 클라이언트 호출을 업데이트합니다 2025-08-01-preview.
• 이전 셰이프를 사용하여 만든 캐시된 에이전트 정의를 지우거나 다시 생성합니다.

버전별 변경 내용

이 섹션에서는 다음 API 버전의 호환성이 깨지는 변경 사항과 호환성이 깨지지 않는 변경 사항을 설명합니다.

• 2026-08-01-preview
• 2026-05-01-미리보기
• 2026-04-01
• 2025-11-01-preview
• 2025-08-01-preview
• 2025-05-01-preview

2026-08-01-preview

이 2026-08-01-preview 버전은 2026-05-01-preview 에서 빌드되며 Work IQ 지식 원본, 오프셋 기반 목록 페이징, 모델 기반 활동 레코드, MCP 서버 결과 처리 또는 위치 생성 클라이언트 호출을 사용하는 애플리케이션에 대한 호환성이 손상되는 변경 내용을 포함합니다.

이 버전에 대한 REST API 참조 설명서를 검토하려면 페이지 맨 위에 있는 2026-08-01-preview API 버전 필터를 선택합니다.

2026-05-01-미리보기

2026-05-01-preview 는 이전에 지속된 속성을 제거하지 않고 2025-11-01-preview 위에 기술 자료, 기술 자료 및 검색 기능을 추가합니다. 이전 미리 보기 버전에서 만든 기존 기술 자료 및 지식 원본은 계속 사용할 수 있습니다. 이 버전은 대부분 새 기능을 노출하고 몇 가지 미리 보기 전용 제한을 되돌려줍니다.

이 버전에 대한 REST API 참조 설명서를 검토하려면 페이지 맨 위에 있는 2026-05-01-preview API 버전 필터를 선택합니다.

2026년 4월 1일

2026-04-01 는 에이전트 검색을 위한 안정적인 첫 번째 API 버전입니다. 최소 추출 검색 계약을 설정하고 미리 보기 시대의 메시지 기반 쿼리 계획 및 응답 합성 기능을 제거합니다.

이 버전에 대한 REST API 참조 설명서를 검토하려면 페이지 맨 위에 있는 2026-04-01 API 버전 필터를 선택합니다.

2025-11-01-preview

이 버전에 대한 REST API 참조 설명서를 검토하려면 페이지 맨 위에 있는 2025-11-01-preview API 버전 필터를 선택합니다.

2025-08-01-preview

이 버전에 대한 REST API 참조 설명서를 검토하려면 페이지 맨 위에 있는 2025-08-01-preview API 버전 필터를 선택합니다.

2025-05-01-프리뷰

이 API 버전은 에이전트 검색 및 지식 에이전트를 소개합니다. 각 에이전트 정의에는 단일 인덱스 targetIndexes 및 선택적 속성(예: defaultRerankerThreshold 및 .)을 지정하는 배열이 defaultIncludeReferenceSourceData필요합니다.

이 버전에 대한 REST API 참조 설명서를 검토하려면 페이지 맨 위에 있는 2025-05-01-preview API 버전 필터를 선택합니다.

관련 콘텐츠

• Azure AI 검색에서 에이전틱 검색
• 기술 자료 만들기
• 기술 자료 쿼리