Samouczek: konfigurowanie punktów zaczepienia agenta (API) w agencie usługi Azure SRE

Wskazówka

Preferuj interfejs użytkownika portalu? Teraz możesz tworzyć haki i zarządzać nimi bezpośrednio w portalu bez korzystania z interfejsu API REST. Portal udostępnia formularz wizualny i edytor kodu. Żadne polecenia curl nie są wymagane.

W tym samouczku utworzysz agenta niestandardowego z zaczepem Stop, który wymusza dodawanie markera zakończenia do każdej odpowiedzi. Możesz skonfigurować punkt zaczepienia za pośrednictwem interfejsu API REST, a następnie przetestować go na placu zabaw portalu.

Szacowany czas: 15 minut

Uwaga / Notatka

Haki na poziomie agenta a haki na poziomie niestandardowego agenta: Ten samouczek tworzy haki na agencie niestandardowym (haki na poziomie niestandardowego agenta). Te haki są uruchamiane tylko wtedy, gdy ten konkretny agent niestandardowy jest uruchamiany.

Aby utworzyć haki na poziomie agenta , które mają zastosowanie do całego agenta (wszystkie wątki, wszystkie agenci niestandardowi), użyj narzędzia Builder>Hooks w portalu.

Level	Jak utworzyć	Scope
Poziom agenta	Portal: Konstruktora Haków >	Dotyczy wszystkich wątków i agentów niestandardowych
Poziom agenta indywidualnego	Interfejs API REST (ten samouczek) lub portal: Płótno agenta > niestandardowy agent > — zarządzanie hookami	Dotyczy tylko jednego agenta niestandardowego

W tym poradniku nauczysz się, jak:

Tworzenie agenta niestandardowego za pomocą elementu stop hook przy użyciu interfejsu API REST
Testowanie zachowania haka w środowisku testowym portalu
Dodaj hak PostToolUse do audytu użycia narzędzia
Blokuj niebezpieczne polecenia za pomocą haka zasad

Wymagania wstępne

Agent Azure SRE w stanie Uruchomiony
polecenie curl w celu wywołania interfejsu API REST
Zalogowano do Azure CLI (az login) w celu uzyskania tokenu dostępu

Omówienie formatu interfejsu API punktów zaczepienia

W tym samouczku użyto interfejsu API REST w wersji 2 do tworzenia punktów zaczepienia na agencie niestandardowym. Karta edytora YAML w portalu pokazuje format v1 i nie wyświetla hooków skonfigurowanych przez API, ale hooki wciąż są aktywne. Możesz je sprawdzić na stronie Builder Hooks>, lub w placu zabaw testowym.

Wskazówka

Kiedy należy używać interfejsu API a portalu:

Portal (narzędzia Builder > Hooks): najlepsze w przypadku punktów zaczepienia na poziomie agenta w formie wizualnej. Żaden kod nie jest konieczny.
Interfejs API (ten samouczek): najlepsze rozwiązanie w przypadku niestandardowego agenta, potoków CI/CD lub zarządzania programistycznego.

Znajdowanie adresu URL interfejsu API agenta

Podstawowy adres URL interfejsu API agenta jest zgodny z tym wzorcem:

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

Aby go znaleźć:

Otwórz sre.azure.com i wybierz agenta.
Na lewym pasku bocznym wybierz Konstruktor>Kanwa Agenta.
Otwórz narzędzia deweloperskie przeglądarki (F12 lub kliknij prawym przyciskiem myszy pozycję > Sprawdź).
Przejdź do karty Sieć, przefiltruj według ciągu "api" i wyszukaj żądania do adresu URL kończącego się na ..azuresre.ai
Podstawowy adres URL to wszystko przed /api/....

Alternatywnie sprawdź atrybut src na karcie Elementy. Znajdź <iframe>, którego src zaczyna się od https://{agent-name}--.

Pobranie tokenu dostępu

Uruchom następujące polecenie, aby uzyskać token dostępu dla interfejsu API agenta SRE:

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

Tworzenie agenta niestandardowego z użyciem stopera lub haka zatrzymania

Ten krok tworzy agenta niestandardowego o nazwie my_hooked_agent z hakiem zatrzymania, który sprawdza, czy odpowiedź kończy się na === RESPONSE COMPLETE ===. Jeśli brakuje znacznika, punkt zaczepienia odrzuca odpowiedź i nakazuje agentowi dodanie znacznika.

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

Otrzymasz komunikat HTTP 202 Zaakceptowano z pełną konfiguracją agenta w treści odpowiedzi.

W poniższym przykładzie pokazano tę samą konfigurację w formacie YAML w wersji 2, aby uzyskać informacje referencyjne:

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 działa hak zatrzymania

Hak zatrzymania ocenia odpowiedź agenta, zanim zostanie zwrócona użytkownikowi.

$ARGUMENTS Zastępuje kod JSON kontekstu zaczepienia, który zawiera ostateczną odpowiedź agenta.
Funkcja LLM ocenia monit i zwraca wartość {"ok": true} lub {"ok": false, "reason": "..."}.
Jeśli agent zostanie odrzucony, będzie nadal działać po dodaniu przyczyny jako komunikatu użytkownika.
Po trzech odrzuceniach (wartość domyślna) agent się zatrzymuje.

Testowanie haka w portalu

Wykonaj następujące kroki, aby przetestować mechanizm zatrzymania:

Przejdź do swojego agenta w portalu i wybierz opcję Budowniczy>Kanwa agenta.
Wybierz przycisk radiowy Test playground.
Wybierz listę rozwijaną Subagent/Tool , znajdź my_hooked_agent i wybierz pozycję Zastosuj.
Wpisz What is 2+2? na czacie i wybierz Wyślij.

Obejrzyj, co się stanie:

Agent najpierw odpowiada numerem 4.
"Stop hook" ocenia i odrzuca odpowiedź (brak znacznika ukończenia).
Pojawi się krok procesu myślowego, w którym agent kontynuuje działanie.
Zostanie wyświetlona ostateczna odpowiedź: 4 - UKOŃCZ ODPOWIEDŹ ..

Hak zadziałał. Przymusiło agenta do dodania znacznika przed zatrzymaniem.

Dodaj hook PostToolUse w celu audytowania

Dodaj punkt zaczepienia PostToolUse, który rejestruje każde narzędzie używane przez agenta. Zaktualizuj tego samego agenta, wysyłając nowe PUT żądanie przy użyciu obu hooków:

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: "*" oznacza, że ten hook działa przy każdym uruchomieniu narzędzia. Skrypt rejestruje nazwę narzędzia i wprowadza [AUDIT] komunikat do konwersacji.

Aby przetestować punkt zaczepienia, zadaj agentowi pytanie, które wyzwala narzędzie (na przykład "Uruchom echo hello").

Blokuj niebezpieczne polecenia

Dodaj drugi haczyk PostToolUse, który blokuje rm -rf, sudo i 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"}))

Kluczowe różnice między hakiem audytowym:

matcher: "Bash|ExecuteShellCommand" jest uruchamiany tylko dla narzędzi powłoki (wzorzec jest zakotwiczony jako ^(Bash|ExecuteShellCommand)$).
failMode: block blokuje wynik narzędzia, jeśli sam skrypt ulegnie awarii (tryb ścisły).
Zwraca "block" z powodem, gdy zostanie znaleziony niebezpieczny wzorzec.

Formaty odpowiedzi punktów zaczepienia

Haki monitów i haki poleceń używają różnych formatów odpowiedzi.

Punkty zaczepienia dla monitów

Monity zaczepienia zwracają prosty kod JSON:

{"ok": true}

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

Haki poleceń

Haki poleceń zwracają rozszerzony JSON.

{"decision": "allow"}

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

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

Hooki komend mogą również używać kodów wyjścia zamiast formatu JSON.

Kod zakończenia	Zachowanie
`0` bez danych wyjściowych	Allow
`0` z formatem JSON	Analizowanie kodu JSON
`2`	Blokada (stderr jako przyczyna)
Other	Wraca do `failMode`

Ostrzeżenie

Odrzucenie bez powodu jest traktowane jako zatwierdzenie. Zawsze dołączaj reason podczas odrzucania.

Zweryfikować

Po skonfigurowaniu i przetestowaniu punktów zaczepienia potwierdź następujące warunki:

Niestandardowe haki na poziomie agenta można skonfigurować przy użyciu interfejsu API REST w wersji 2. Mają zastosowanie tylko do tego agenta niestandardowego.
Tworzysz haki na poziomie agenta w narzędziach Builder > Hooks. Mają zastosowanie w całym agencie.
Hak zatrzymania powoduje, że agent dodaje znacznik === RESPONSE COMPLETE === przed zatrzymaniem.
Zaczepienie audytu PostToolUse rejestruje dzienniki [AUDIT] dla wywołań narzędzi.
Mechanizm zasad blokuje niebezpieczne polecenia, takie jak rm -rf i sudo.

Troubleshooting

W poniższej tabeli wymieniono typowe problemy i rozwiązania dotyczące punktów zaczepienia agenta.

Problem	Rozwiązanie
Haki nie są widoczne w zakładce YAML w portalu	Oczekiwano — karta YAML wyświetla tylko wersję v1. Niestandardowe hooki na poziomie agenta utworzone za pośrednictwem interfejsu API są aktywne i widoczne w Builder>Hooks lub playground.
`Unsupported kind: ExtendedAgent`	Użyj punktu końcowego v2: `PUT /api/v2/extendedAgent/agents/{name}`.
`Handoffs cannot be null`	Dodaj `"handoffs": []` do ładunku JSON.
Hook nie ma żadnego wpływu	Uwzględnij `reason` pole podczas odrzucania. Bez niego odrzucenie jest traktowane jako zatwierdzenie.
Agent wykonuje pętlę w nieskończoność	Dolna `maxRejections` (wartość domyślna: 3, zakres: 1–25).

Następne kroki

Dowiedz się więcej o punktach zaczepienia agentów.

Opinia

Czy ta strona była pomocna?

Last updated on 2026-03-27