Hooks v Copilot Studio: řízení chování agentů je dostupné ve veřejném preview

GHCP harness

U agentů využívajících GitHub Copilot harness agent zvažuje, jak úkol vyřešit a které nástroje zavolat. Instrukce tato rozhodnutí usměrňují, některé kroky by se ale měly spustit pokaždé, když nastane určitá událost – nejen tehdy, když je model sám zvolí. Hooks poskytují předvídatelné kontrolní body, ve kterých běhové prostředí vyvolá Vámi připravenou logiku.

HR agent tak může zahájit konverzaci s již dostupnou informací o zemi zaměstnance a jeho preferovaném jazyce. Pracovní postup pro maskování dat může skrýt citlivé osobní údaje v dotazu uživatele ještě před zpracováním agentem. Rezervační pracovní postup zase může porovnat navrženou cenu s rozpočtem zaměstnance před spuštěním rezervačního nástroje.

Následující příklady ukazují, jak hooks doplňují kontext, transformují data a kontrolují navrhované akce. Zahrnují pracovní postupy, mapování vstupů a výstupů i záznamy průběhu zpracování včetně situací, kdy hook selže.

Hooks jsou aktuálně ve veřejném preview pro agenty využívající GitHub Copilot harness. Najdete je na copilotstudio.preview.microsoft.com, kde si ověřte dostupnost ve Vašem prostředí.

Od spouštěčů témat k hooks

U agentů využívajících Standard harness nabízejí spouštěče témat známé způsoby reakce v definovaných bodech konverzace: A message is received zpracovává příchozí zprávy a An AI-generated response is about to be sent se uplatňuje ve fázi odesílání odpovědi.

Agenti využívající GitHub Copilot harness používají hooks jako rozšiřující body v konkrétních okamžicích zpracování, například při zahájení relace nebo před voláním nástroje. Jakmile nastane odpovídající událost, běhové prostředí vyvolá nakonfigurovanou logiku, aniž by její spuštění musel zvolit model.

Stejný princip hooks navázaných na životní cyklus je dostupný také v GitHub Copilot SDK, kde vývojáři používají obslužné funkce jako onSessionStart a onPreToolUse.

V Copilot Studio se obsluha hooku aktuálně implementuje prostřednictvím pracovního postupu. Ten přijímá vstupy události a vrací výstupy, které doplňují kontext, nahrazují hodnoty nebo zakazují navržené volání nástroje. Hook určuje, kdy se pracovní postup spustí; agent nadále rozhoduje, jak úkol vyřešit s využitím výsledného kontextu a rozhodnutí.

Dovednosti agentů poskytují pokyny k řešení úkolů, zatímco hooks zajišťují spouštění na základě událostí. Další souvislosti popisuje přehled agentů využívajících GitHub Copilot harness.

Konfigurace hooku

Podle návodu Add a hook vyberte událost, vytvořte nebo vyberte kompatibilní pracovní postup a připojte jej k agentovi. Stejný pracovní postup můžete použít u více agentů a podle metadat o agentovi, uživateli nebo kanálu určit, která pravidla se mají uplatnit.

1. Načtení kontextu zaměstnance při zahájení relace

Agent HR Buddy odpovídá zaměstnancům na otázky týkající se benefitů a nástupu do zaměstnání. Užitečnost odpovědí závisí na kontextu: země zaměstnance pomáhá určit příslušné pokyny, kategorie pracovního poměru ovlivňuje platnost jednotlivých zásad a preferovaný jazyk určuje jazyk odpovědi. Cílem je zpřístupnit tyto údaje hned na začátku relace.

Start (pre-loop) se spouští na začátku nové konverzace. Nasazený pracovní postup načte profil přihlášeného zaměstnance a vrátí additionalContext. Tento text se připojí k první zprávě uživatele v relaci jako další blok kontextu. Model tak získá informace, které může využít při uvažování a tvorbě odpovědi. Například „Země: Řecko“ a „Preferovaný jazyk: řečtina“ pomohou agentovi HR Buddy vybrat relevantní pokyny a odpovědět řecky.

Přestože blok doprovází zprávu uživatele, jeho obsah dodává pracovní postup – uživatel tyto údaje nemusí zadávat. Blok doplňuje instrukce agenta a obsah konverzace. Oprávnění k datům a nárok na benefity nadále vynucují a určují HR systémy.

V ukázkovém agentovi HR Buddy vytvořte hook Load employee context, vyberte Start (pre-loop) a připojte příslušný pracovní postup:

Formulář pro vytvoření hooku propojuje událost zahájení relace s pracovním postupem pro načtení kontextu zaměstnance.

Ukázkový pracovní postup má následující kroky:

Krok	Vstup a výstup
Identifikace zaměstnance	Načtěte metadata.userAadObjectId ze vstupu hooku.
Načtení profilu	Podle ID vyhledejte ukázkový záznam zaměstnance. Pokud nenajdete odpovídající profil, zaznamenejte důvod.
Výběr polí	Použijte country, employmentCategory, preferredLanguage a onboardingStage.
Vrácení kontextu	Zformátujte hodnoty jako additionalContext; pro identitu bez odpovídajícího záznamu vraťte prázdný kontext.

V produkčním prostředí nahraďte krok s ukázkovým profilem vyhledáváním v HR systému s ověřením identity a oprávnění.

Průběh zpracování v HR Buddy: hook vrátí kontext zaměstnance v additionalContext, následuje volání nástroje a odpověď v řečtině.

2. Maskování osobních údajů v promptu pomocí Azure Language

Pomocí události User prompt submitted odešlete prompt do Azure Language k detekci osobních údajů (PII) a vraťte text s maskovanými údaji jako modifiedPrompt.

Test v Preview používá otázku na rodičovskou dovolenou obsahující ukázkové americké číslo sociálního zabezpečení (Social Security number) z dokumentace Microsoftu.

Konfigurace ověřeného volání služby

Použijte akci Detect Personal Information (V3.1) z konektoru Azure Cognitive Service for Language. Krok pojmenujte Analyze prompt PII:

Nastavení	Hodnota
Koncový bod	HTTPS koncový bod schváleného prostředku Azure Language.
Ověřování	Klíč účtu uložený v zabezpečeném připojení konektoru.
Operace	EntitiesRecognitionPIIV3_1, využívající Text Analytics v3.1.
Kategorie PII	V tomto příkladu USSocialSecurityNumber.
Vypnutí protokolování (Logging opt-out)	true.

Přihlašovací údaje uchovávejte v zabezpečeném připojení a přístup omezte na schválené volající.

Vytvořte Redact prompt PII. Namapujte prompt na pole text dokumentu s ID prompt-1 a jazykem en. Předávejte objekt dokumentu, aby konektor správně serializoval uvozovky a konce řádků.

Pracovní postup odešle prompt z hooku do Azure Language, ověří výsledek a vrátí text s maskovanými údaji.

Nastavte kategorie a jazyk podle zásad Vaší organizace; tento příklad používá angličtinu a jedinou kategorii. Výchozí maskování nahrazuje údaje hvězdičkami.

Mapování výsledku služby na výstup hooku

Ověřte výsledek konektoru i zpracování dokumentu: vyžadujte prázdné pole errors, právě jeden dokument s odpovídajícím ID, vyplněné redactedText a ošetření varování. Uložené schéma v kroku Parse JSON odmítá neočekávané dokumenty, prázdný text po maskování i neprázdná pole chyb nebo varování.

V kroku Respond to the agent namapujte redactedText odpovídajícího dokumentu na modifiedPrompt. Poté připojte pracovní postup k hooku User prompt submitted ukázkového agenta HR Buddy.

Skutečný průběh v Preview: číslo sociálního zabezpečení se nahradí hvězdičkami, zatímco otázka na rodičovskou dovolenou a požadovaný jazyk odpovědi zůstanou beze změny.

Dále předávejte pouze text s maskovanými údaji. Podrobnosti o rozpoznaných entitách obsahující původní hodnoty ponechte uvnitř schváleného procesu zpracování. Pokud služba nic nerozpozná, vrátí původní znění. Úspěšnost detekce se liší a některé citlivé hodnoty mohou v textu zůstat.

Při selhání: Pokud hook skončí chybou nebo překročí časový limit, může agent pokračovat ve zpracování původního promptu. Selhání zaznamenejte pomocí diagnostiky očištěné od citlivých údajů a nastavte níže popsané řízení přístupu a uchovávání dat.

3. Kontrola rezervace vůči rozpočtu

Cestovní agent pomáhá zaměstnanci vybrat let. Předpokládejme, že navrhne rezervaci za 650 USD, ale zaměstnanec má rozpočet 500 USD. Cílem je zkontrolovat skutečně navrženou rezervaci před jejím provedením a poskytnout agentovi jasný důvod k výběru letu v rámci rozpočtu.

Pre tool use se spouští bezprostředně před voláním nástroje a poskytuje toolName a parameters. Pracovní postup porovná navrženou cenu a měnu s nezávisle načtenými zásadami a vrátí rozhodnutí. Odpověď deny zablokuje navržené volání a poskytne modelu důvod, který může použít k vysvětlení limitu nebo k výběru jiné možnosti.

Ukázkový agent Travel Buddy má nástroj BookFlight založený na pracovním postupu, který neprovádí skutečnou transakci, a hook Check booking policy spouštěný před použitím nástroje. Jeho působnost je přes pole Tools omezena na tento nástroj. Hook porovnává navrženou cenu s ukázkovým limitem 500 USD.

Nástroj přijímá quoteId, totalMinorUnits a currency. Částky v USD se předávají jako celočíselný počet centů: 65000 představuje 650 USD. V chatu Preview nástroj tuto hodnotu serializoval jako text, proto ji pracovní postup před porovnáním částek převádí pomocí int().

Ukázkový pracovní postup sjednotí formát ceny a porovná ji s limitem. Produkční nasazení vyžaduje níže uvedené kontroly identity, zásad a backendu.

Krok	Vstup a rozhodnutí
Ověření návrhu	Vyžadujte nakonfigurovaný název nástroje, identitu přihlášeného uživatele, vyplněné ID cenové nabídky, kladnou celočíselnou cenu a měnu USD.
Načtení zásad	Použijte metadata.userAadObjectId při načtení zásad s kontrolou oprávnění. Ukázkový záznam poskytuje limit 50 000 amerických centů.
Ověření zásad	Vyžadujte právě jedny použitelné zásady, nezáporný celočíselný limit a shodnou měnu.
Porovnání částek	Cenu nad limitem zamítněte. Platnou cenu rovnou limitu nebo nižší povolte.
Vrácení rozhodnutí	Nastavte permissionDecision a permissionDecisionReason. Původní argumenty zachovejte ponecháním prázdného modifiedParameters.

Skutečný průběh v Preview: návrh za 650 USD je zamítnut s odůvodněním. Agent požádá o levnější nabídku, aniž by zavolal BookFlight.

Pro schválení ponechte oba výstupy rozhodnutí o povolení prázdné. Při ošetřených chybách validace nebo načítání zásad vraťte deny s důvodem: „Rezervace vyžaduje ověřené zásady. Zkuste to prosím znovu, až bude ověření zásad úspěšné.“ Pole additionalContext ponechte prázdné a suppressOutput nastavte na false.

Při selhání: Pokud hook před použitím nástroje selže nebo překročí časový limit, rezervační nástroj se přesto může spustit. V produkčním prostředí musí rezervační služba před vytvořením rezervace nezávisle ověřit volajícího, nabízenou cenu a rozpočet.

Další události hooks

Událost	Vstupy	Využití
Post tool use	toolName, parameters, result	Vraťte modifiedResult a před zpracováním modelem vyberte z úspěšného výsledku nástroje pouze schválená pole.
After tool failure	toolName, parameters, error	Vyhodnoťte nástroj a chybu a vraťte additionalContext s pokyny, například s pravidlem omezeného počtu opakování při dočasné chybě vyhledávání. Agent podle tohoto kontextu zvolí další krok.
Error	error, errorContext, recoverable	Chyby mimo volání nástroje ošetřete prostřednictvím errorHandling: retry, skip nebo abort. Použijte omezený retryCount a bezpečný obsah userNotification.

Všechna pole popisuje referenční přehled událostí.

Aktuální chování a požadavky na implementaci

Selhání hooks a povinné kontroly

Současné běhové prostředí používá chování fail-open: pokud hook skončí chybou, překročí časový limit nebo vrátí odpověď, kterou nelze přečíst, zpracování pokračuje výchozím způsobem.

Pro pracovní postupy hooks platí časový limit odpovědi pracovního postupu. Při jeho překročení zobrazí chat Preview upozornění, že hook selhal kvůli vypršení časového limitu pracovního postupu.

Příklad	Důsledek selhání hooku
Kontext zaměstnance	Agent pokračuje s dosavadním kontextem.
Maskování promptu	Agent může pokračovat ve zpracování původního promptu.
Kontrola rezervace	Nástroj pokračuje ve zpracování; nadále se uplatňují nezávislá pravidla vynucovaná backendem.

Kontroly před použitím nástroje mohou provádět detekci osobních údajů, vynucovat pravidla ochrany soukromí, ověřovat zásady a oprávnění, zabraňovat úniku dat nebo zajišťovat jiné kontroly souladu s předpisy. Jejich selhání může odhalit citlivá data nebo umožnit operaci, kterou by zásady zablokovaly.

Pokud ověření selže, povinné kontroly musí zabránit provedení chráněné akce. Tomuto chování se říká fail-closed. Protože hooks v Copilot Studio aktuálně fungují v režimu fail-open, vynucujte zásadní pravidla nezávisle v nástroji nebo v podkladové službě. Rezervační služba například musí odmítnout rezervaci nad rozpočtem i tehdy, když hook není dostupný.

Pracovní postup může zachytit chybu služby a vrátit deny, čímž volání nástroje zablokuje. Pokud ale selže samotný pracovní postup nebo překročí časový limit, nástroj se přesto může spustit. Tyto situace testujte odděleně a rozlišujte mezi zabráněním volání nástroje a odmítnutím transakce v backendu. U nástrojů odesílajících citlivá data musí kontrola úspěšně proběhnout ještě předtím, než data opustí systém. Protokoly a upozornění pomáhají selhání odhalit, samotné akci ale nezabrání.

Maskování a uchovávání dat

Hooks mohou maskovat data ve třech kontrolních bodech: User prompt submitted vrací modifiedPrompt, který nahrazuje zprávu předávanou agentovi; Pre tool use vrací modifiedParameters, které nahrazují argumenty odesílané nástroji; Post tool use vrací modifiedResult, který nahrazuje úspěšný výsledek nástroje před jeho předáním modelu.

Tyto transformace nemažou data, která již byla přijata nebo uložena. V příkladu s osobními údaji obdrží původní prompt Copilot Studio i Azure Language, proto nastavte přístup k přepisům konverzací a protokolům i dobu jejich uchovávání samostatně. Parametr suppressOutput řídí výstup viditelný pro uživatele, nikoli ukládání dat.

Použití hooks u vestavěných nástrojů

Hooks podporují také vestavěné znalostní nástroje, například web_search, a nástroje příkazového řádku, například příkazy bash. Nejprve k agentovi přidejte alespoň jeden nástroj, aby se v konfiguraci hooku zobrazil filtr Tools. Chcete-li hook použít i na volání vestavěných nástrojů, zvolte rozsah All tools ponecháním prázdného pole Tools. Tyto vestavěné nástroje nelze ve filtru vybrat jednotlivě.

Vstup hooku obsahuje toolName, takže pracovní postup může rozpoznat volaný nástroj a použít odpovídající logiku. Protože All tools zahrnuje i ostatní volání nástrojů, před vytvořením podmínek podle jejich názvů ověřte skutečné názvy v Preview.

Praktické nasazení hooks

Hooks rozšiřují chování agentů nad rámec instrukcí tím, že propojují pracovní postupy s klíčovými okamžiky zpracování. Začněte konkrétním, úzce vymezeným scénářem, ověřte výsledky v Preview a předem naplánujte, co se má stát při selhání pracovního postupu.