Pengait agen di Azure SRE Agent

Hook adalah titik pemeriksaan kustom yang mencegat dan mengontrol perilaku agen pada momen-momen kunci. Gunakan kait untuk memberlakukan gerbang kualitas pada respons agen, mengaudit dan mengontrol penggunaan alat, memblokir operasi berbahaya dengan memberlakukan kebijakan, dan mencegah penyelesaian tugas awal dengan memvalidasi output agen.

Masalahnya

Agen Anda menjalankan tugas secara otonom - menyelidiki insiden, menjalankan alat, dan menghasilkan respons. Tetapi otonomi tanpa pengawasan menciptakan risiko:

Respons yang tidak lengkap: Agen mengatakan "selesai" sebelum mengatasi semua yang Anda minta.
Penggunaan alat yang tidak diaudit: Anda tidak memiliki visibilitas ke alat mana yang dipanggil agen atau hasil apa yang didapatkannya.
Tidak ada penegakan kebijakan: Operasi berbahaya (perintah destruktif, perubahan yang tidak sah) berjalan tanpa pengawasan.
Kesenjangan kualitas: Respons melewatkan informasi penting karena tidak ada langkah validasi.

Anda memerlukan cara untuk mencegat perilaku agen pada saat-saat utama tanpa memperlambatnya atau menghapus otonominya sepenuhnya.

Cara kerja pengait agen

Hook adalah titik pemeriksaan kustom yang Anda lampirkan ke peristiwa agen tertentu. Ketika peristiwa terjadi, hook Anda mengevaluasi situasi dan memutuskan apakah akan mengizinkan atau memblokir tindakan.

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

Dua acara kait didukung saat ini:

Event	Memicu ketika	Apa yang dapat Anda lakukan
Stop	Agen akan mengembalikan respons akhir	Memvalidasi kelengkapan, menolak, dan memaksa agen untuk melanjutkan
PostToolUse	Alat tersebut berhasil mengeksekusi dengan sukses	Penggunaan audit, hasil blokir, menyuntikkan konteks tambahan

Dua tingkat kait

Kait beroperasi pada dua tingkat:

Tingkat	Tempat untuk mengonfigurasi	Ruang lingkup
Tingkat agen	Builder → Hooks pada portal	Berlaku untuk seluruh agen termasuk semua utas dan semua agen kustom
Tingkat agen khusus	Agen Canvas → Agen Kustom → Mengelola Hooks, atau melalui REST API v2	Hanya berlaku ketika agen kustom tertentu berjalan

Kedua tingkat dapat berdampingan. Jika kait tingkat agen dan kait tingkat agen kustom sama-sama cocok dengan kejadian yang sama, keduanya dijalankan. Kait tingkat agen menembak terlebih dahulu.

Jenis eksekusi

Anda dapat menerapkan kait dengan menggunakan LLM atau skrip shell:

Tipe	Cara kerjanya	Paling cocok untuk
Petunjuk	Model Bahasa Alamiah (LLM) mengevaluasi prompt Anda dan memberikan keputusan dalam format JSON.	Validasi mendalam ("Apakah respons ini lengkap?")
Perintah	Skrip bash atau Python berjalan di lingkungan terisolasi	Pemeriksaan deterministik, penegakan kebijakan, audit

Kait prompt sangat kuat untuk evaluasi subjektif, seperti memeriksa apakah respons membahas semua masalah pengguna atau memverifikasi bahwa penyelidikan sudah cukup menyeluruh. Mereka menggunakan $ARGUMENTS tempat penampung untuk menerima konteks hook penuh. Jika $ARGUMENTS tidak ada dalam perintah, konteks ditambahkan secara otomatis. Saat transkrip percakapan tersedia, pengait prompt juga menerima alat ReadFile dan GrepSearch, yang memungkinkan LLM menalar tentang riwayat percakapan lengkap.

Kait perintah lebih baik untuk pemeriksaan deterministik, seperti memvalidasi bahwa respons berisi penanda yang diperlukan, memblokir perintah berbahaya, atau pengelogan penggunaan alat ke sistem eksternal.

Apa yang membuat pendekatan ini berbeda

Tabel berikut membandingkan perilaku agen dengan dan tanpa kait.

Tanpa kait	Dengan kait
Agen memutuskan kapan "selesai"	Anda mendefinisikan apa arti "selesai"
Penggunaan alat tidak terlihat	Setiap panggilan alat dapat diaudit
Perintah berbahaya dilanjutkan secara diam-diam	Penegakan kebijakan memblokirnya secara otomatis
Kualitas tergantung pada rekayasa yang cepat saja	Gerbang kualitas otomatis menangkap celah

Hook tidak menggantikan kontrol keamanan mode run - mereka melengkapinya. Jalankan mode mengontrol apa yang dapat dilakukan agen. Pengait mengontrol seberapa baik fungsi bekerja dan apa yang terjadi dengan hasilnya.

Sebelum dan sesudah

Skenario	Sebelumnya	Sesudah
Kualitas respons	Agen berhenti ketika mengira tugasnya selesai	Stop hook Anda memvalidasi kelengkapan sebelum respons menjangkau pengguna
Visibilitas perangkat	Tidak ada rekam jejak audit eksekusi alat	PostToolUse menghubungkan log dan memverifikasi setiap panggilan alat
Penegakan kebijakan	Perintah berbahaya dijalankan tanpa pemeriksaan	Skrip memblokir `rm -rf`, `sudo`, dan pola berisiko lainnya secara otomatis
Jaminan kualitas	Prompt engineering adalah satu-satunya alat Anda	Kait berbasis LLM mengevaluasi nuansa; skrip memberlakukan aturan deterministik

Mengonfigurasi kait

Cara termudah untuk membuat kait adalah melalui antarmuka portal:

Hook tingkat agen: Buka Builder → Hooks → pilih Ciptakan hook.
Kait tingkat agen kustom: Buka Kanvas Agen → pilih agen kustom → Kelola Kait.

Petunjuk / Saran

Anda juga dapat mengonfigurasi kait melalui REST API v2 dengan menggunakan PUT /api/v2/extendedAgent/agents/{agentName}. Format YAML di bagian berikut menunjukkan skema konfigurasi lengkap. Untuk mempelajari lebih lanjut, lihat tutorial API.

Tab YAML Kanvas Agen menampilkan format v1 dan tidak menampilkan kait. Gunakan halaman Hooks di bawah Builder untuk melihat dan mengelola hooks.

Contoh berikut menunjukkan konfigurasi kait lengkap:

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 respon hook

Hook harus mengeluarkan JSON. Dua format didukung.

Format sederhana (disarankan untuk kait prompt):

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

Format yang diperluas (disarankan untuk kait perintah):

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

Kait perintah juga dapat menggunakan kode keluar alih-alih output JSON:

Kode keluar	Perilaku
`0` tanpa output	Izinkan (tidak ada keberatan)
`0` dengan JSON	Mengurai JSON untuk keputusan
`2`	Selalu blokir. stderr adalah penyebab
Other	Menggunakan pengaturan `failMode` (`allow` atau `block`)

Perhatian

Untuk Stop hook, penolakan tanpa alasan dianggap sebagai persetujuan, dan agen berhenti beroperasi secara normal. Selalu sediakan reason kolom ketika menolak.

Nota

Anda dapat menentukan beberapa kait untuk peristiwa yang sama. Untuk PostToolUse, setiap hook dengan pola pencocokan matcher berjalan secara independen. Jika beberapa hook menyediakan additionalContext, konteks dari hook terakhir disuntikkan ke dalam percakapan.

Referensi konfigurasi

Tabel berikut ini menjelaskan semua opsi konfigurasi kait yang tersedia.

Option	Tipe	Default	Deskripsi
`type`	string	`prompt`	`prompt` atau `command`
`prompt`	string	—	Teks perintah LLM (diperlukan untuk kait perintah). Gunakan `$ARGUMENTS` untuk injeksi konteks.
`command`	string	—	Perintah shell sebaris (untuk kait perintah, saling eksklusif dengan `script`).
`script`	string	—	Skrip multibaris (untuk kait perintah, saling eksklusif dengan `command`).
`matcher`	string	—	Pola regex untuk nama alat (diperlukan untuk hook PostToolUse). `*` cocok dengan semua alat. Pola diangkerkan sebagai `^(pattern)$` dan dicocokkan sesuai dengan sensitivitas huruf besar/kecil. Kosong atau null tidak cocok dengan apapun.
`timeout`	int	`30`	Batas waktu eksekusi dalam hitungan detik (harus positif; nilai di atas 300 ditandai selama validasi CLI).
`failMode`	string	`allow`	Cara menangani kesalahan kait: `allow` atau `block`.
`model`	string	`ReasoningFast`	Model untuk kait permintaan (nama skenario atau nama penyebaran).
`maxRejections`	int	`3` (agen default)	Batas penolakan maksimum sebelum menghentikan paksa. Rentang: 1–25. Berlaku untuk stop hook jenis perintah saja. Hook Stop jenis perintah tidak memiliki batas implisit. Saat beberapa hook prompt menentukan nilai yang berbeda, nilai maksimum yang digunakan.

Skema konteks pengait

Hook menerima konteks JSON terstruktur tentang peristiwa saat ini. Prompt hook menerima konteks melalui $ARGUMENTS tempat penampung dalam teks perintah. Kait perintah menerima konteks sebagai JSON di stdin.

Untuk kedua jenis hook, kolom execution_summary berisi jalur file yang mengarah ke transkrip percakapan (bukan konten sebaris). Untuk prompt hooks, LLM menerima alat ReadFile dan GrepSearch untuk mengakses file ini. Untuk kait perintah, file tersedia di jalur yang ditentukan di kotak pasir.

Bidang umum

Semua hook memiliki bidang berikut:

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

Hentikan bidang hook

Stop hook menerima informasi tambahan tentang output akhir agen.

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

Bidang pengait PostToolUse

Hooks PostToolUse menerima bidang tambahan selama eksekusi alat.

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

Batasan

Batas berikut berlaku untuk pengait agen.

Limit	Nilai
Ukuran skrip	Maksimum 64 KB
Jeda Waktu	1–300 detik
Penolakan maks (perintah Hentikan hook)	1–25 (default: 3)
Dukungan untuk shebang skrip	`#!/bin/bash`, `#!/usr/bin/env python3`
Lingkungan eksekusi skrip	Penerjemah kode berbasis sandbox

Contoh: Mengaudit semua penggunaan alat

Hook PostToolUse berikut ini mencatat setiap panggilan alat dan menambah pesan konteks audit:

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

Bidang additionalContext ditambahkan sebagai pesan pengguna dalam percakapan, memberikan agen kemampuan untuk melihat rekaman audit.

Contoh: Memerlukan penanda penyelesaian

Stop hook berikut menolak respons yang tidak diakhir dengan "Tugas selesai.":

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

Praktik terbaik

Ikuti panduan ini saat Anda mengonfigurasi kait agen:

Selalu berikan alasan saat menolak. Perlakukan penolakan tanpa alasan sebagai persetujuan.
Gunakan batas waktu yang sesuai: Kait jangka panjang memperlambat eksekusi agen.
Menangani kesalahan dengan anggun: Gunakan failMode: allow kecuali penegakan ketat diperlukan.
Bersikaplah spesifik dengan pencocokan: Pencocokan PostToolUse yang terlalu luas dapat menyebabkan masalah performa.
Uji kait secara menyeluruh: Kait yang selalu menolak dapat menyebabkan perulangan (dimitigasi oleh maxRejections).
Log ke stderr: Gunakan stderr untuk men-debug output. Sistem mengurai stdout sebagai hasil kait.

Cobalah sendiri

Cuplikan layar berikut menunjukkan sebuah "Stop hook" yang sedang beraksi. Agen awalnya merespons hanya dengan "4", tetapi mekanisme menolak respons karena penanda penyelesaian hilang. Agen kemudian melanjutkan dan menambahkan penanda.

Get started

Sumber Daya	Apa yang akan Anda pelajari
Mengonfigurasi pengait agen (API)	Menyiapkan kait dengan menggunakan REST API v2 dan YAML

Kemampuan	Bagaimana hubungannya
Mode operasi	Kait melengkapi kontrol keamanan mode berjalan. Mode-mode mengontrol apa yang dijalankan, hooks mengontrol seberapa baik eksekusinya.
Alat Python	Buat alat kustom yang dapat diaudit dan divalidasi oleh hooks.

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-03-27