사용자를 대신하여 Fabric 데이터를 쿼리하는 Foundry 에이전트 구축하기

지역 영업 관리자와 영업 사원이 동일한 Foundry 에이전트에게 정확히 같은 질문을 합니다: "지역별 매출을 보여줘." 관리자는 모든 지역을 볼 수 있습니다. 반면, 영업 사원은 자신의 지역만 볼 수 있습니다. 동일한 에이전트, 동일한 프롬프트, 내부적으로는 동일한 도구 호출이지만, 완전히 다른 두 가지 답변이 나옵니다. 그리고 이 모든 것을 가능하게 하기 위해 if user.role == "manager" 같은 코드를 단 한 줄도 작성하지 않았습니다.

이것이 Microsoft Fabric 데이터 에이전트를 Microsoft Foundry에 도구로 연결하는 내용입니다. 이 통합은 단순히 에이전트에게 새로운 데이터 소스를 제공하는 것이 아니라, 이미 누가 질문하고 있는지 아는 데이터 소스를 에이전트에게 제공하는 것입니다. Fabric은 수년 동안 Power BI 시맨틱 모델에 행 수준 보안(RLS)과 열 수준 보안(CLS)을 구축해 왔습니다. Foundry는 지난 1년간 대화 중간에 도구를 호출할 수 있는 에이전트를 구축해 왔습니다. 이 둘을 연결하는 것이 바로 On-Behalf-Of (OBO) ID 패스스루이며, 한 번 올바르게 설정하면 에이전트를 통해 데이터 유출에 대해 걱정할 필요가 없습니다. 왜냐하면 보안 적용 자체가 애초에 Fabric을 벗어나지 않았기 때문입니다.

이것은 실습 기반 구축 가이드입니다. 저희는 Fabric 데이터 에이전트를 게시하고, 이를 Foundry 프로젝트에 연결하며, fabric_dataagent_preview 도구 유형을 사용하여 도구로 첨부한 다음, 두 가지 다른 로그인 사용자로서 실행하여 RLS 경계가 실제로 유지되는지 증명할 것입니다.

사고 모델 (The mental model)

코드를 만지기 전에, 사람들이 혼동하는 두 가지를 분리하는 것이 도움이 됩니다: Fabric 데이터 에이전트와 이를 호출하는 Foundry 도구입니다.

<strong>Fabric 데이터 에이전트</strong>는 Fabric 네이티브 객체입니다. 이를 Fabric 작업 공간 내에서 구축하고, 하나 이상의 데이터 소스(웨어하우스, 레이크하우스, KQL 데이터베이스 또는 Power BI 시맨틱 모델)를 지정한 다음, 안정적인 엔드포인트를 갖도록 게시합니다. 이 에이전트는 이미 자연어를 해당 소스에 대한 쿼리로 변환하는 방법을 알고 있으며, 기반이 되는 시맨틱 모델에 정의된 모든 RLS(행 수준 보안) 또는 CLS(열 수준 보안) 규칙을 준수합니다. 이 부분은 Foundry와 독립적으로 존재합니다. 내일 Fabric 채팅 UI에서 이를 사용하고 에이전트 프레임워크를 전혀 건드리지 않을 수도 있습니다.

<strong>Foundry 도구</strong>는 Foundry 에이전트가 대화 중간에 해당 게시된 Fabric 데이터 에이전트를 호출할 수 있게 해주는 얇고 타입이 지정된(typed) 래퍼입니다. Foundry는 보안 로직을 재구현하지 않습니다. 대신, 에이전트를 사용하는 사람의 신원을 인증하고 그 신원 정보를 Fabric에 전달하며, Fabric가 이미 하는 일을 하도록 합니다. 즉, 해당 신원이 볼 수 있도록 허용된 행과 열만을 사용하여 질문에 답변하게 합니다.

이러한 권한 위임(handoff) 자체가 전체 가치 제안입니다. 만약 검색 단계에서 문서 수준의 권한을 조용히 무시하는 RAG 파이프라인을 구축해 본 적이 있다면, 이것이 왜 중요한지 이미 알고 계실 겁니다.

사전 요구 사항

아래 코드가 작동하려면 몇 가지 조건이 충족되어야 합니다:

• 유료 F2 이상 용량의 Fabric 워크스페이스 또는 Fabric이 활성화된 Power BI Premium P1 이상
• 읽기 액세스 권한을 가진 데이터 소스가 최소 하나 포함된, 게시된 Fabric 데이터 에이전트
• Fabric 데이터 에이전트와 Foundry 프로젝트가 동일 테넌트에 있고, 동일 계정으로 로그인되어 있어야 함
• Fabric 데이터 에이전트 및 기본 데이터 소스가 동일 리전의 용량에 위치해야 함
• 최소한 사용자 본인과 에이전트를 사용할 모든 사람에게 Foundry 프로젝트에서 Foundry User (또는 AI Developer) RBAC 역할 부여
• 사용자 ID 인증만 가능. Fabric 데이터 에이전트 도구에는 서비스 주체(Service principal) 인증이 명시적으로 지원되지 않습니다. 만약 사용자의 에이전트가 일반적으로 관리 ID 아래에서 헤드리스(headless)로 실행된다 하더라도, 이 도구 호출 패턴은 깨지므로 실제 로그인한 사용자(user in the loop)가 필요합니다.

마지막 요점은 사람들이 가장 많이 헷갈리는 부분이므로, 무언가를 구축하기 전에 반복할 가치가 있습니다. 이 도구는 대화형으로 사용자와 상호작용하는 에이전트를 위해 설계되었습니다. 백그라운드 작업(background job)을 위한 도구가 아닙니다.

1단계: Fabric 데이터 에이전트 게시하기

Fabric 워크스페이스에서 새 데이터 에이전트 항목을 만들고, 이를 시맨틱 모델 또는 웨어하우스에 연결하며, 이 에이전트가 어떤 용도로 좋은지 지침을 제공하고, Fabric 채팅 창에서 올바르게 답변할 때까지 테스트합니다. 그런 다음 게시합니다.

게시되면 엔드포인트 URL을 엽니다. 다음과 같습니다:

이 URL에서 workspace_id와 artifact_id를 모두 복사해야 합니다. 이 두 가지는 다음 단계에서 모두 필요하며, REST API를 깊이 파고들지 않고 찾을 수 있는 유일한 방법입니다.

2단계: Foundry에 연결 만들기

Foundry는 해당 두 ID를 저장하는 연결 객체가 필요합니다. 그래야 Fabric 도구가 어떤 데이터 에이전트를 호출해야 하는지 알 수 있습니다. 포털 또는 REST API로 이 작업을 수행할 수 있습니다. 첫 실행에는 포털 경로가 더 간단합니다:

1. Foundry 프로젝트에서 **빌드 및 사용자 정의(Build and customize) > 에이전트(Agents)**로 이동합니다.
2. 기존 에이전트를 열거나 새 에이전트를 시작합니다.
3. 지식 소스(knowledge source)를 추가하고 Microsoft Fabric을 선택합니다.
4. 새 연결을 생성하고, workspace_id와 artifact_id를 사용자 지정 키로 붙여넣은 후 **비밀(Is secret)**에 체크합니다.
5. 연결 이름을 지정하고 이 프로젝트에만 국한할지 아니면 계정 전체에서 공유할지 선택합니다.

스크립트로 처리하는 것을 선호한다면, 동일한 연결을 관리 평면(management plane)에 직접 생성할 수 있습니다:

PUT https://management.azure.com/subscriptions/<sub-id>/resourceGroups/<rg>/providers/Microsoft.CognitiveServices/accounts/<foundry-account>/projects/<project>/connections/<connection-name>?api-version=2025-04-01-preview
Authorization: Bearer <token>
Content-Type: application/json
...

이 연결 객체에는 사용자 신원(user identity)을 담는 것이 없습니다. 이는 순전히 라우팅 정보이며, Foundry가 올바른 Fabric 데이터 에이전트를 가리키도록 하는 역할을 합니다. 실제 사용자의 신원은 호출 시점에 자동으로 계층화됩니다.

3단계: Fabric 도구를 Foundry 에이전트에 연결하기

연결을 설정했으니, 이를 에이전트에 첨부하는 것은 SDK에서 몇 줄이면 충분합니다. 흐름은 다른 모든 Foundry 도구와 유사합니다. 즉, 연결 ID를 해석(resolve)하고, 이를 타입 지정된 도구 정의(typed tool definition)에 전달한 다음, 이 도구를 에이전트 정의에 넘겨주는 방식입니다.

import os
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
...

`tool_choice=

에이전트를 호출하는 것은 다른 모든 Foundry 에이전트와 마찬가지로 Responses API를 사용합니다:

client = project.get_openai_client()

response = client.responses.create(
...

이 스크립트를 실행할 때는 기본 의미 모델(semantic model)의 모든 리전에 대한 전체 접근 권한을 가진 사용자 자격으로 인증합니다. 그러면 완벽하게 분해된 결과를 얻게 됩니다. 이제 정확히 같은 스크립트, 같은 에이전트, 같은 질문을 사용하되, 단일 리전에 RLS(Row-Level Security)로 범위가 제한된 사용자 자격으로 인증하여 실행해 보세요. 도구 호출(tool call)은 Foundry 측에서 동일하게 보입니다. 하지만 반환되는 답변에는 해당 사용자만이 접근 가능한 리전만 포함되어 있습니다.

에이전트의 지침, 도구 정의, 또는 프롬프트 어디에도 역할이나 리전에 대한 언급은 없습니다. 제한 사항은 코드 내에서 전혀 구현되지 않았습니다. 이는 Fabric에 의해 강제되며, 의미 모델에 이미 존재하는 RLS나 CLS(Column-Level Security) 규칙을 사용합니다. 이 규칙들은 해당 사용자가 Power BI에서 보고서를 직접 열었을 때 적용될 규칙들과 동일합니다.

전체 과정에서 단일 호출의 형태는 다음과 같습니다:

더 큰 그림에서의 위치

단일 요청을 넘어 시야를 넓히면 흥미로운 부분은 변하지 않는 것들입니다. Foundry 에이전트는 누가 사용하든 동일한 에이전트이며, 도구 정의 또한 같습니다. 요청마다 달라지는 것은 호출이 Fabric에 도달하기 전에 Foundry와 연결된 Entra 앱 사이에서 자동으로 발생하는 토큰 교환(token exchange)입니다.

[

이것이 바로 아키텍처적 이점입니다. 에이전트를 한 번만 구축하면 됩니다. 역할별로 별도의 에이전트를 만들 필요도 없고, 애플리케이션 내부에 Power BI에 설정된 내용과 동기화되어야 하는 권한 테이블을 유지할 필요도 없습니다. 권한 모델은 정확히 한 곳에 존재하며, 그곳은 데이터 팀이 이미 관리하고 있는 장소이기도 합니다.

프로덕션 고려 사항

데모 단계를 넘어 가기 전에 알아두면 좋을 몇 가지 사항들이 있습니다.

Foundry 에이전트당 Fabric 데이터 에이전트를 하나씩. 현재 도구는 하나의 Fabric 데이터 에이전트만 지식 소스로 연결하는 것을 지원합니다. 여러 개의 Fabric 데이터 에이전트에 기반해야 한다면, 단일 에이전트에 여러 Fabric 도구를 연결하는 것이 아니라, 여러 Foundry 에이전트를 사용하거나 그 앞에 오케스트레이션 레이어를 구축해야 합니다.

서비스 주체(Service principals)는 절대 안 됩니다. 파이프라인의 어떤 부분이 관리자 ID(managed identity) 하에, 실제 사용자 개입 없이 무인으로 실행된다면 이 도구를 사용할 수 없습니다. 무인 경로를 구성할 때는 기본 데이터 소스에 직접 연결하고, Fabric 데이터 에이전트 도구는 상호 작용적이고 사용자가 존재하는 세션에만 예약해야 합니다.

지역 및 테넌트 경계가 권고 사항이 아닌 강제됩니다. Fabric 데이터 에이전트, 그 기반 데이터 소스, 그리고 Foundry 프로젝트 모두 테넌트와 지역에서 일치해야 합니다. 만약 다중 지역 배포를 진행한다면, 에이전트 아키텍처를 계획하기 전에 Fabric 용량 배치(capacity placement)를 먼저 계획해야 합니다.

규정 준수 경계 이동. Microsoft는 Fabric 데이터 에이전트가 Foundry를 통해 사용되는 경우, 응답이 Fabric의 규정 준수 경계를 벗어나 Foundry 자체 약관에 따라 처리될 수 있음을 명확히 밝히고 있습니다. 만약 귀하의 데이터가 특정 거주지 또는 규정 준수 요구 사항을 가지고 있다면, 프로덕션 트래픽을 위해 연결하기 전에 해당 문서 섹션을 주의 깊게 읽어보십시오.

관리자 계정이 아닌 실제 RLS로 테스트하세요. 자신의 개발자 계정으로 모든 것을 구축하고 데모하는 것이 유혹적이지만, 이 계정은 보통 광범위한 접근 권한을 가지고 있습니다. 이 통합의 전체 가치는 적절하게 제한된 계정으로 테스트하기 전까지는 보이지 않습니다. 통합이 완료되었다고 판단하기 전에 그 시간을 할애하세요.

이것이 의미하는 바

Fabric 데이터 에이전트를 Foundry 에이전트에 연결하는 코드는 실제로 매우 작습니다. 도구 정의, 연결 ID, 몇 줄의 코드만 필요합니다. 진지하게 받아들여야 할 부분은 이 작은 코드 조각이 기반하고 있는 모든 것입니다. Fabric 내부의 수년간 축적된 RLS(행 수준 보안) 및 CLS(열 수준 보안) 적용, 에이전트가 권한 테이블을 보거나 저장할 필요가 없게 만드는 ID 패스스루 모델, 그리고 질문하는 사람이 이미 볼 수 있도록 허용된 것만 항상 보장한다는 것입니다.

조직이 Power BI나 Fabric을 통해 이미 관리하고 있는 데이터 위에 내부 에이전트를 구축하는 경우, 이는 일반적인 검색 도구 위에 자체 접근 제어 계층을 구축하고 유지하는 것보다 훨씬 적은 작업일 가능성이 높습니다. 데이터 에이전트를 게시하고 연결을 구성한 다음, Fabric이 기존에 하던 작업을 계속하도록 내버려 두세요.

참고 자료

• Foundry 에이전트와 함께 Microsoft Fabric 데이터 에이전트 사용하기
• Microsoft Foundry에서 데이터 에이전트 사용하기 (미리 보기)
• Fabric 데이터 에이전트 시나리오 (미리 보기)
• 프로젝트에 새 연결 추가하기
• Fabric에서 AI를 위한 크로스 지리 처리 및 저장