Připojení agenta v agentovi Azure SRE

Háky jsou vlastní kontrolní body, které zachycují a řídí chování agenta v klíčových okamžicích. Pomocí implementačních háků vynucujte brány kvality u odpovědí agentů, provádějte audit a kontrolu využití nástrojů, vynucujte zásady pro blokování nebezpečných operací a předcházejte předčasnému dokončení úlohy ověřením výstupu agenta.

Řešení potíží s háky agenta

Váš agent spouští úlohy nezávisle tím, že prošetřuje incidenty, spouští nástroje a generuje odpovědi. Ale autonomie bez dohledu vytváří riziko:

Neúplné odpovědi: Agent před vyřešením všeho, co jste požádali, řekne "hotovo".
Využití neauditovaného nástroje: Nemáte přehled o nástrojích, které agent volá nebo jaké výsledky získá.
Žádné vynucení zásad: Nebezpečné operace (destruktivní příkazy, neoprávněné změny) probíhají bez kontroly.
Mezery v kvalitě: Odpovědi zmeškaly důležité informace, protože neexistuje žádný krok ověření.

Potřebujete způsob, jak zachytit chování agenta v klíčových okamžikech, aniž byste ho zpomalili nebo úplně odstranili jeho autonomii.

Jak fungují 'hooky' agentů

Hooky jsou vlastní kontrolní body, které připojíte ke konkrétním událostem agenta. Když se událost aktivuje, váš háček vyhodnotí situaci a rozhodne, jestli akci povolí nebo zablokuje.

Agent about to stop → Stop hook evaluates response → Allow or reject
Agent uses a tool   → PostToolUse hook checks result → Allow, block, or inject context

Aktuálně se podporují tyto dvě háčkové události:

Zvláštní událost	Spustí se, když	Co můžete dělat
Stop	Agent se chystá vrátit konečnou odpověď.	Ověřit úplnost, zamítnout a přimět agenta pokračovat
PostToolUse	Nástroj úspěšně dokončil provedení.	Auditování využití, blokových výsledků, vložení dalšího kontextu

Dvě úrovně háčků

Háky fungují na dvou úrovních:

Úroveň	Kde konfigurovat	Scope
Úroveň agenta	Tvůrce → háky na portálu	Platí pro celého agenta včetně všech vláken a všech vlastních agentů.
Úroveň vlastního agenta	Agent Canvas → vlastního agenta → spravovat háky nebo přes rozhraní REST API v2	Platí pouze, když běží konkrétní uživatelský agent.

Obě úrovně mohou existovat společně. Pokud háček na úrovni agenta a vlastní háček na úrovni agenta odpovídají stejné události, obě se spustí. Nejprve se spustí háky na úrovni agentů.

Typy spouštění

Háky můžete implementovat pomocí LLM nebo shell skriptu.

Typ	Jak to funguje	Nejvhodnější pro
Výzva	LLM vyhodnocuje váš příkaz a vrátí výsledek ve formátu JSON.	Nuanced validation ("Je tato odpověď úplná?")
Command	Skript Bash nebo Python se spouští v prostředí s izolovaným prostorem (sandbox)	Deterministické kontroly, vynucení zásad, auditování

Háky výzvy jsou pro subjektivní vyhodnocení účinné, například kontrola, jestli odpověď řeší všechny obavy uživatelů nebo zda bylo šetření dostatečně důkladné. Pomocí zástupného symbolu $ARGUMENTS získají celý kontext hooku. Pokud $ARGUMENTS na příkazovém řádku není, připojí se kontext automaticky. Pokud je k dispozici přepis konverzace, ReadFile a GrepSearch nástroje, spolu s návěsníky výzev, umožní LLM analyzovat celou historii konverzace.

Háky příkazů jsou lepší pro deterministické kontroly, jako je například ověření, že odpověď obsahuje požadované značky, blokování nebezpečných příkazů nebo použití nástroje protokolování do externího systému.

Chování agenta s háky a bez háků

Následující tabulka porovnává chování agenta s využitím háků a bez využití háků.

Bez háků	S háky
Agent se rozhodne, kdy je hotovo.	Definujete, co znamená "hotovo".
Použití nástroje je neviditelné	Každé volání nástroje je možné auditovat.
Nebezpečné příkazy postupují potichu	Prosazování zásad je automaticky blokuje.
Kvalita závisí pouze na inženýrství podnětů.	Automatizované brány kvality zachytávají nedostatky

Hooky nenahrazují bezpečnostní mechanismy provozního režimu. Místo toho je doplňují. Režimy spuštění řídí , co může agent dělat. Háky řídí , jak dobře funguje a co se stane s výsledky.

Před a po přidání háků agentů

Scénář	před	Po
Kvalita odezvy	Agent se zastaví, když si myslí, že je hotový	Váš stop hook ověří úplnost, než odpověď dosáhne uživatelů.
Viditelnost nástrojů	Žádný záznam auditu provádění nástrojů	Hákování PostToolUse zaznamenává a ověřuje každý hovor nástroje
Vynucení zásad	Nebezpečné příkazy se spouštějí nezaškrtnuté	Skripty, `rm -rf`, `sudo` a další rizikové vzory jsou blokovány automaticky.
Kontrola kvality	Inženýrství promptů je vaší jedinou pákou.	Háky založené na LLM vyhodnocují nuance; Skripty vynucují deterministická pravidla.

Konfigurace háků agentů

Vytváření hooků prostřednictvím uživatelského rozhraní portálu:

Háky na úrovni agenta: Přejděte do Builderu → háky → vyberte Vytvořit háček.
Háky na úrovni vlastního agenta: Přejděte na Agent Canvas → vyberte vlastního agenta → Spravovat háky.

Podrobné pokyny najdete v tématu Vytváření a správa háků na portálu.

Návod

Můžete také nakonfigurovat háky prostřednictvím rozhraní REST API v2 pomocí PUT /api/v2/extendedAgent/agents/{agentName}. Formát YAML v následující části ukazuje úplné schéma konfigurace. Další informace najdete v kurzu k rozhraní API.

Karta Agent Canvas YAML zobrazuje formát v1 a nezobrazuje hooky. Pomocí stránky Haky v části Builder můžete zobrazit a spravovat haky.

Následující příklad ukazuje úplnou konfiguraci háku:

api_version: azuresre.ai/v2
kind: ExtendedAgent
metadata:
  name: my_hooked_agent
spec:
  instructions: |
    You are a helpful assistant.
  handoffDescription: ""
  enableVanillaMode: true
  hooks:
    Stop:
      - type: prompt
        prompt: |
          Check if the response ends with "Task complete."
          $ARGUMENTS
          Respond with:
          - {"ok": true} if it does
          - {"ok": false, "reason": "End your response with 'Task complete.'"} if not
        timeout: 30

    PostToolUse:
      - type: command
        matcher: "Bash|ExecuteShellCommand"
        timeout: 30
        failMode: block
        script: |
          #!/usr/bin/env python3
          import sys, json, re

          context = json.load(sys.stdin)
          command = context.get('tool_input', {}).get('command', '')

          dangerous = [r'\brm\s+-rf\b', r'\bsudo\b', r'\bchmod\s+777\b']
          for pattern in dangerous:
              if re.search(pattern, command):
                  print(json.dumps({"decision": "block", "reason": f"Blocked: {pattern}"}))
                  sys.exit(0)

          print(json.dumps({"decision": "allow"}))

Formát odpovědi webhooku

Háky musí vysílovat JSON. Podporují se dva formáty:

Jednoduchý formát (doporučeno pro výzvy):

{"ok": true}
{"ok": false, "reason": "Please include more details."}

Rozšířený formát (doporučeno pro háky příkazů):

{"decision": "allow"}
{"decision": "block", "reason": "Dangerous command detected."}
{"decision": "allow", "hookSpecificOutput": {"additionalContext": "Tool audit logged."}}

Příkazové háčky mohou používat ukončovací kódy místo JSON výstupu.

Ukončovací kód	Chování
`0` bez výstupu	Povolit (bez námitky)
`0` s json	Analýza JSON pro rozhodování
`2`	Vždy zablokujte. stderr se stává příčinou
Ostatní	Používá `failMode` nastavení (`allow` nebo `block`)

Upozornění

U stop hooků se odmítnutí bez důvodu považuje za schválení a agent se řádně zastaví. Při odmítnutí vždy zadejte reason pole.

Poznámka:

Pro stejnou událost můžete definovat více háků. Pro PostToolUse se každý háček s odpovídajícím matcher vzorem spouští nezávisle. Pokud je k dispozici více additionalContextháčků, do konverzace se vloží kontext posledního háčku.

Referenční informace ke konfiguraci

Následující tabulka popisuje všechny dostupné možnosti konfigurace háku.

Možnost	Typ	Výchozí	Description
`type`	řetězec	`prompt`	`prompt` nebo `command`
`prompt`	řetězec	(žádný)	Text výzvy LLM (vyžaduje se pro háky výzvy). Slouží `$ARGUMENTS` k injektáži kontextu.
`command`	řetězec	(žádný)	Příkaz inline shell (pro příkazové háky, vzájemně se vylučují s `script`).
`script`	řetězec	(žádný)	Víceřádkový skript (pro příkazové háky, který se vylučuje s `command`).
`matcher`	řetězec	(žádný)	Šablona regulárního výrazu pro názvy nástrojů (vyžadovaná pro PostToolUse háky). `*` odpovídá všem nástrojům. Vzory jsou ukotvené jako `^(pattern)$` a porovnávají se s rozlišením malých a velkých písmen. Prázdné nebo null neodpovídá žádné hodnotě.
`timeout`	int	`30`	Časový limit spuštění v sekundách (musí být kladný; hodnoty nad 300 jsou při ověřování rozhraní příkazového řádku označeny).
`failMode`	řetězec	`allow`	Jak řešit chyby háku: `allow` nebo `block`.
`model`	řetězec	`ReasoningFast`	Model pro háčky výzvy (název scénáře nebo název nasazení)
`maxRejections`	int	`3` (výchozí nastavení agenta)	Maximální počet zamítnutí před vynucením zastavení. Rozsah: 1 až 25. Platí jenom pro háky typu Stop prompt. Zarážky typu příkaz nemají žádný implicitní limit. Pokud několik volání výzvy určuje různé hodnoty, použije se maximum.

Schéma kontextu háku

Háky přijímají strukturovaný kontext JSON týkající se aktuální události. Hooky výzvy dostávají kontext pomocí zástupného $ARGUMENTS symbolu v textu výzvy. Háky příkazů přijímají kontext jako JSON na .stdin

U obou typů execution_summary háku obsahuje pole cestu k souboru přepisu konverzace (ne vložený obsah). Pro prompt hooky obdrží LLM ReadFile a GrepSearch nástroje pro přístup k tomuto souboru. Pro volání příkazů je soubor k dispozici v zadané cestě v sandboxu.

Společná pole

Všechna háky obdrží následující pole:

{
  "hook_event_name": "Stop",
  "agent_name": "my_agent",
  "current_turn": 5,
  "max_turns": 50,
  "execution_summary": "/path/to/transcript.txt"
}

Zastavit hákové pole

Stop hooks obdrží dodatečná pole týkající se konečného výstupu agenta.

{
  "final_output": "Here is my response...",
  "stop_hook_active": false,
  "stop_rejection_count": 0
}

Pole háku PostToolUse

Háky PostToolUse obdrží další pole o provádění nástroje.

{
  "tool_name": "ExecutePythonCode",
  "tool_input": { "code": "print(2+2)" },
  "tool_result": "4",
  "tool_succeeded": true
}

Úrovně modelu

Hooky promptu využívají model AI k vyhodnocování chování agenta. Můžete vybrat, kterou úroveň modelu bude hook používat, a vyvážit tak kvalitu vyhodnocování vzhledem k nákladům a latenci.

Vrstva	Nejvhodnější pro	Kompromis
Reasoning	Komplexní vynucování zásad, vícekrokové ověřování, drobné kontroly dodržování předpisů	Nejvyšší kvalita, vyšší náklady a latence
Rychlé odůvodnění (výchozí)	Většina háků, ověřování odpovědí, kontroly auditu, bezpečnostní vynucování	Kvalitní uvažování s nízkou latencí
Obecné účely	Jednoduché kontroly formátu, základní ověření dodržování předpisů	Vyvážená přesnost, náklady a rychlost
Rychle	Zjednodušené kontroly, ověření přítomnosti, ověření formátu	Nejnižší náklady, nejrychlejší odpověď
Dlouhý kontext	Hooky, které zpracovávají velké výstupy, analýzu celých dokumentů a rozsáhlé výstupy nástrojů	Zpracovává větší vstup, vyšší náklady

Návod

Hooky ve výchozím nastavení používají Fast Reasoning, protože se spouštějí při každé odpovědi agenta nebo volání nástroje, takže nízká latence je důležitá. Používejte důvod pouze pro háky, které vynucují složité zásady, kde je přesnost kritická.

Omezení

Následující omezení platí pro háky agentů.

Limit	Hodnota
Velikost skriptu	Maximálně 64 kB
Přerušení zápasu	1 až 300 sekund
Maximální počet zamítnutí (výzva k zastavení háku)	1 až 25 (výchozí: 3)
Podporované skriptové interprety	`#!/bin/bash`, `#!/usr/bin/env python3`
Prostředí spouštění skriptů	Interpret kódu v izolovaném prostoru (sandbox)

Příklad: Auditování veškerého využití nástrojů

Následující postToolUse hook zaznamená každé volání nástroje a přidá kontextovou zprávu auditu:

hooks:
  PostToolUse:
    - type: command
      matcher: "*"
      timeout: 30
      failMode: allow
      script: |
        #!/usr/bin/env python3
        import sys, json

        context = json.load(sys.stdin)
        tool_name = context.get('tool_name', 'unknown')

        print(f"Tool used: {tool_name}", file=sys.stderr)

        output = {
            "decision": "allow",
            "hookSpecificOutput": {
                "additionalContext": f"[AUDIT] Tool '{tool_name}' was executed."
            }
        }
        print(json.dumps(output))

Toto additionalContext pole je přidáno do konverzace jako zpráva uživatele, čímž poskytuje agentovi přehled o záznamu auditu.

Příklad: Vyžadování značky dokončení

Následující zarážka zamítá odpovědi, které nekončí na "Dokončení úkolu".

hooks:
  Stop:
    - type: command
      timeout: 30
      failMode: allow
      script: |
        #!/bin/bash
        CONTEXT=$(cat)
        FINAL_OUTPUT=$(echo "$CONTEXT" | jq -r '.final_output // empty')

        if [[ "$FINAL_OUTPUT" == *"Task complete."* ]]; then
          exit 0
        else
          echo "Please end your response with 'Task complete.'" >&2
          exit 2
        fi

Osvědčené postupy

Při konfiguraci háků agenta:

Při odmítnutí vždy uveďte důvod. Zachází s zamítnutími bez důvodů jako se schváleními.
Použijte vhodné časové limity: Dlouhotrvající háky zpomalují spouštění agenta.
Zpracovávejte chyby elegantně: Použijte failMode: allow, pokud není vyžadováno striktní vynucování.
Buďte specifická s nástroji pro porovnávání: Příliš široké nástroje PostToolUse můžou způsobit problémy s výkonem.
Důkladně otestujte háky: Háky, které vždy selhávají, můžou způsobit smyčky (což lze zmírnit pomocí ).
Přihlaste se k stderru: Pro ladění výstupu použijte stderr. Systém parsuje stdout jako výsledek hooku.

Vyzkoušejte si agent hooky

Následující snímek obrazovky ukazuje stop háček v akci. Agent zpočátku odpovídá pouze textem "4", ale háček odpověď odmítne, protože chybí ukončovací značka. Agent pak pokračuje a přidá značku.

Začínáme

zdroj	Co se naučíte
Vytváření a správa háků (portál)	Vytvářejte hooky vizuálně v uživatelském rozhraní portálu, bez nutnosti volání API.
Konfigurace háků agentů (API)	Nastavte hooky pomocí REST API v2 a YAML.

Schopnost	Jak souvisí
Režimy spuštění	Háky doplňují bezpečnostní prvky režimu spuštění. Režimy řídí, co běží, háky řídí , jak dobře běží.
Nástroje Pythonu	Vytvořte vlastní nástroje, které můžou háky auditovat a ověřovat.

Váš názor

Byla tato stránka užitečná?

Last updated on 2026-06-04