Kurz: Konfigurace háků agentů (API) v agentovi Azure SRE

Návod

Dáváte přednost uživatelskému rozhraní portálu? Nyní můžete vytvářet a spravovat háky přímo na portálu bez použití rozhraní REST API. Portál poskytuje vizuální formulář a editor kódu. Nejsou vyžadovány žádné curl příkazy.

V tomto kurzu vytvoříte vlastního agenta s hákem Stop, který vynutí agenta přidat značku dokončení do každé odpovědi. Hook nakonfigurujete prostřednictvím rozhraní REST API a pak ho otestujete na dětském hřišti portálu.

Odhadovaný čas: 15 minut

Poznámka:

Hooky na úrovni agenta vs. hooky na úrovni vlastního agenta: Tento tutoriál vytváří hooky pro vlastního agenta (hooky na úrovni vlastního agenta). Tyto hooky se aktivují pouze při spuštění toho konkrétního vlastního agenta.

Pokud chcete vytvořit háky na úrovni agenta, které platí pro celého agenta (všechna vlákna, všechny vlastní agenty), použijte na portálu Tvůrce>Hooků.

Úroveň	Postup vytvoření	Scope
Úroveň agenta	Portál: Stavitel > Hooky	Platí pro všechna vlákna a speciální agenty.
Úroveň vlastního agenta	REST API (tento kurz) nebo Portál: Agent Canvas > Vlastní agent > Správa háků	Platí jenom pro jednoho vlastního agenta.

V tomto návodu se naučíte, jak:

Vytvoření vlastního agenta s použitím stop hooku pomocí rozhraní REST API
Testování chování háků v testovacím prostředí portálu
Přidání háku PostToolUse pro využití nástrojů pro auditování
Blokovat nebezpečné příkazy pomocí politického hooku

Předpoklady

Agent Azure SRE ve běžícím stavu
curl pro volání rozhraní REST API
Přihlášení k Azure CLI (az login) pro získání přístupového tokenu

Pochopte formát hooku API

Tento kurz používá rozhraní REST API v2 k vytvoření hooků na vlastní agent. Karta editoru YAML na portálu zobrazuje formát v1 a nezobrazuje háky nakonfigurované přes rozhraní API, ale háky jsou stále aktivní. Můžete je ověřit na stránce Builderu>Hooků nebo v testovacím prostředí.

Návod

Kdy použít rozhraní API vs. portál:

Portál (háky tvůrce > ): Nejvhodnější pro háky na úrovni agenta ve vizuální podobě. Není nutný žádný kód.
Rozhraní API (tento kurz): Nejvhodnější pro háky na úrovni vlastních agentů, kanály CI/CD nebo programovou správu.

Vyhledání adresy URL rozhraní API vašeho agenta

Základní adresa URL rozhraní API vašeho agenta se řídí tímto vzorem:

https://{agent-name}--{hash}.{hash}.{region}.azuresre.ai

Jak ho najít:

Otevřete sre.azure.com a vyberte svého agenta.
Na levém bočním panelu vyberte Tvůrce>Plátno agenta.
Otevřete vývojářské nástroje prohlížeče (F12 nebo klikněte pravým tlačítkem na > Zkontrolovat).
Přejděte na kartu Síť, vyfiltrujte podle "api" a vyhledejte požadavky na adresu URL končící ..azuresre.ai
Základní adresa URL je vše před /api/....

Případně zkontrolujte src atribut na kartě Prvky. Vyhledejte <iframe>, jehož src začíná na https://{agent-name}--.

Získání přístupového tokenu

Spuštěním následujícího příkazu získejte přístupový token pro rozhraní API agenta SRE:

TOKEN=$(az account get-access-token \
  --resource <RESOURCE_ID> \
  --query accessToken -o tsv)

Vytvoření vlastního agenta se stop hákem

Tento krok vytvoří vlastního agenta nazvaného my_hooked_agent pomocí zarážky Stop, která zkontroluje, jestli odpověď končí na === RESPONSE COMPLETE ===. Pokud značka chybí, háček odpověď odmítne a řekne agentovi, aby přidal značku.

AGENT_URL="https://your-agent--xxxxxxxx.yyyyyyyy.region.azuresre.ai"

curl -X PUT "${AGENT_URL}/api/v2/extendedAgent/agents/my_hooked_agent" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @- << 'EOF'
{
  "name": "my_hooked_agent",
  "properties": {
    "instructions": "You are a helpful assistant. Be concise.",
    "handoffDescription": "",
    "handoffs": [],
    "enableVanillaMode": true,
    "hooks": {
      "Stop": [
        {
          "type": "prompt",
          "prompt": "Check the agent response below.\n\n$ARGUMENTS\n\nDoes it end with === RESPONSE COMPLETE ===?\nIf yes: {\"ok\": true}\nIf no: {\"ok\": false, \"reason\": \"Add === RESPONSE COMPLETE === at the end.\"}",
          "timeout": 30
        }
      ]
    }
  }
}
EOF

Obdržíte HTTP 202 Akceptované s úplnou konfigurací agenta v těle odpovědi.

Následující příklad ukazuje stejnou konfiguraci ve formátu YAML v2 pro referenci:

api_version: azuresre.ai/v2
kind: ExtendedAgent
metadata:
  name: my_hooked_agent
spec:
  instructions: |
    You are a helpful assistant. Be concise.
  handoffDescription: ""
  enableVanillaMode: true
  hooks:
    Stop:
      - type: prompt
        prompt: |
          Check the agent response below.

          $ARGUMENTS

          Does it end with === RESPONSE COMPLETE ===?
          If yes: {"ok": true}
          If no: {"ok": false, "reason": "Add === RESPONSE COMPLETE === at the end."}
        timeout: 30

Jak funguje stop hák

Stop hook vyhodnocuje odpověď agenta předtím, než se vrátí uživateli.

$ARGUMENTS Nahradí JSON kontextu hooku, který zahrnuje konečnou odpověď agenta.
LLM vyhodnotí výzvu a vrátí {"ok": true} nebo {"ok": false, "reason": "..."}.
Pokud je odmítnuto, agent bude pokračovat v práci poté, co se důvod vloží jako zpráva uživatele.
Po třech zamítnutích (výchozí nastavení) se agent zastaví.

Otestování háku na portálu

K otestování háku Stop postupujte takto:

Přejděte na portál ke svému agentovi a vyberte Tvůrce>Plátno agenta.
Vyberte přepínač Testovací hřiště .
Vyberte rozevírací seznam Subagent/Tool , najděte my_hooked_agent a vyberte Použít.
Zadejte What is 2+2? do chatu a vyberte Odeslat.

Podívejte se, co se stane:

Agent nejprve odpoví 4.
Stop hook vyhodnocuje a odmítne odpověď (bez indikátoru dokončení).
Zobrazí se krok myšlenkového procesu, ve kterém agent pokračuje.
Zobrazí se konečná odpověď: 4 === RESPONSE COMPLETE ===.

Háček fungoval. Přinutilo agenta přidat značku před zastavením.

Přidání háku PostToolUse pro auditování

Přidejte háček PostToolUse, který protokoluje každý nástroj, který agent používá. Aktualizujte téhož agenta odesláním nového požadavku PUT se dvěma hooky:

curl -X PUT "${AGENT_URL}/api/v2/extendedAgent/agents/my_hooked_agent" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d @- << 'EOF'
{
  "name": "my_hooked_agent",
  "properties": {
    "instructions": "You are a helpful assistant. Be concise.",
    "handoffDescription": "",
    "handoffs": [],
    "enableVanillaMode": true,
    "hooks": {
      "Stop": [
        {
          "type": "prompt",
          "prompt": "Check the agent response below.\n\n$ARGUMENTS\n\nDoes it end with === RESPONSE COMPLETE ===?\nIf yes: {\"ok\": true}\nIf no: {\"ok\": false, \"reason\": \"Add === RESPONSE COMPLETE === at the end.\"}",
          "timeout": 30
        }
      ],
      "PostToolUse": [
        {
          "type": "command",
          "matcher": "*",
          "timeout": 30,
          "failMode": "allow",
          "script": "#!/usr/bin/env python3\nimport sys, json\ncontext = json.load(sys.stdin)\ntool = context.get('tool_name', 'unknown')\nprint(json.dumps({'decision': 'allow', 'hookSpecificOutput': {'additionalContext': f'[AUDIT] {tool} executed.'}}))"
        }
      ]
    }
  }
}
EOF

matcher: "*" znamená, že tento háček běží pro každé volání nástroje. Skript zaznamená název nástroje a vloží [AUDIT] zprávu do konverzace.

K otestování háku požádejte agenta o otázku, která aktivuje nástroj (například Spustit echo hello).

Blokování nebezpečných příkazů

Přidejte druhý háček PostToolUse, který blokuje rm -rf, sudoa chmod 777:

PostToolUse:
  # Audit hook (runs for all tools)
  - type: command
    matcher: "*"
    timeout: 30
    failMode: allow
    script: |
      #!/usr/bin/env python3
      import sys, json
      context = json.load(sys.stdin)
      tool = context.get('tool_name', 'unknown')
      print(json.dumps({"decision": "allow",
        "hookSpecificOutput": {"additionalContext": f"[AUDIT] {tool} executed."}}))

  # Policy hook (only for shell tools)
  - 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', '')
      for pattern in [r'\brm\s+-rf\b', r'\bsudo\b', r'\bchmod\s+777\b']:
          if re.search(pattern, command):
              print(json.dumps({"decision": "block", "reason": f"Blocked: {pattern}"}))
              sys.exit(0)
      print(json.dumps({"decision": "allow"}))

Klíčové rozdíly oproti háku auditu:

matcher: "Bash|ExecuteShellCommand" Spouští se pouze pro nástroje prostředí (vzor je ukotvený jako ^(Bash|ExecuteShellCommand)$).
failMode: block zablokuje výsledek nástroje, pokud se samotný skript chybově ukončí (striktní režim).
Vrátí "block" s důvodem, kdy je nalezen nebezpečný vzor.

Formáty odpovědí hooku

Háky příkazového řádku a příkazové háky používají různé formáty odpovědí.

Spouštěcí háky

Volání výzvy vrací jednoduchý kód JSON:

{"ok": true}

{"ok": false, "reason": "Please fix X."}

Háky příkazů

Háky příkazů vrací rozbalený JSON:

{"decision": "allow"}

{"decision": "block", "reason": "Dangerous command."}

{"decision": "allow", "hookSpecificOutput": {"additionalContext": "Audit note."}}

Háky příkazů můžou místo JSON používat ukončovací kódy:

Ukončovací kód	Chování
`0` bez výstupu	Povolit
`0` s json	Parsování JSON
`2`	Block (stderr je důvodem)
Ostatní	Vrátí se zpět do `failMode`

Upozornění

Zamítnutí bez důvodu se považuje za schválení. Při odmítnutí vždy zahrňte reason .

Ověřte

Po konfiguraci a otestování háku potvrďte následující podmínky:

Připojení na úrovni vlastního agenta nakonfigurujete pomocí rozhraní REST API verze 2. Platí pouze pro specifického agenta.
V hookech Tvůrce vytvoříte >. Platí pro celého agenta.
Stop hák způsobí, že agent přidá značku === RESPONSE COMPLETE === před zastavením.
PostToolUse audit hook protokoluje [AUDIT] zprávy pro volání nástrojů.
Háček zásad blokuje nebezpečné příkazy jako rm -rf a sudo.

Troubleshooting

Následující tabulka uvádí běžné problémy a řešení pro háky agentů.

Problém	Řešení
Na kartě YAML na portálu se nezobrazují háky	Očekáváno – karta YAML zobrazuje jenom verzi 1. Vlastní hooky na úrovni agentů vytvořené prostřednictvím rozhraní API jsou aktivní a viditelné v Tvůrce>Hácích nebo v testovacím prostředí.
`Unsupported kind: ExtendedAgent`	Použijte koncový bod v2: `PUT /api/v2/extendedAgent/agents/{name}`.
`Handoffs cannot be null`	Přidejte `"handoffs": []` do datového bloku JSON.
Háček nemá žádný účinek	Při odmítnutí uveďte pole `reason`. Bez ní se odmítnutí považuje za schválení.
Agent se smyčkuje navždy	Nižší `maxRejections` (výchozí hodnota: 3, rozsah: 1–25).

Další krok

Přečtěte si o hácích agentů.

Váš názor

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

Last updated on 2026-03-28