Haki agentów w agencie usługi Azure SRE

Hooks to niestandardowe punkty kontrolne, które przechwytują i kontrolują zachowanie agenta w kluczowych momentach. Użyj punktów zaczepienia, aby wymusić bramy jakości na odpowiedziach agentów, użyciu narzędzia inspekcji i kontroli, blokować niebezpieczne operacje przez wymuszanie zasad i zapobiegać wczesnemu uzupełnianiu zadań przez weryfikowanie danych wyjściowych agenta.

Problem rozwiązywany przez haki agenta

Agent uruchamia zadania autonomicznie, badając zdarzenia, uruchamiając narzędzia i generując odpowiedzi. Ale autonomia bez nadzoru stwarza ryzyko:

Niekompletne odpowiedzi: agent oznajmia "gotowe" zanim zajmie się wszystkim, o co poprosiłeś.
Niezaudytowane użycie narzędzia: nie masz wglądu w narzędzia, które agent wywołuje lub jakie wyniki otrzymuje.
Brak wymuszania zasad: niebezpieczne operacje (destrukcyjne polecenia, nieautoryzowane zmiany) przechodzą bez kontroli.
Luki w jakości: odpowiedzi pomijają krytyczne informacje, ponieważ nie ma kroku weryfikacji.

Potrzebujesz sposobu na przechwycenie zachowania agenta w kluczowych momentach bez spowolnienia go lub całkowitego usunięcia jego autonomii.

Jak działają haki agenta

Punkty zaczepienia to niestandardowe punkty kontrolne dołączane do określonych zdarzeń agenta. W momencie wywołania zdarzenia, uchwyt ocenia sytuację i decyduje, czy zezwolić na działanie, czy je zablokować.

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

Obecnie obsługiwane są dwa zdarzenia hooków:

Zdarzenie	Wyzwalacz uruchamia się, gdy	Co można zrobić
Zatrzymaj	Agent ma zwrócić ostateczną odpowiedź	Weryfikuj kompletność, odrzuć i wymuś kontynuowanie agenta
PostToolUse	Narzędzie kończy wykonywanie pomyślnie	Kontrola użycia, blokowanie wyników, wstrzykiwanie dodatkowego kontekstu

Dwa poziomy haków

Hooki działają na dwóch poziomach:

Level	Gdzie skonfigurować	Scope
Poziom agenta	Builder → Hooks w portalu	Dotyczy całego agenta, łącznie ze wszystkimi wątkami i agentami spersonalizowanymi.
Poziom agenta indywidualnego	Widok agenta → Agenta Niestandardowego → Zarządzanie Hakami lub za pośrednictwem REST API v2	Ma zastosowanie tylko wtedy, gdy ten konkretny agent niestandardowy jest uruchamiany

Oba poziomy mogą współistnieć. Jeśli punkt zaczepienia na poziomie agenta i punkt zaczepienia na poziomie niestandardowym agenta są zgodne z tym samym zdarzeniem, oba są uruchamiane. Haki na poziomie agenta są najpierw uruchamiane.

Typy wykonania

Możesz implementować hooki, używając albo LLM, albo skryptu powłoki.

Typ	Jak to działa	Najlepsze dla
Polecenie	Usługa LLM ocenia monit i zwraca decyzję w formacie JSON	Walidacja zniuansowana ("Czy ta odpowiedź została ukończona?")
Polecenie	Skrypt Bash lub języka Python jest uruchamiany w odizolowanym środowisku piaskownicy	Deterministyczne kontrole, wymuszanie zasad, inspekcja

Punkty zaczepienia monitu są zaawansowane do oceny subiektywnej, na przykład sprawdzania, czy odpowiedź dotyczy wszystkich obaw użytkowników lub sprawdzania, czy badanie było wystarczająco dokładne. Używają symbolu zastępczego $ARGUMENTS do odbierania pełnego kontekstu haka. Jeśli $ARGUMENTS nie jest obecny w wierszu polecenia, kontekst jest dołączany automatycznie. Gdy dostępna jest transkrypcja konwersacji, haki monitów również otrzymują narzędzia ReadFile i GrepSearch, co pozwala LLM analizować pełną historię konwersacji.

Haki poleceń są lepsze w przypadku testów deterministycznych, takich jak weryfikowanie, czy odpowiedź zawiera wymagane znaczniki, blokowanie niebezpiecznych poleceń lub użycie narzędzia rejestrowania w systemie zewnętrznym.

Zachowanie agenta z punktami zaczepiania i bez

W poniższej tabeli porównuje się zachowanie agenta z hakami i bez nich.

Bez haków	Z hakami
Agent decyduje, kiedy jest "gotowe"	Definiujesz, co oznacza "gotowe"
Użycie narzędzia jest niewidoczne	Każde wywołanie narzędzia może być audytowane.
Niebezpieczne polecenia są kontynuowane w trybie dyskretnym	Wymuszanie zasad blokuje je automatycznie
Jakość zależy wyłącznie od samego projektowania promptów.	Automatyczne zapory jakości wychwytują luki

Hooki nie zastępują mechanizmów bezpieczeństwa trybu działania. Zamiast tego uzupełniają je. Tryby uruchamiania kontrolują , co może zrobić agent. Hooki kontrolują , jak dobrze to działa i co się dzieje z wynikami.

Przed i po dodaniu haków agenta

Scenario	przed	po
Jakość odpowiedzi	Agent zatrzymuje się, gdy myśli, że zadanie zostało ukończone	Twój hak zatrzymania weryfikuje kompletność przed dotarciem odpowiedzi do użytkowników
Widoczność narzędzia	Brak śledzenia wykonania narzędzia	PostToolUżyj dziennik punktów zaczepienia i zweryfikuj każde wywołanie narzędzia
Wymuszanie zasad	Niebezpieczne polecenia są uruchamiane niezaznaczone	Skrypty automatycznie blokują `rm -rf`, `sudo` i inne ryzykowne wzorce
Kontrola jakości	Inżynieria promptu jest jedyną dźwignią	Hooki oparte na LLM oceniają niuanse; skrypty wymuszają reguły deterministyczne

Konfigurowanie punktów zaczepienia agenta

Tworzenie punktów zaczepienia za pośrednictwem interfejsu użytkownika portalu:

Haki na poziomie agenta: Przejdź do Konstruktora → Punkty zaczepienia → wybierz Utwórz punkt zaczepienia.
Haczyki na poziomie agenta niestandardowego: Przejdź do Agent Canvas → wybierz agenta niestandardowego → Zarządzaj haczykami.

Aby uzyskać instrukcje krok po kroku, zobacz Tworzenie punktów zaczepienia i zarządzanie nimi w portalu.

Wskazówka

Punkty zaczepienia można również skonfigurować za pomocą interfejsu API REST w wersji 2 przy użyciu polecenia PUT /api/v2/extendedAgent/agents/{agentName}. Format YAML w poniższej sekcji przedstawia pełny schemat konfiguracji. Aby dowiedzieć się więcej, zobacz samouczek dotyczący interfejsu API.

Zakładka Agent Canvas YAML wyświetla format v1 i nie pokazuje hooków. Użyj strony Haki w obszarze Konstruktor , aby wyświetlić haki i zarządzać nimi.

W poniższym przykładzie przedstawiono pełną konfigurację punktów zaczepienia:

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

Format odpowiedzi haka

Hooki muszą zwracać JSON. Obsługiwane są dwa formaty:

Prosty format (zalecany w przypadku punktów zaczepienia monitów):

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

Rozszerzony format (zalecany dla hooków poleceń):

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

Haczyki poleceń mogą również używać kodów wyjścia zamiast wyjścia JSON.

Kod zakończenia	Zachowanie
`0` bez danych wyjściowych	Zezwalaj (bez sprzeciwu)
`0` z formatem JSON	Analizowanie kodu JSON na potrzeby decyzji
`2`	Zawsze blokuj. stderr staje się przyczyną
Other	Używa `failMode` ustawienia (`allow` lub `block`)

Ostrzeżenie

W przypadku haków stop, odrzucenie bez powodu jest traktowane jako zatwierdzenie, a agent zatrzymuje się w normalny sposób. Zawsze podaj reason pole podczas odrzucania.

Uwaga / Notatka

Można zdefiniować wiele punktów zaczepienia dla tego samego zdarzenia. Każdy uchwyt z odpowiednim wzorcem matcher w narzędziu PostToolUse działa niezależnie. Jeśli wiele punktów zaczepienia zapewnia additionalContext, kontekst ostatniego haka zostanie wstrzyknięty do konwersacji.

Dokumentacja konfiguracji

W poniższej tabeli opisano wszystkie dostępne opcje konfiguracji punktów zaczepienia.

Option	Typ	Wartość domyślna	Opis
`type`	ciąg	`prompt`	`prompt` lub `command`
`prompt`	ciąg	(brak)	Tekst monitu LLM (wymagany w przypadku punktów zaczepienia monitu). Użyj `$ARGUMENTS` do wstrzykiwania kontekstu.
`command`	ciąg	(brak)	Wbudowane polecenie powłoki (do użycia w hakach poleceń, wykluczające się z `script`).
`script`	ciąg	(brak)	Skrypt wielowierszowy (w przypadku punktów zaczepienia poleceń wzajemnie wykluczających się za pomocą polecenia `command`).
`matcher`	ciąg	(brak)	Wzorzec wyrażeń regularnych dla nazw narzędzi (wymagane dla hooków PostToolUse). `*` pasuje do wszystkich narzędzi. Wzorce są zakotwiczone jako `^(pattern)$` i dopasowane z uwzględnieniem wielkości liter. Wartość pusta lub null nie pasuje do niczego.
`timeout`	int	`30`	Limit czasu wykonywania w sekundach (musi być dodatni; wartości powyżej 300 są oflagowane podczas walidacji interfejsu wiersza polecenia).
`failMode`	ciąg	`allow`	Jak obsługiwać błędy hooków: `allow` lub `block`.
`model`	ciąg	`ReasoningFast`	Model dla haczyków monitów (nazwa scenariusza lub nazwa wdrożenia).
`maxRejections`	int	`3` (ustawienie domyślne agenta)	Maksymalna ilość odrzuceń przed wymuszonym zatrzymaniem. Zakres: od 1 do 25. Dotyczy tylko haczyków zatrzymania typu prompt. Haki zatrzymania typu komenda nie mają niejawnego limitu. Gdy wiele punktów zaczepienia monitu określi różne wartości, zostanie użyta wartość maksymalna.

Schemat kontekstu haka

"Hooki otrzymują ustrukturyzowany kontekst JSON dotyczący bieżącego zdarzenia." Haczyki monitów odbierają kontekst za pomocą symbolu zastępczego $ARGUMENTS w tekście monitora. Haki poleceń odbierają kontekst jako kod JSON w pliku stdin.

W przypadku obu typów zaczepów execution_summary pole zawiera ścieżkę pliku do transkrypcji konwersacji (a nie zawartości osadzonej). W przypadku prompt hooks usługa LLM odbiera ReadFile i GrepSearch narzędzia do uzyskiwania dostępu do tego pliku. W przypadku hooków poleceń plik jest dostępny w określonej ścieżce w sandboxie.

Typowe pola

Wszystkie hooki otrzymują następujące pola:

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

Zatrzymaj pola punktów zaczepienia

Stop hooki otrzymują dodatkowe pola dotyczące ostatecznych danych wyjściowych agenta.

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

PostToolUżyj pola punktów zaczepienia

PostTool Use haki otrzymują dodatkowe pola związane z wykonywaniem narzędzia.

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

Poziomy modelu

Hooki promptów wykorzystują model AI do oceny zachowania agenta. Możesz wybrać, którego poziomu modelu używa hook, zachowując równowagę między jakością oceny a kosztem i opóźnieniem.

Warstwa	Najlepsze dla	Kompromis
Reasoning	Złożone wymuszanie zasad, wieloetapowa weryfikacja, zniuansowane kontrole zgodności	Najwyższa jakość, wyższy koszt i opóźnienie
Szybkie rozumowanie (ustawienie domyślne)	Większość punktów zaczepienia, walidacja odpowiedzi, kontrole inspekcji, wymuszanie bezpieczeństwa	Dobre rozumowanie z małym opóźnieniem
Ogólne przeznaczenie	Proste kontrole formatu, podstawowa weryfikacja zgodności	Zrównoważona dokładność, koszt i szybkość
Szybko	Uproszczone kontrole, sprawdzanie obecności, weryfikacja formatu	Najniższy koszt, najszybsza odpowiedź
Długi kontekst	Mechanizmy przetwarzające obszerne dane wyjściowe, pełną analizę dokumentów i rozbudowane wyniki narzędzi	Obsługuje większe dane wejściowe, wyższe koszty

Wskazówka

Hooki są domyślnie ustawione na Fast Reasoning, ponieważ są uruchamiane przy każdej odpowiedzi agenta i każdym wywołaniu narzędzia, dlatego niskie opóźnienie ma znaczenie. Używaj Rozumowania tylko w przypadku hooków wymuszających złożone zasady tam, gdzie dokładność ma kluczowe znaczenie.

Limity

Następujące limity dotyczą punktów zaczepienia agentów.

Limit	Wartość
Rozmiar skryptu	Maksymalna 64 KB
Przerwa czasowa	Od 1 do 300 sekund
Maksymalna liczba odrzuceń (uruchomienie zatrzymywania wyzwalaczy)	Od 1 do 25 (wartość domyślna: 3)
Obsługiwane skrypty — shebangs	`#!/bin/bash`, `#!/usr/bin/env python3`
Środowisko wykonywania skryptu	Interpreter kodu w trybie piaskownicy

Przykład: Inspekcja użycia wszystkich narzędzi

Następujący hak PostToolUse rejestruje każde użycie narzędzia i dodaje komunikat kontekstu audytu.

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))

Pole additionalContext jest dodawane jako komunikat użytkownika do konwersacji, co daje agentowi wgląd w dziennik inspekcji.

Przykład: wymaganie znacznika ukończenia

Następujący hook Zatrzymania odrzuca odpowiedzi, które nie kończą się ciągiem "Zadanie ukończone".

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

Najlepsze rozwiązania

Podczas konfigurowania punktów zaczepienia agenta:

Zawsze podaj powód podczas odrzucania. Traktuj odrzucenia bez powodów jako zatwierdzenia.
Użyj odpowiednich limitów czasu: Długotrwałe hooki spowalniają wykonywanie agenta.
Obsługa błędów w sposób bezpieczny: używaj failMode: allow , chyba że wymagane jest ścisłe wymuszanie.
Bądź precyzyjny z matcherami: Zbyt szerokie matchery PostToolUse mogą powodować problemy z wydajnością.
Dokładnie przetestuj haki: Haki, które zawsze odrzucają, mogą powodować pętle (ograniczane przez maxRejections).
Zaloguj się do narzędzia stderr: użyj narzędzia stderr do debugowania danych wyjściowych. System analizuje stdout jako wynik hooka.

Spróbuj samodzielnie podłączyć agenta

Poniższy zrzut ekranu przedstawia działanie hak zatrzymania. Agent początkowo odpowiada za pomocą ciągu "4", ale punkt zaczepienia odrzuca odpowiedź, ponieważ brakuje znacznika ukończenia. Następnie agent przechodzi do dodania znacznika.

Wprowadzenie

Resource	Czego się uczysz
Tworzenie punktów zaczepienia i zarządzanie nimi (portal)	Wizualne tworzenie punktów zaczepienia w interfejsie użytkownika portalu bez wywołań interfejsu API.
Konfigurowanie punktów zaczepienia agenta (API)	Skonfiguruj punkty zaczepienia przy użyciu interfejsu API REST w wersji 2 i YAML.

Zdolność	Jak to się wiąże
Tryby uruchamiania	Haki uzupełniają mechanizmy kontroli bezpieczeństwa trybu uruchamiania. Tryby kontrolują co działa, haki kontrolują jak dobrze to działa.
Narzędzia języka Python	Tworzenie niestandardowych narzędzi, które można podłączyć do inspekcji i weryfikowania.

Opinia

Czy ta strona była pomocna?

Last updated on 2026-06-04