Samouczek: tworzenie punktów zaczepienia i zarządzanie nimi w portalu

W tym samouczku utworzysz dwa mechanizmy ładu przy użyciu portalu: punkt zaczepienia Stop, który wymusza formatowanie danych (tabele markdown z pogrubionymi nagłówkami) i punkt zaczepienia PostToolUse, który blokuje niebezpieczne polecenia powłoki. Konfigurowanie zaczepów odbywa się zarówno na poziomie agenta (dotyczy wszystkich wątków i podagentów), jak i na poziomie podagentu (dotyczy jednego określonego podagentu).

Szacowany czas: 10 minut

W tym poradniku nauczysz się, jak:

Wymagania wstępne

• Agent Azure SRE w stanie Uruchomiony
• Rola współautora lub nowsza w zasobie agenta SRE

Informacje o miejscu, w którym działają haki w portalu

Hooki operują na dwóch poziomach. Zrozumienie tego rozróżnienia jest kluczową koncepcją architektury.

Tworzenie punktów zaczepienia na poziomie agenta

Haczyki na poziomie agenta mają zastosowanie do całego agenta, w tym do każdego wątku i każdego podagenta. Mają tryby aktywacji, które kontrolują, kiedy są aktywne.

Otwórz stronę Hooki

Wykonaj następujące kroki, aby przejść do strony z hakami.

1. Przejdź do sre.azure.com i wybierz agenta.
2. W pasku bocznym wybierz Build + setup, a następnie rozwiń Extensions.
3. Wybierz pozycję Haki.

Zostanie wyświetlony nagłówek Haki z opisem, przyciskiem Utwórz punkt zaczepienia i pustą siatką danych (lub listą istniejących punktów zaczepienia).

Tworzenie haka zatrzymania

Mechanizm zatrzymania uruchamia się, gdy agent jest gotowy zwrócić ostateczną odpowiedź. Służy do weryfikowania jakości odpowiedzi i wymuszania reguł formatowania.

1. Wybierz Utwórz hook.

2. Wypełnij pola formularza:

   Pole	Wartość
   Nazwa	require-table-format
   Typ zdarzenia	Zatrzymaj
   Tryb aktywacji	Zawsze
   Opis	Gwarantuje, że odpowiedzi zawierają dane ustrukturyzowane jako tabele w formacie markdown z pogrubionymi nagłówkami

3. W obszarze Definicja hooka zachowaj typ hooka ustawiony na Prompt.

4. Zachowaj ustawienie Model na Szybkie rozumowanie (ustawienie domyślne).

5. W edytorze Monit wprowadź następujący tekst:

   Check the agent response below.
   
   $ARGUMENTS
   
   Does the response present any structured data (lists of items, comparisons, metrics) as a markdown table with **bold** column headers?
   If no structured data is present, approve.
   If structured data IS present as a table with bold headers: {"ok": true}
   If structured data is present but NOT formatted as a table: {"ok": false, "reason": "Reformat the structured data as a markdown table with **bold** column headers."}
   

6. Pozostaw limit czasu (s) w 30, tryb niepowodzenia w Allow, a maksymalną liczbę odrzuceń na 3.

7. Wybierz opcję Zapisz.

Okno dialogowe zamknie się z komunikatem informującym o sukcesie. Punkt zaczepienia wyświetla się w tabeli z typem zdarzenia Zatrzymaj i aktywacją Zawsze.

Testowanie zaczepienia zatrzymywania

Wykonaj następujące kroki, aby sprawdzić, czy funkcja zatrzymania działa poprawnie.

1. Wróć do głównej nawigacji za pomocą Wstecz, a następnie wybierz Nowy czat.
2. Wpisz Porównaj zalety i wady języka Python vs Go w celu utworzenia mikrousług i wybierz pozycję Wyślij.
3. Obejrzyj odpowiedź agenta:
   • Agent początkowo odpowiada za pomocą porównania zwykłego tekstu.
   • Stop hook ocenia i odrzuca odpowiedź, ponieważ dane nie znajdują się w tabeli.
   • Agent ponownie formatuje odpowiedź jako tabelę markdown z pogrubionymi nagłówkami.

Ostateczna odpowiedź przedstawia porównanie jako sformatowaną tabelę podobną do poniższego przykładu:

Utwórz hook PostToolUse

Hak PostToolUse jest wywoływany po zakończeniu działania narzędzia. Służy do inspekcji użycia narzędzi, blokowania niebezpiecznych poleceń lub dodawania dodatkowego kontekstu.

1. Wróć do Build + setup>Extensions>Hooks.

2. Wybierz Utwórz hook.

3. Wypełnij formularz:

   Pole	Wartość
   Nazwa	block-dangerous-commands
   Typ zdarzenia	Użycie narzędzia post
   Tryb aktywacji	Zawsze
   Opis	Blokuje rm -rf, sudo i chmod 777 w komendach powłoki
   Typ haka	Polecenie
   Dopasowywarka narzędzi	Bash\|ExecuteShellCommand

4. Wybierz język Python jako język skryptu.

5. W edytorze skryptów wprowadź następujący skrypt:

   #!/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"}))
   

6. Ustaw Tryb awarii na Blokuj (jeśli skrypt ulegnie awarii, wynik narzędzia zostanie zablokowany).

7. Wybierz opcję Zapisz.

Oba hooki są teraz wyświetlane w siatce danych Hooks.

Testowanie haków PostToolUse

Wykonaj następujące kroki, aby sprawdzić, czy punkt zaczepienia PostToolUse działa poprawnie.

1. Wróć do głównej nawigacji za pomocą przycisku Wstecz, a następnie wybierz Nowy czat.
2. Poproś agenta o uruchomienie bezpiecznego polecenia: "Uruchom echo hello". Hak umożliwia to polecenie.
3. Poproś agenta o uruchomienie niebezpiecznego polecenia: "Uruchom polecenie rm -rf /tmp/test". Hak blokuje to polecenie.

Bezpieczne polecenie działa normalnie. Niebezpieczne polecenie jest blokowane, a agent otrzymuje komunikat wyjaśniający, dlaczego.

Edytowanie i usuwanie punktów zaczepienia na poziomie agenta

Istniejące hooki można modyfikować lub usuwać z tabeli danych Hooki.

• Edytuj: wybierz ikonę edycji w dowolnym wierszu zaczepienia w siatce danych, zmodyfikuj pola i wybierz pozycję Zapisz.
• Usuń: zaznacz pole wyboru obok punktów zaczepienia, które chcesz usunąć, wybierz pozycję Usuń na pasku narzędzi i potwierdź.

Tabela danych natychmiast odzwierciedla wprowadzone zmiany.

Tworzenie hooków na poziomie subagentów

Konfigurujesz haczyki na poziomie podagentów bezpośrednio w definicji podagentu. Mają zastosowanie tylko wtedy, gdy działa ten konkretny podagent, nie zaś główny agent lub inne podagenty.

Otwórz panel haków podagentów

Wykonaj następujące kroki, aby uzyskać dostęp do konfiguracji punktów zaczepienia dla określonego podagentu.

1. W pasku bocznym wybierz Build + setup, rozwiń Workflows i wybierz Agent Canvas.
2. Wybierz istniejący subagent, aby go edytować, lub wybierz pozycję Utwórz , aby rozpocząć nową.
3. W formularzu podrzędnym przewiń w dół do sekcji Haki .
4. Wybierz pozycję Zarządzaj punktami zaczepienia.

Zostanie otwarty panel boczny z sekcjami Zatrzymaj i Po użyciu narzędzia. Jeśli nie skonfigurowano żadnych punktów zaczepienia, zobaczysz puste stany z tekstem wskazówek.

Dodaj uchwyt do podagentu

W poniższych krokach dodano hak zatrzymania, który gwarantuje, że ten subagent zawsze odpowiada sekcją podsumowania.

1. W panelu Zarządzanie punktami zaczepienia wybierz pozycję Dodaj punkt zaczepienia w dolnej części panelu.

2. W oknie dialogowym wypełnij formularz hook:

   Pole	Wartość
   Typ zdarzenia	Zatrzymaj
   Typ haka	Podpowiedź
   Polecenie	Check the response below. $ARGUMENTS Does it include a clear summary section at the end? If yes: {"ok": true} If no: {"ok": false, "reason": "Add a Summary section at the end of your response."}
   Limit czasu (s)	30
   Tryb awaryjny	Allow
   Maksymalna liczba odrzuconych	3

3. Wybierz pozycję Zapisz na haku.

4. Wybierz pozycję Utwórz (lub Zapisz) w podagentze, aby zapisać pełną konfigurację.

Uchwyt zostanie wyświetlony w panelu Zarządzanie uchwytami w sekcji Zatrzymywanie. Formularz podrzędny zawiera pozycję Zarządzaj punktami zaczepienia (1) na przycisku.

Zarządzanie hookami dla wątku

Haki na poziomie agenta z aktywacją Zawsze są domyślnie aktywne w każdej konwersacji. Należy ręcznie aktywować haki przy użyciu aktywacji na żądanie dla każdego wątku.

Przełączanie haków w konwersacji

Wykonaj następujące kroki, aby aktywować lub dezaktywować haki w określonym wątku.

1. Otwórz wątek czatu .
2. Wybierz przycisk + w stopce czatu.
3. Wybierz pozycję Zarządzaj punktami zaczepienia.
4. Włącz lub wyłącz haki dla bieżącego wątku.

Można tymczasowo dezaktywować Always hooki. W razie potrzeby można aktywować On Demand hooki. Nie można aktywować ani dezaktywować wymaganych haków systemowych.

Zmiany haka są stosowane natychmiast w bieżącym wątku.

Troubleshooting

W poniższej tabeli wymieniono typowe problemy i rozwiązania podczas tworzenia punktów zaczepienia i zarządzania nimi w portalu.

Następne kroki

Treści powiązane

• Przegląd możliwości zaczepów agenta
• Samouczek: konfigurowanie punktów zaczepienia agenta za pośrednictwem interfejsu API REST
• Tryby uruchamiania