---
title: SharePoint 메타데이터로 문서를 골라 답하는 에이전트 — 토픽 분기 없이
description: GitHub Copilot 하네스 에이전트는 SharePoint 라이브러리의 열(Country·상태·부서 등) 값으로 해당 문서만 골라 그 안에서 검색해요. 내장 도구 2개의 역할과 체이닝 흐름, 주의할 점을 정리했어요.
date: 2026-10-01
tags: [Copilot Studio, SharePoint, 메타데이터 필터링, 지식 소스, GitHub Copilot 하네스, Power Platform]
cards:
- /cards/copilot-studio-sharepoint-metadata-filter/card-01.png
- /cards/copilot-studio-sharepoint-metadata-filter/card-02.png
- /cards/copilot-studio-sharepoint-metadata-filter/card-03.png
- /cards/copilot-studio-sharepoint-metadata-filter/card-04.png
- /cards/copilot-studio-sharepoint-metadata-filter/card-05.png
- /cards/copilot-studio-sharepoint-metadata-filter/card-06.png
- /cards/copilot-studio-sharepoint-metadata-filter/card-07.png
author: Lissa
source: https://interlinear.work/notes/copilot-studio-sharepoint-metadata-filter/
---
> **원문:** [SharePoint Metadata Filtering in Copilot Studio: From Topic Logic to Agent Decisions](https://microsoft.github.io/mcscatblog/posts/sharepoint-metadata-filtering/)
> **게시일:** 2026-09-01 (2026-09-02 수정) · **저자:** Adi Leibowitz (The Custom Engine, Copilot Studio CAT 블로그)
SharePoint 라이브러리에는 생김새는 비슷한데 적용 대상이 다른 문서가 많아요. 복리후생 정책은 나라마다 다르고, 제품 가이드는 특정 시장에만 해당하고, 어떤 절차는 상태가 **Approved**일 때만 유효하죠.
메이커들이 "SharePoint 메타데이터로 문서를 걸러서 답하게 해 주세요"라고 요청한 지는 정말 오래됐어요. 원문 표현을 빌리면 "대략 무한 년쯤 걸렸지만, 이제 됐어요".
## 예전에는 왜 어려웠나요?
Standard 하네스1에서는 "사용자 의도 → SharePoint 메타데이터 → 맞는 문서 URL"로 이어지는 간단한 설정 경로가 없었어요.
메이커들은 토픽을 여러 개 만들고, 각 토픽에 범위를 좁힌 **생성형 답변 만들기(Create generative answers)** 노드를 넣어 비슷하게 흉내 냈어요. 그런데 이 노드가 좁힐 수 있는 건 설정해 둔 소스나 URL까지였지, 라이브러리의 메타데이터가 아니었어요. 그래서 나라·부서·문서 상태가 하나 늘 때마다 관리할 설정도 하나씩 늘었죠.
GitHub Copilot 하네스로 구동되는 에이전트는 이 간극을 메워요. 에이전트가 요청을 해석하고, 메타데이터로 SharePoint 파일을 거르고, 맞는 문서의 URL을 모은 다음, **그 문서들 안에서만** 검색해요.
## 설정은 이게 전부예요
SharePoint 문서 라이브러리에는 작성자, 수정한 날짜 같은 기본 열이 있고, 국가·상태·부서 같은 사용자 지정 열2을 추가할 수도 있어요.
이 라이브러리를 **지식 소스로 추가**하고 질문하면 끝이에요. 메이커가 따로 설정할 메타데이터 도구는 없어요. 메타데이터가 필요해 보이면 에이전트가 쓸 수 있는 열을 찾아보고, 기록된 값으로 해당 파일을 골라 그 문서 묶음에서 답해요. Standard 하네스처럼 분기마다 토픽을 만들 필요가 없어요.
예를 들어 라이브러리에 `Country` 열이 있고, 사용자가 "캐나다에서는 육아휴직 혜택이 어떻게 돼요?"라고 묻는다고 해 볼게요. 에이전트는 `Country` 값이 Canada인 문서를 모두 찾은 다음, 그 파일들 안에서만 육아휴직 정보를 검색해요.
이게 중요한 이유가 있어요. 정책 문서 본문에는 "캐나다"라는 단어가 아예 없을 수도 있어요. 그 정보가 라이브러리 메타데이터에만 들어 있는 거죠. 본문만 검색하면 맞는 문서를 놓치거나, 다른 나라용 정책을 섞어서 답할 수 있어요.
같은 패턴은 이런 메타데이터에도 통해요.
- 승인 상태, 검토 날짜
- 부서, 사업부, 대상 독자
- 제품, 서비스, 시장
- 문서 유형, 소유자, 마지막 수정 날짜
- 폴더 위치, 파일 형식
## 내장 도구 2개, 역할은 따로
GitHub Copilot 하네스 에이전트는 현재 SharePoint 지식용 내장 도구를 두 개 받아요. 도구마다 스키마3가 따로 있어서, 에이전트가 하나만 부를지 둘을 이어서 부를지 스스로 정해요.
| 도구 | 주요 입력 | 돌려주는 것 |
|---|---|---|
| `sharepoint_metadata_filter` | 작성자, 편집자, 날짜, 파일 형식, 폴더, 사용자 지정 열 필터, 포함할 열, 그룹화할 열 | 맞는 파일 이름과 URL, 열 값, 사용 가능한 열, 실제 일치 개수, 빈 값 개수, 그룹별 합계 |
| `knowledge_search_sharepoint` | 필수 `query`, 선택 `search_query`(다시 쓴 검색어), 선택 `scopeUrls` | 선택한 SharePoint 범위의 검색 결과(문서 제목, URL, 참조 ID) |
### 메타데이터 필터만 쓰는 경우
"나라별로 문서가 몇 개씩 있어요?" 같은 질문은 파일을 하나하나 열어 검색할 필요가 없어요. 에이전트는 `sharepoint_metadata_filter`에 이것만 보내요.
```json
{
"groupByColumn": "Country"
}
```
그러면 화면에 보이는 몇 줄이 아니라 **서버에서 계산한 합계**가 돌아와요.
```json
{
"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단계.** 에이전트가 메타데이터 필터에 미국 파일을 요청하고, 모든 열을 달라고 해요.
```json
{
"columnFilter": {
"column": "Country",
"operator": "eq",
"value": "US"
},
"includeColumns": ["*"]
}
```
**2단계.** 맞는 파일 두 개(`Contoso Benefits.docx`, `Contoso HR policies.docx`)가 작성자·수정자·수정 시각·열 값과 함께 돌아와요. 응답에는 이런 안내 문구도 들어 있어요. "개수는 `totalMatched`로 보고하고, 이 파일 URL들을 `knowledge_search_sharepoint`의 `scopeUrls`에 넘겨 내용을 검색하라."
**3단계.** 에이전트가 받은 URL을 검색 도구에 넘겨요.
```json
{
"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 스킬](https://microsoft.github.io/cat-agent-skills/skills/knowledge-source-router/)은 일부러 엄격하게 만든 국가별 라우팅 절차예요. 라이브러리 메타데이터를 살펴보고, 맞는 파일을 전부 가져오고, 그 URL 안에서만 검색하고, 국가가 지정되지 않았거나 빠진 문서를 보고하라고 에이전트에게 지시해요.
이 정도 안내는 절차가 매번 똑같아야 하고 점검하기 쉬워야 할 때 유용해요. 하지만 모든 에이전트에 필요한 건 아니에요. 에이전트 지침을 명확하게 쓰고 지식 소스 설명을 잘 달아 두면, 메타데이터 필터링이 언제 필요한지, 검색과 어떻게 엮을지를 에이전트가 판단하게 둘 수도 있어요.
원문의 권장은 이거예요. **안정적인 결과가 나오는 가장 가벼운 안내부터 시작하고, 테스트에서 필요하다고 드러날 때만 단계를 엄격하게 추가하세요.** 반복해서 쓸 안내를 묶어 두고 싶다면 Skill로 만들면 돼요.
## 꼭 알아둘 3가지
- **내장 도구는 공개 API가 아니에요.** 두 도구는 내부 구현이라 이름·매개변수·동작이 예고 없이 바뀔 수 있어요. 특정 도구 계약에 기대지 말고, 지원되는 Copilot Studio 기능을 기준으로 설계하세요.
- **권한을 대신하지 않아요.** 메타데이터 필터링은 답변에 쓸 문서 범위를 좁힐 뿐이에요. 사용자가 못 읽는 문서에 접근 권한을 주지 않고, 로그인한 사용자 기준의 SharePoint 권한 트리밍4은 그대로 적용돼요.
- **메타데이터 품질이 전부예요.** 에이전트는 라이브러리에 기록된 값을 써야 해요. 파일 이름이나 본문을 보고 국가·상태·소유자를 짐작하게 두면 안 돼요.
## 이걸로 할 수 있게 되는 것
- **수명 주기를 아는 답변:** 라이브러리에 상태가 기록돼 있다면, 승인된 최신 문서를 우선하고 초안이나 폐기된 문서는 피할 수 있어요.
- **대상별 안내:** 사이트 하나에 여러 부서·제품·시장용 자료를 두고도, 대상마다 지식 소스를 따로 만들 필요가 없어요.
- **라이브러리 현황 질문:** "소유자별로 정책이 몇 개예요?", "Country 값이 비어 있는 파일은 뭐예요?" 같은 질문에 문서 본문을 추측하지 않고 메타데이터로 답해요.
## 정리
핵심은 설정할 도구가 하나 더 생긴 게 아니에요. **"어떤 문서가 해당되는가"와 "그 문서에 뭐라고 쓰여 있는가"를 분리**하는 더 쉬운 방법이 생긴 거예요.
- 할 일은 SharePoint 라이브러리를 지식 소스로 추가하는 것뿐이에요. GitHub Copilot 하네스 에이전트에서 동작해요.
- 라이브러리에 국가·상태·부서 같은 열을 제대로 채워 두세요. 답변 품질이 여기서 갈려요.
- 안내는 가볍게 시작하고, 테스트 결과를 보고 필요할 때만 엄격한 절차(스킬 등)를 더하세요.
---
## 어휘 주석
1. **하네스(harness):** 에이전트를 실제로 구동하는 실행 엔진. Copilot Studio에는 기존의 Standard 하네스와 새로운 GitHub Copilot 하네스가 있고, 이 글의 메타데이터 필터링은 GitHub Copilot 하네스 에이전트에서 동작해요.
2. **사용자 지정 열(custom column):** SharePoint 문서 라이브러리에 직접 추가하는 속성 열. 문서마다 국가·상태·부서 같은 값을 붙여 분류할 수 있어요.
3. **스키마(schema):** 도구가 어떤 입력을 받고 어떤 형태로 결과를 돌려주는지 정해 둔 명세. 에이전트는 이걸 보고 도구를 언제, 어떻게 부를지 판단해요.
4. **권한 트리밍(permission trimming):** 검색이나 답변 결과에서 현재 사용자가 볼 권한이 없는 항목을 자동으로 빼는 동작.