Filtrování metadat SharePointu v Copilot Studio: od logiky témat k rozhodování agentů

Agenti využívající GitHub Copilot harness mohou pomocí metadat SharePointu vyhledat dokumenty platné pro daný dotaz, omezit rozsah vyhledávání ve znalostech a odpovědět bez ručně sestavené směrovací logiky.

Knihovny dokumentů SharePointu často obsahují podobné dokumenty, které ale platí pro různé skupiny uživatelů. Pravidla zaměstnaneckých benefitů se mohou lišit podle země. Produktová příručka může být určena pouze pro jeden trh. Postup může být platný jen tehdy, když má stav Approved.

V prostředí Standard harness chyběla jednoduchá, konfigurovatelná cesta od záměru uživatele přes metadata SharePointu až k URL odpovídajících dokumentů. Tvůrci agentů mohli podobné směrování sestavit pomocí více témat a uzlů Create generative answers s omezeným rozsahem. Tyto uzly ale omezovaly vyhledávání na nakonfigurované zdroje nebo URL, nikoli podle metadat knihovny dokumentů. Každá další země, oddělení nebo stav dokumentu tak znamenaly další konfiguraci, kterou bylo nutné udržovat.

Agenti využívající GitHub Copilot harness nyní tuto mezeru dokážou překlenout. Agent může interpretovat požadavek, vyfiltrovat soubory SharePointu podle metadat, získat URL odpovídajících dokumentů a vyhledávat pouze v nich.

Začněte konkrétním scénářem

Každá knihovna dokumentů SharePointu už obsahuje vestavěné sloupce, například autora a datum změny. Můžete přidat také vlastní sloupce, například zemi, stav nebo oddělení. Stačí knihovnu přidat jako znalostní zdroj a položit agentovi otázku. Tvůrce agenta nemusí konfigurovat žádný samostatný nástroj pro metadata. Pokud jsou metadata pro dotaz relevantní, agent se může pokusit zjistit dostupné sloupce, podle uložených hodnot vybrat správné soubory a odpovědět na základě této sady dokumentů. Není potřeba vytvářet samostatné téma pro každou větev, jako tomu bylo v prostředí Standard harness.

Představte si knihovnu se sloupcem Country. Uživatel se zeptá: „Jaké benefity spojené s rodičovskou dovolenou platí v Kanadě?“ Agent může najít všechny dokumenty, jejichž uložená hodnota ve sloupci Country je Canada, a poté hledat informace o rodičovské dovolené pouze v těchto souborech.

To je důležité, protože slovo „Canada“ se v samotném dokumentu vůbec nemusí vyskytovat. Může být uvedeno pouze v metadatech knihovny. Vyhledávání založené jen na obsahu proto může správný dokument přehlédnout nebo zkombinovat informace z pravidel určených pro různé země.

Stejný postup funguje i s dalšími metadaty:

• stav schválení a datum revize,
• oddělení, organizační jednotka nebo cílová skupina,
• produkt, služba nebo trh,
• typ dokumentu, vlastník nebo datum poslední změny,
• umístění ve složce a typ souboru.

Celé nastavení spočívá v přidání knihoven dokumentů SharePointu jako znalostních zdrojů. Nic dalšího není potřeba konfigurovat.

Dva vestavěné nástroje, dvě různé úlohy

Agenti využívající GitHub Copilot harness mají v současnosti k dispozici dva vestavěné nástroje pro práci se znalostmi ze SharePointu. Každý má vlastní schéma, takže agent může rozhodnout, zda zavolá jeden z nich, nebo oba propojí do navazujících kroků:

Nástroj	Důležité vstupy	Co vrací
sharepoint_metadata_filter	Autor, poslední upravující, datum, typ souboru, složka, filtry vlastních sloupců, sloupce zahrnuté do výstupu nebo sloupec pro seskupení	Názvy a URL odpovídajících souborů, hodnoty sloupců, dostupné sloupce, skutečné počty shod, počty prázdných hodnot a součty podle skupin
knowledge_search_sharepoint	Povinný parametr query, volitelný přeformulovaný dotaz search_query a volitelný parametr scopeUrls	Výsledky vyhledávání z vybraného rozsahu SharePointu včetně názvů dokumentů, URL a referenčních ID

Nástroj pro metadata může pracovat samostatně. Agent například dokáže odpovědět na otázku „Kolik dokumentů je přiřazeno k jednotlivým zemím?“, aniž by musel každý soubor otevřít a prohledat. Nástroji sharepoint_metadata_filter předá tento vstup:

{
  "groupByColumn": "Country"
}

Nástroj vrátí součty vypočítané na serveru, nikoli jen počty odvozené z řádků zobrazených agentovi:

{
  "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"
}

U otázky zaměřené na obsah, která metadata nepotřebuje, může agent zavolat knowledge_search_sharepoint přímo nad nakonfigurovanými znalostními zdroji SharePointu.

Zajímavější je propojení obou nástrojů. Představte si knihovnu se sloupcem Country a dotaz „Jaké zaměstnanecké benefity nabízí Contoso v USA?“ Agent nejprve požádá sharepoint_metadata_filter o soubory pro USA a vyžádá si všechny dostupné sloupce:

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

Nástroj vrátí odpovídající soubory, jejich metadata a URL potřebné pro další krok:

Výstup nástroje sharepoint_metadata_filter

{
  "files": [
    {
      "url": "https://pplatform.sharepoint.com/Shared%20Documents/Contoso%20HR%20Documents/Contoso%20Benefits.docx",
      "fileName": "Contoso Benefits.docx",
      "fileType": "docx",
      "author": "Emily Braun",
      "modifiedBy": "Elad Gal",
      "lastModified": "2026-09-01T20:22:12Z",
      "size": 33330,
      "columns": {
        "Country": "US",
        "Image Tags": null
      }
    },
    {
      "url": "https://pplatform.sharepoint.com/Shared%20Documents/Contoso%20HR%20Documents/Contoso%20HR%20policies.docx",
      "fileName": "Contoso HR policies.docx",
      "fileType": "docx",
      "author": "Emily Braun",
      "modifiedBy": "Elad Gal",
      "lastModified": "2026-09-01T20:22:23Z",
      "size": 28658,
      "columns": {
        "Country": "US",
        "Image Tags": null
      }
    }
  ],
  "totalFound": 2,
  "totalMatched": 2,
  "availableColumns": [
    "Image Tags",
    "Country",
    "Author",
    "Modified By"
  ],
  "backend": "sharepoint_rest",
  "usage": "Report totalMatched as the count and pass these file URLs into knowledge_search_sharepoint's scopeUrls parameter to search their contents."
}

Agent poté předá získané URL nástroji pro vyhledávání ve znalostech:

{
  "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"
  ]
}

Nástroj vyhledává v rozsahu vymezeném předanými URL a vrátí odpovídající dokumenty:

[2 results]
Title: Contoso Benefits.docx
URL: https://pplatform.sharepoint.com/.../Contoso Benefits.docx
ReferenceId: turn1doc1
Title: Contoso HR policies.docx
URL: https://pplatform.sharepoint.com/.../Contoso HR policies.docx
ReferenceId: turn1doc2

Agent nemusí oba nástroje propojovat při každém dotazu. Pro přehledy knihovny a agregace může použít pouze filtrování metadat, pro obecné otázky k obsahu pouze vyhledávání ve znalostech. Oba nástroje využije tehdy, když metadata určují správnou sadu dokumentů.

Agenta můžete vést, aniž byste skriptovali každé rozhodnutí

Dovednost (skill) Knowledge Source Router ukazuje záměrně striktní postup směrování podle země. Agentovi ukládá, aby prozkoumal metadata knihovny, získal všechny odpovídající soubory, vyhledával pouze v jejich URL a uvedl všechny nepřiřazené nebo vyloučené dokumenty.

Takto podrobné vedení je užitečné, pokud musí být postup opakovatelný a snadno kontrolovatelný. Není ale nutné pro každého agenta. Pokud má agent jasné instrukce a dobře popsané znalostní zdroje, můžete mu také nechat rozhodnutí, kdy je filtrování metadat relevantní a jak ho zkombinovat s vyhledáváním ve znalostech.

Začněte co nejjednoduššími instrukcemi, které pro Váš scénář přinášejí spolehlivé výsledky. Přísnější kroky přidejte, až když testování ukáže, že je agent potřebuje. Pokud chcete opakovaně použitelné pokyny zabalit do dovednosti, podívejte se, jak fungují Skills u agentů využívajících GitHub Copilot harness.

Vestavěné nástroje pro metadata a vyhledávání ve znalostech jsou implementační detaily, nikoli veřejná API. Jejich názvy, parametry i chování se mohou změnit bez předchozího upozornění. Řešení proto stavte na podporovaných možnostech Copilot Studio, nikoli na konkrétním rozhraní interního nástroje.

Filtrování metadat zužuje obsah, který agent zvažuje při tvorbě odpovědi. Nenahrazuje oprávnění SharePointu ani nezpřístupňuje dokumenty, které uživatel nemá právo číst. Výsledky jsou i nadále omezeny podle oprávnění přihlášeného uživatele v SharePointu.

Zásadní zůstává také kvalita metadat. Agent by měl používat hodnoty uložené v knihovně, nikoli odhadovat zemi, stav nebo vlastníka podle názvu souboru či textu dokumentu.

Jaké scénáře to umožňuje

Odpovědi zohledňující životní cyklus dokumentů. Agent může upřednostnit schválené a aktuální dokumenty a vynechat koncepty nebo vyřazené materiály, pokud knihovna tyto stavy eviduje.

Informace pro konkrétní cílovou skupinu. Jeden web SharePointu může obsahovat materiály pro několik oddělení, produktů nebo trhů, aniž by pro každou skupinu musel existovat samostatný znalostní zdroj.

Přehledy obsahu knihovny. Agent může odpovídat na otázky jako „Kolik směrnic je přiřazeno jednotlivým vlastníkům?“ nebo „Které soubory nemají vyplněnou hodnotu Country?“ přímo z metadat knihovny, místo aby odpověď odvozoval z textu dokumentů.

Hlavní změnou není další nástroj ke konfiguraci. Je jí jednodušší oddělení toho, které dokumenty jsou pro dotaz relevantní, od toho, co tyto dokumenty říkají. Díky tomu lze využívat metadata při práci se znalostmi, aniž by každá varianta vyžadovala další pevně naprogramovanou větev směrování.