SharePoint 메타데이터로 문서를 골라 답하는 에이전트 — 토픽 분기 없이

원문: SharePoint Metadata Filtering in Copilot Studio: From Topic Logic to Agent Decisions 게시일: 2026-09-01 (2026-09-02 수정) · 저자: Adi Leibowitz (The Custom Engine, Copilot Studio CAT 블로그)

SharePoint 라이브러리에는 생김새는 비슷한데 적용 대상이 다른 문서가 많아요. 복리후생 정책은 나라마다 다르고, 제품 가이드는 특정 시장에만 해당하고, 어떤 절차는 상태가 Approved일 때만 유효하죠.

메이커들이 “SharePoint 메타데이터로 문서를 걸러서 답하게 해 주세요”라고 요청한 지는 정말 오래됐어요. 원문 표현을 빌리면 “대략 무한 년쯤 걸렸지만, 이제 됐어요”.

예전에는 왜 어려웠나요?

Standard 하네스¹에서는 “사용자 의도 → SharePoint 메타데이터 → 맞는 문서 URL”로 이어지는 간단한 설정 경로가 없었어요.

메이커들은 토픽을 여러 개 만들고, 각 토픽에 범위를 좁힌 생성형 답변 만들기(Create generative answers) 노드를 넣어 비슷하게 흉내 냈어요. 그런데 이 노드가 좁힐 수 있는 건 설정해 둔 소스나 URL까지였지, 라이브러리의 메타데이터가 아니었어요. 그래서 나라·부서·문서 상태가 하나 늘 때마다 관리할 설정도 하나씩 늘었죠.

GitHub Copilot 하네스로 구동되는 에이전트는 이 간극을 메워요. 에이전트가 요청을 해석하고, 메타데이터로 SharePoint 파일을 거르고, 맞는 문서의 URL을 모은 다음, 그 문서들 안에서만 검색해요.

설정은 이게 전부예요

SharePoint 문서 라이브러리에는 작성자, 수정한 날짜 같은 기본 열이 있고, 국가·상태·부서 같은 사용자 지정 열²을 추가할 수도 있어요.

이 라이브러리를 지식 소스로 추가하고 질문하면 끝이에요. 메이커가 따로 설정할 메타데이터 도구는 없어요. 메타데이터가 필요해 보이면 에이전트가 쓸 수 있는 열을 찾아보고, 기록된 값으로 해당 파일을 골라 그 문서 묶음에서 답해요. Standard 하네스처럼 분기마다 토픽을 만들 필요가 없어요.

예를 들어 라이브러리에 Country 열이 있고, 사용자가 “캐나다에서는 육아휴직 혜택이 어떻게 돼요?“라고 묻는다고 해 볼게요. 에이전트는 Country 값이 Canada인 문서를 모두 찾은 다음, 그 파일들 안에서만 육아휴직 정보를 검색해요.

이게 중요한 이유가 있어요. 정책 문서 본문에는 “캐나다”라는 단어가 아예 없을 수도 있어요. 그 정보가 라이브러리 메타데이터에만 들어 있는 거죠. 본문만 검색하면 맞는 문서를 놓치거나, 다른 나라용 정책을 섞어서 답할 수 있어요.

같은 패턴은 이런 메타데이터에도 통해요.

승인 상태, 검토 날짜
부서, 사업부, 대상 독자
제품, 서비스, 시장
문서 유형, 소유자, 마지막 수정 날짜
폴더 위치, 파일 형식

내장 도구 2개, 역할은 따로

GitHub Copilot 하네스 에이전트는 현재 SharePoint 지식용 내장 도구를 두 개 받아요. 도구마다 스키마³가 따로 있어서, 에이전트가 하나만 부를지 둘을 이어서 부를지 스스로 정해요.

도구	주요 입력	돌려주는 것
`sharepoint_metadata_filter`	작성자, 편집자, 날짜, 파일 형식, 폴더, 사용자 지정 열 필터, 포함할 열, 그룹화할 열	맞는 파일 이름과 URL, 열 값, 사용 가능한 열, 실제 일치 개수, 빈 값 개수, 그룹별 합계
`knowledge_search_sharepoint`	필수 `query`, 선택 `search_query`(다시 쓴 검색어), 선택 `scopeUrls`	선택한 SharePoint 범위의 검색 결과(문서 제목, URL, 참조 ID)

메타데이터 필터만 쓰는 경우

“나라별로 문서가 몇 개씩 있어요?” 같은 질문은 파일을 하나하나 열어 검색할 필요가 없어요. 에이전트는 sharepoint_metadata_filter에 이것만 보내요.

{
  "groupByColumn": "Country"
}

그러면 화면에 보이는 몇 줄이 아니라 서버에서 계산한 합계가 돌아와요.

{
  "aggregation": true,
  "groupBy": "Country",
  "totalMatched": 9,
  "blankCount": 6,
  "availableColumns": ["Image Tags", "Country", "Author", "Modified By"],
  "groups": [
    { "value": "US", "count": 2 },
    { "value": "EU", "count": 1 }
  ],
  "backend": "sharepoint_rest"
}

반대로 메타데이터가 필요 없는 일반 내용 질문이면, 에이전트는 knowledge_search_sharepoint만 불러서 설정된 SharePoint 지식 소스 전체를 검색해요.

둘을 이어 쓰는 경우

재미있는 건 체이닝이에요. “Contoso는 미국에서 어떤 직원 복리후생을 제공해요?“라는 질문을 따라가 볼게요.

1단계. 에이전트가 메타데이터 필터에 미국 파일을 요청하고, 모든 열을 달라고 해요.

{
  "columnFilter": {
    "column": "Country",
    "operator": "eq",
    "value": "US"
  },
  "includeColumns": ["*"]
}

2단계. 맞는 파일 두 개(Contoso Benefits.docx, Contoso HR policies.docx)가 작성자·수정자·수정 시각·열 값과 함께 돌아와요. 응답에는 이런 안내 문구도 들어 있어요. “개수는 totalMatched로 보고하고, 이 파일 URL들을 knowledge_search_sharepoint의 scopeUrls에 넘겨 내용을 검색하라.”

3단계. 에이전트가 받은 URL을 검색 도구에 넘겨요.

{
  "search_query": "What employee benefits does Contoso offer in the US?",
  "query": "What employee benefits do we offer in the US?",
  "scopeUrls": [
    "https://pplatform.sharepoint.com/Shared%20Documents/Contoso%20HR%20Documents/Contoso%20Benefits.docx",
    "https://pplatform.sharepoint.com/Shared%20Documents/Contoso%20HR%20Documents/Contoso%20HR%20policies.docx"
  ]
}

4단계. 검색은 넘겨받은 두 문서 안에서만 일어나고, 결과도 그 두 문서로 돌아와요.

정리하면 에이전트는 매번 체이닝하지 않아요. 개수·집계 같은 목록 질문엔 메타데이터 필터만, 일반 내용 질문엔 검색만, 메타데이터가 문서 범위를 정하는 질문엔 둘 다 써요.

안내는 하되, 모든 결정을 스크립트로 짜지는 마세요

CAT의 Knowledge Source Router 스킬은 일부러 엄격하게 만든 국가별 라우팅 절차예요. 라이브러리 메타데이터를 살펴보고, 맞는 파일을 전부 가져오고, 그 URL 안에서만 검색하고, 국가가 지정되지 않았거나 빠진 문서를 보고하라고 에이전트에게 지시해요.

이 정도 안내는 절차가 매번 똑같아야 하고 점검하기 쉬워야 할 때 유용해요. 하지만 모든 에이전트에 필요한 건 아니에요. 에이전트 지침을 명확하게 쓰고 지식 소스 설명을 잘 달아 두면, 메타데이터 필터링이 언제 필요한지, 검색과 어떻게 엮을지를 에이전트가 판단하게 둘 수도 있어요.

원문의 권장은 이거예요. 안정적인 결과가 나오는 가장 가벼운 안내부터 시작하고, 테스트에서 필요하다고 드러날 때만 단계를 엄격하게 추가하세요. 반복해서 쓸 안내를 묶어 두고 싶다면 Skill로 만들면 돼요.

꼭 알아둘 3가지

내장 도구는 공개 API가 아니에요. 두 도구는 내부 구현이라 이름·매개변수·동작이 예고 없이 바뀔 수 있어요. 특정 도구 계약에 기대지 말고, 지원되는 Copilot Studio 기능을 기준으로 설계하세요.
권한을 대신하지 않아요. 메타데이터 필터링은 답변에 쓸 문서 범위를 좁힐 뿐이에요. 사용자가 못 읽는 문서에 접근 권한을 주지 않고, 로그인한 사용자 기준의 SharePoint 권한 트리밍⁴은 그대로 적용돼요.
메타데이터 품질이 전부예요. 에이전트는 라이브러리에 기록된 값을 써야 해요. 파일 이름이나 본문을 보고 국가·상태·소유자를 짐작하게 두면 안 돼요.

이걸로 할 수 있게 되는 것

수명 주기를 아는 답변: 라이브러리에 상태가 기록돼 있다면, 승인된 최신 문서를 우선하고 초안이나 폐기된 문서는 피할 수 있어요.
대상별 안내: 사이트 하나에 여러 부서·제품·시장용 자료를 두고도, 대상마다 지식 소스를 따로 만들 필요가 없어요.
라이브러리 현황 질문: “소유자별로 정책이 몇 개예요?”, “Country 값이 비어 있는 파일은 뭐예요?” 같은 질문에 문서 본문을 추측하지 않고 메타데이터로 답해요.

정리

핵심은 설정할 도구가 하나 더 생긴 게 아니에요. “어떤 문서가 해당되는가”와 “그 문서에 뭐라고 쓰여 있는가”를 분리하는 더 쉬운 방법이 생긴 거예요.

할 일은 SharePoint 라이브러리를 지식 소스로 추가하는 것뿐이에요. GitHub Copilot 하네스 에이전트에서 동작해요.
라이브러리에 국가·상태·부서 같은 열을 제대로 채워 두세요. 답변 품질이 여기서 갈려요.
안내는 가볍게 시작하고, 테스트 결과를 보고 필요할 때만 엄격한 절차(스킬 등)를 더하세요.

어휘 주석

하네스(harness): 에이전트를 실제로 구동하는 실행 엔진. Copilot Studio에는 기존의 Standard 하네스와 새로운 GitHub Copilot 하네스가 있고, 이 글의 메타데이터 필터링은 GitHub Copilot 하네스 에이전트에서 동작해요.
사용자 지정 열(custom column): SharePoint 문서 라이브러리에 직접 추가하는 속성 열. 문서마다 국가·상태·부서 같은 값을 붙여 분류할 수 있어요.
스키마(schema): 도구가 어떤 입력을 받고 어떤 형태로 결과를 돌려주는지 정해 둔 명세. 에이전트는 이걸 보고 도구를 언제, 어떻게 부를지 판단해요.
권한 트리밍(permission trimming): 검색이나 답변 결과에서 현재 사용자가 볼 권한이 없는 항목을 자동으로 빼는 동작.