에이전트 애플리케이션에서 새 에이전트 엔드포인트 및 게시 환경으로 마이그레이션

이 가이드에서는 Microsoft Foundry에서 에이전트 게시 환경이 어떻게 변경되었는지 설명합니다. 별도의 에이전트 애플리케이션 리소스를 만든 레거시 모델과 새 에이전트 개체 모델을 비교하고 기존 에이전트 및 게시된 애플리케이션을 마이그레이션하는 단계를 안내합니다.

변경 개요

새 에이전트 개체 모델은 에이전트 애플리케이션 및 에이전트 배포를에이전트 개체 자체로 축소합니다. 예전에는 게시 과정에서 고유 ID, 엔드포인트, 배포 환경을 포함한 별도의 에이전트 애플리케이션 리소스가 생성되었습니다. 이제 모든 에이전트에는 생성된 순간부터 이러한 기능이 있습니다.

이전(레거시 모델)

  1. 리소스 모델: 에이전트(데이터 평면), 에이전트 애플리케이션(컨트롤 플레인) 및 배포(컨트롤 플레인)는 별도의 개체입니다.
  2. 에이전트 개체 속성: id (에이전트의 고유 식별자), name및 versions (최신 에이전트 버전)
  3. ID: Foundry 프로젝트의 게시되지 않은 에이전트는 Entra 에이전트 ID와 Entra 에이전트 청사진을 공유합니다. 게시되면 에이전트는 에이전트 애플리케이션 리소스 범위 내에서 고유한 ID와 청사진을 부여받습니다.
  4. 게시: 두 가지 동작. 에이전트를 게시하면 에이전트 애플리케이션 리소스와 배포가 생성되고, 해당 배포는 게시된 에이전트 버전을 참조하게 됩니다. 에이전트 애플리케이션은 100% 트래픽을 해당 버전으로 라우팅하는 안정적인 엔드포인트를 노출합니다. 배포는 시작/중지 수명 주기 관리를 지원합니다. 두 번째 제스처는 에이전트 애플리케이션을 Microsoft 365 및 Teams에 게시할 수 있다는 것입니다.

Foundry 프로젝트가 에이전트 버전, 에이전트 및 에이전트 애플리케이션을 구성하는 방법을 보여 주는 다이어그램

After(새 모델)

  1. 리소스 모델: 에이전트 개체만 존재합니다(데이터 평면 및 컨트롤 플레인). 그들은 에이전트 애플리케이션 및 배포가 담당했던 책임을 흡수합니다.
  2. 에이전트 개체 속성: id, name, versions, agent_endpoint (안정적인 엔드포인트), protocol_configuration, authorization_schemesversion_selector, blueprintinstance_identity및 agent_card (소비자 및 A2A에 대한 에이전트 세부 정보 및 기능을 표시합니다).
  3. ID: 새로 만든 에이전트는 기본적으로 고유한 Entra 에이전트 청사진 및 Entra 에이전트 ID를 받습니다. Bring-your-own Entra 에이전트 청사진은 지원되지만 기본값은 아닙니다.
  4. 게시: 두 개의 동등한 제스처입니다. 먼저 안정적인 엔드포인트를 통해 노출할 에이전트 버전을 선택합니다. 둘째, 에이전트의 안정적인 엔드포인트를 M365/Teams에 게시합니다.

Foundry 프로젝트가 에이전트 버전 및 에이전트를 구성하는 방법을 보여 주는 다이어그램

키 시프트: 에이전트 만들기는 안정적인 엔드포인트 및 고유한 에이전트 ID를 가져오는 데 필요한 유일한 단계 입니다. 엔드포인트에 대한 별도의 게시 단계는 없습니다. 이제 게시는 특히 M365 및 Teams 채널을 통해 에이전트를 배포하는 것을 의미합니다.

전환 중 에이전트 유형

전환 기간 동안 다음 세 가지 유형의 에이전트가 발생할 수 있습니다.

유형 agent.identity 설명
새 에이전트 비null 개체 모델 업데이트 후에 생성됩니다. 고유한 ID 및 청사진이 있습니다. 모든 새로운 기능을 사용할 수 있습니다.
레거시 에이전트 Null 개체 모델 업데이트 전에 생성됩니다. 공유 프로젝트 ID 및 청사진을 사용합니다. 새 에이전트 속성(예: protocol_configuration, agent_endpoint및 agent_card)으로 백필되지만 고유한 에이전트 ID가 없는 한 안정적인 엔드포인트를 통해 Teams/M365에 게시할 수 없습니다.
게시된 에이전트(즉, 에이전트 애플리케이션) 해당 없음(별도의 리소스) 이전 게시 흐름의 레거시 리소스입니다. 에이전트 버전을 가리키는 배포판을 포장합니다.

이 값은 새 에이전트와 레거시 에이전트를 구분합니다. agent.identity.

계속 작동하는 것

  • 기존 에이전트 애플리케이션은 엔드포인트를 통해 트래픽을 계속 제공합니다.
  • 에이전트 애플리케이션을 통해 M365/Teams에 게시된 에이전트는 계속 작동합니다.
  • 프로젝트 엔드포인트는 이전 버전과의 호환성을 위해 계속 사용할 수 있습니다(더 이상 권장 경로는 아니지만).
  • 레거시 에이전트는 Foundry 프로젝트의 개발 및 테스트에 완벽하게 작동합니다.

마이그레이션 경로

경로 1: 새 에이전트(작업이 필요 없음)

개체 모델 업데이트 후 에이전트를 만드는 경우 고유한 ID, 안정적인 엔드포인트 및 모든 새 기능을 사용하여 새 모델을 자동으로 가져옵니다. 마이그레이션이 필요하지 않습니다.

경로 2: 레거시 에이전트 업그레이드

업데이트 전에 만든 레거시 에이전트는 공유 프로젝트 ID를 사용하며 새 모델을 통해 게시할 수 없습니다. 업그레이드하려면 다음을 수행합니다.

  1. 에이전트가 레거시 에이전트인지 확인합니다.

    GET {endpoint}/agents/{agent_name}?api-version=2025-11-15-preview
Authorization: Bearer {{token}}
Foundry-Features: AgentEndpoints=V1Preview

    응답에서 null이면 instance_identity 레거시 에이전트입니다.

  2. 동일한 정의를 사용하여 새 에이전트를 만듭니다.

    참고

    현재 레거시 에이전트를 고유한 ID로 업그레이드할 수 있는 방법은 없습니다. 고유한 ID를 얻으려면 동일한 정의(지침, 도구, 모델 구성)를 사용하여 새 에이전트를 만듭니다. 새 에이전트는 고유한 ID와 안정적인 엔드포인트를 자동으로 받습니다. 향후 업데이트에서 직접 업그레이드 경로가 계획되어 있습니다.

  3. 새 에이전트가 만들어지면 고유한 ID가 있으며 에이전트 엔드포인트를 사용하는 새 게시 환경을 비롯한 모든 새 기능을 사용할 수 있습니다.

경로 3: 기존 에이전트 애플리케이션 마이그레이션

에이전트 애플리케이션이 M365/Teams에 게시되어 있고 새 모델로 마이그레이션하려는 경우 다음 단계를 수행합니다.

  1. 에이전트 애플리케이션 뒤에 있는 에이전트와 동일한 정의를 사용하여 새 에이전트를 만듭니다(지침, 도구, 모델 구성). 새 에이전트는 고유한 ID와 안정적인 엔드포인트를 자동으로 받습니다. 자세한 내용은 경로 2 를 참조하세요.

  2. Foundry 포털에서 Microsoft 365 및 Teams 새 에이전트를 게시합니다. 게시는 Foundry 포털을 통해서만 사용할 수 있습니다. 퍼블릭 게시 API는 없습니다. 단계를 보려면 Microsoft 365 Copilot 에이전트 게시 및 Microsoft Teams를 참조하세요.

  3. 안정적인 새 엔드포인트를 사용하여 M365/Teams에서 새 에이전트가 작동하는지 확인합니다.

  4. 새 에이전트가 작동하는지 확인한 후 이전 에이전트 애플리케이션의 서비스를 해제합니다.

    • 에이전트 애플리케이션 Azure 리소스를 삭제합니다. 리소스를 삭제해도 에이전트 버전은 삭제되지 않습니다.
    • 기존 통합이 계속 작동하려면 이전 애플리케이션 엔드포인트 URL을 참조하는 코드를 업데이트하여 새 에이전트 안정적인 엔드포인트 URL을 사용합니다.

엔드포인트 URL 변경

마이그레이션할 때 이전 엔드포인트 형식을 참조하는 코드 또는 통합을 업데이트합니다.

양상 레거시 엔드포인트 새 엔드포인트
응답 https://{account}.../projects/{project}/applications/{app}/protocols/openai https://{account}.../projects/{project}/agents/{agent}/endpoint/protocols/openai/responses
활동 https://{account}.../projects/{project}/applications/{app}/protocols/activityprotocol https://{account}.../projects/{project}/agents/{agent}/endpoint/protocols/activityprotocol

전환 중에 UX 게시

전환 중에 에이전트 유형에 따라 다른 게시 환경이 표시 될 수 있습니다.

  • 새 에이전트 (agent.identity != null): 안정적인 엔드포인트 선택, 버전 라우팅 및 M365/Teams에 직접 게시하는 새 게시 UX가 표시됩니다.
  • 레거시 에이전트 (agent.identity == null): 레거시 에이전트 애플리케이션 게시 UX가 표시됩니다. 배너는 업그레이드 링크와 함께 새 환경을 사용할 수 있음을 나타낼 수 있습니다.

타임라인 및 사용 중단

단계 상태
사용할 수 있는 새 에이전트 개체 모델 ✅ 사용 가능
레거시 에이전트 애플리케이션은 계속 작동합니다. ✅ 지원
레거시 에이전트 ID 업그레이드 제스처 🔄 곧 출시 예정
에이전트 애플리케이션 사용 중단 발표됨 📅 계획
에이전트 애플리케이션 지원 종료 📅 미정

Faq

즉시 마이그레이션해야 하나요?

아니요. 기존 에이전트 애플리케이션은 계속 작동합니다. 그러나 새 기능(트래픽 분할, 여러 프로토콜, 사용 안 함/사용, A2A)은 새 에이전트 모델에서만 사용할 수 있습니다.

에이전트 애플리케이션의 작동이 중지될까요?

즉시는 아닙니다. 에이전트 애플리케이션은 사전 통지 및 마이그레이션 기간으로 더 이상 사용되지 않습니다. 지원 종료 날짜까지 계속 작동합니다.

동일한 기본 에이전트에 대한 에이전트 애플리케이션과 새 모델 에이전트를 둘 다 사용할 수 있나요?

전환 중에는 그렇습니다. 에이전트 애플리케이션과 새 에이전트 엔드포인트가 공존할 수 있습니다. 그러나 별도의 ID와 엔드포인트가 있는 별도의 리소스입니다.

에이전트 애플리케이션 리소스에 할당된 Azure 역할 기반 액세스 제어(RBAC) 역할은 어떻게 되나요?

에이전트 애플리케이션 리소스의 에이전트 ID에 대한 역할 할당은 에이전트 개체로 전송되지 않습니다. 새 에이전트 엔드포인트의 에이전트 ID에 필요한 역할을 할당해야 합니다. 마찬가지로 최소 권한의 원칙을 고려하고 불필요한 사용 권한을 제거합니다.

클라이언트가 에이전트와 상호 작용할 수 있도록 하는 클라이언트에 대한 역할 할당도 업데이트해야 합니다. 레거시 모델에서 이러한 할당은 에이전트 애플리케이션 리소스로 범위가 지정될 수 있습니다. 새 모델에서 프로젝트 범위에서 적절한 역할을 할당합니다.

내 에이전트는 에이전트 ID로 인증하는 도구를 사용합니다. 어떤 변경 내용이 있나요?

새 모델을 사용하면 에이전트에 생성할 수 있는 고유한 ID가 있으므로 게시 시 ID가 변경되지 않습니다. 그러나 레거시 에이전트에서 마이그레이션하는 경우 에이전트는 공유 프로젝트 ID 및 에이전트 애플리케이션 ID와 다른 새 ID를 가져옵니다. 다운스트림 리소스에 대한 RBAC를 다시 할당해야 합니다.

관련 콘텐츠

  • Last updated on