OpenAPI 지정 도구에서 Foundry 에이전트 서비스를 사용하는 방법

이제 OpenAPI 3.0 지정된 도구를 사용하여 Azure AI 에이전트를 외부 API에 연결하여 다양한 애플리케이션과 확장 가능한 상호 운용성을 가능하게 할 수 있습니다. 인증에 관리 ID(Microsoft Entra ID)를 사용하면 사용자 지정 도구를 사용하여 액세스 및 연결을 안전하게 인증할 수 있습니다. 이 방법은 기존 인프라 또는 웹 서비스와 통합하는 데 적합합니다.

OpenAPI 지정 도구는 에이전트의 기능과 효율성을 향상시키는 표준화되고 자동화되고 확장 가능한 API 통합을 제공하여 함수 호출 환경을 향상시킵니다. OpenAPI 사양은 HTTP API를 설명하는 공식 표준을 제공합니다. 이 표준은 API의 작동 방식, API 시퀀스가 함께 작동하는 방식을 이해하는 데 도움이 되며 클라이언트 코드 생성, 테스트 만들기, 디자인 표준 적용 등을 지원합니다. 현재 OpenAPI 3.0 명시된 도구는 세 가지 인증 유형인 anonymous, API key, 및 managed identity를 지원합니다.

사용량 지원

필수 조건

1. 빠른 시작에서 필수 구성 요소 및 설정 단계를 완료해야 합니다.
2. OpenAPI 사양에서 다음 요구 사항을 확인합니다.
   1. OpenAPI 사양에는 필요하지 않지만, OpenAPI 도구와 함께 작동하려면 각 함수에 operationId가 필요합니다.
   2. operationId에는 문자와 -, _만 포함되어야 합니다. 이 요구 사항을 충족하도록 수정할 수 있습니다. 설명이 포함된 이름을 사용하여 모델에서 사용할 함수를 효율적으로 결정할 수 있습니다.

API 키로 인증

API 키 인증을 사용하면 API 키 또는 전달자 토큰과 같은 다양한 방법을 통해 OpenAPI 사양을 인증할 수 있습니다. 각 OpenAPI 사양은 하나의 API 키 보안 스키마만 지원합니다. 여러 보안 스키마가 필요한 경우 여러 OpenAPI 사양 도구를 만듭니다.

1. OpenAPI 사양 보안 스키마를 업데이트합니다. 섹션과 securitySchemes 하나의 형식 apiKey구성표가 있습니다. 다음은 그 예입니다.

    "securitySchemes": {
        "apiKeyHeader": {
                "type": "apiKey",
                "name": "x-api-key",
                "in": "header"
            }
    }
   

   일반적으로 연결에서 이름이 name인 항목에 해당하는 key 필드만 업데이트하면 됩니다. 보안 체계에 여러 스키마가 포함된 경우 그 중 하나만 유지합니다.

2. 섹션을 포함하도록 OpenAPI 사양을 업데이트합니다.security

   "security": [
        {  
        "apiKeyHeader": []  
        }  
    ]
   

3. 이 문서의 뒷부분에서 설명한 대로 API 키가 저장되고 연결을 통해 전달되기 때문에 API 키가 필요한 OpenAPI 사양에서 매개 변수를 제거합니다.

4. API 키를 저장할 custom keys 연결을 만듭니다.

   1. Microsoft Foundry 포털로 이동하여 왼쪽 탐색 창에서 관리 센터를 선택합니다.

      

   2. 왼쪽 탐색 창의 AI 프로젝트에서 연결된 리소스 를 선택합니다.

   3. 설정 페이지에서 + 새 연결을 선택합니다.

      비고

      나중에 API 키를 다시 생성하는 경우 새 키로 연결을 업데이트해야 합니다.

      

   4. 다른 리소스 종류에서 사용자 지정 키를 선택합니다.

      

   5. 다음 정보를 입력합니다.

      • key: name 보안 체계의 필드입니다. 이 예제에서는 x-api-key입니다.

        "securitySchemes": {
            "apiKeyHeader": {
                    "type": "apiKey",
                    "name": "x-api-key",
                    "in": "header"
                }
        }
        

      • 값: YOUR_API_KEY

      • 연결 이름: YOUR_CONNECTION_NAME(아래 샘플 코드에서 이 연결 이름을 사용합니다.)

      • 액세스: 이 프로젝트만 선택하거나 모든 프로젝트에 공유할 수 있습니다. 아래 샘플 코드에서 연결 문자열을 입력한 프로젝트에 이 연결에 대한 액세스 권한이 있는지 확인합니다.

5. 연결을 만든 후 SDK 또는 REST API를 통해 사용합니다. 이 문서의 맨 위에 있는 탭을 사용하여 코드 예제를 확인합니다.

관리 ID를 사용하여 인증(Microsoft Entra ID)

Microsoft Entra ID 는 직원이 외부 리소스에 액세스하는 데 사용할 수 있는 클라우드 기반 ID 및 액세스 관리 서비스입니다. Microsoft Entra ID를 사용하면 API 키를 사용할 필요 없이 API를 인증할 때 보안을 더 추가할 수 있습니다. 관리 ID 인증을 설정한 후 에이전트에서 사용하는 Foundry 도구가 인증을 처리합니다.

관리 ID 인증을 구성할 때 대상 그룹 값을 제공해야 합니다. 대상 그룹은 관리 ID가 액세스할 수 있는 API 또는 서비스를 식별하는 OAuth2 리소스 식별자(범위 또는 애플리케이션 ID URI라고도 함)입니다.

일반적인 대상 그룹 값:

• Foundry 도구(이전의 Azure AI 서비스 또는 Cognitive Services): https://cognitiveservices.azure.com/
• Azure Resource Manager API: https://management.azure.com/
• Microsoft Graph: https://graph.microsoft.com/
• Microsoft Entra ID에 등록된 사용자 지정 API: API의 앱 등록에 있는 애플리케이션 ID URI 사용

관리 ID를 사용하여 인증을 설정하려면 다음을 수행합니다.

1. Foundry 리소스에 시스템 할당 관리 ID가 사용하도록 설정되어 있는지 확인합니다.

   

2. OpenAPI 사양을 통해 연결하려는 서비스에 대한 리소스를 만듭니다.

3. 리소스에 대한 적절한 액세스를 할당합니다.

   1. 리소스에 대한 액세스 제어 를 선택합니다.

   2. 추가를 선택한 다음 화면 맨 위에 역할 할당을 추가합니다.

      

   3. 필요한 적절한 역할 할당을 선택합니다. 일반적으로 READER 역할 이상이 필요합니다. 그런 후 다음을 선택합니다.

   4. 관리 ID를선택한 다음 멤버를 선택합니다.

   5. 관리 ID 드롭다운 메뉴에서 Foundry 도구를 검색한 다음 에이전트의 Foundry 도구를 선택합니다.

   6. 완료를 선택합니다.

4. 설치를 완료한 후 Foundry 포털, SDK 또는 REST API를 통해 도구를 사용할 수 있습니다. 이 문서의 맨 위에 있는 탭을 사용하여 코드 샘플을 확인합니다.