Tutorial: Mengonfigurasi kait agen (API) di Azure SRE Agent

Petunjuk / Saran

Lebih suka UI portal? Anda sekarang dapat membuat dan mengelola kait langsung di portal tanpa menggunakan REST API. Portal menyediakan formulir visual dan editor kode. Tidak ada curl perintah yang diperlukan.

Dalam tutorial ini, Anda membuat agen kustom dengan Stop hook yang memaksa agen untuk menambahkan penanda penyelesaian ke setiap respons. Anda mengonfigurasi hook melalui REST API, lalu mengujinya di taman bermain portal.

Perkiraan waktu: 15 menit

Nota

Kait pada tingkat agen vs. tingkat agen kustom: Tutorial ini membuat kait pada agen kustom (kait pada tingkat agen kustom). Hook ini hanya diaktifkan saat agen kustom tersebut dijalankan.

Untuk membuat kait tingkat agen yang berlaku untuk seluruh agen (semua utas, semua agen kustom), gunakan Builder>Hooks di portal.

Tingkat	Cara membuat	Ruang lingkup
Tingkat agen	Portal: Builder > Hooks	Berlaku untuk semua utas dan agen kustom
Tingkat agen khusus	REST API (tutorial ini) atau Portal: Agen Canvas > Agen Kustom > Mengelola Hooks	Hanya berlaku untuk satu agen kustom

Dalam tutorial ini, Anda akan belajar cara:

Membuat agen kustom dengan Stop hook menggunakan REST API
Menguji perilaku kait di taman bermain Uji portal
Menambahkan hook PostToolUse untuk mengaudit penggunaan alat
Memblokir perintah berbahaya dengan kait kebijakan

Prasyarat

Agen Azure SRE dalam status Berjalan
curl untuk memanggil REST API
Azure CLI masuk (az login) untuk mendapatkan token akses

Memahami format API kait

Tutorial ini menggunakan REST API v2 untuk membuat kait pada agen kustom. Tab pengaturan editor YAML portal menunjukkan format v1 dan tidak menampilkan pengait yang dikonfigurasi dengan API, tetapi pengait tersebut masih aktif. Anda dapat memverifikasinya di halaman Builder>Hooks atau taman bermain Uji.

Petunjuk / Saran

Kapan menggunakan API vs portal:

Portal (Builder > Hooks): Terbaik untuk pengait pada tingkat agen dalam bentuk visual. Tidak ada kode yang diperlukan.
API (tutorial ini): Terbaik untuk kait tingkat agen kustom, alur CI/CD, atau manajemen terprogram.

Menemukan URL API agen Anda

URL dasar API agen Anda mengikuti pola ini:

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

Untuk menemukannya:

Buka sre.azure.com dan pilih agen Anda.
Di bilah sisi kiri, pilih Penyusun>Kanvas Agen.
Buka Alat Pengembang browser Anda (F12 atau klik > kanan Periksa).
Buka tab Jaringan , filter menurut "api", dan cari permintaan ke URL yang berakhiran .azuresre.ai.
URL dasar adalah semua yang terdapat sebelum /api/....

Atau, periksa atribut src di tab Elemen. Cari <iframe> yang src dimulai dengan https://{agent-name}--.

Mendapatkan token akses

Jalankan perintah berikut untuk mendapatkan token akses untuk SRE Agent API:

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

Membuat agen kustom dengan Stop hook

Langkah ini membuat agen kustom yang disebut my_hooked_agent dengan Stop hook yang memeriksa apakah respons diakhiri dengan === RESPONSE COMPLETE ===. Jika penanda tidak ada, hook akan menolak respons dan memberi tahu agen untuk menambahkan penanda tersebut.

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

Anda menerima HTTP 202 Diterima dengan konfigurasi agen lengkap di isi respons.

Contoh berikut menunjukkan konfigurasi yang sama dalam format YAML v2 untuk referensi:

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

Cara kerja Stop hook

Stop hook mengevaluasi respons agen sebelum kembali ke pengguna:

Mengganti $ARGUMENTS dengan konteks kait JSON, yang mencakup respons akhir dari agen.
LLM mengevaluasi perintah dan mengembalikan {"ok": true} atau {"ok": false, "reason": "..."}.
Jika ditolak, agen terus bekerja setelah alasan disuntikkan sebagai pesan pengguna.
Setelah tiga penolakan (default), agen berhenti.

Menguji hook di portal

Ikuti langkah-langkah berikut untuk menguji Stop hook:

Buka agen Anda di portal dan pilih Builder>Agent Canvas.
Pilih tombol radio Lingkungan Uji.
Pilih menu dropdown Subagent/Tool , temukan my_hooked_agent, dan pilih Terapkan.
Ketik What is 2+2? di obrolan dan pilih Kirim.

Tonton apa yang terjadi:

Agen pertama kali merespons dengan 4.
Stop hook mengevaluasi dan menolak respons (tidak ada penanda penyelesaian).
Langkah proses Pemikiran muncul ketika agen melanjutkan.
Respons akhir muncul: 4 === RESPONS SELESAI ===.

Pengait itu berhasil. Ini memaksa agen untuk menambahkan penanda sebelum berhenti.

Menambahkan hook "PostToolUse" untuk audit

Tambahkan hook PostToolUse yang mencatat setiap alat yang digunakan agen. Perbarui agen yang sama dengan mengirim permintaan baru PUT yang mengandung kedua hook:

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: "*" berarti hook ini dijalankan pada setiap pemanggilan alat. Skrip mencatat nama alat dan menyuntikkan pesan [AUDIT] ke dalam percakapan.

Untuk menguji hook, ajukan pertanyaan kepada agen yang memicu alat (misalnya, "Jalankan echo hello").

Blokir perintah berbahaya

Tambahkan hook PostToolUse kedua yang memblokir rm -rf, , sudodan 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"}))

Perbedaan utama dari audit hook:

matcher: "Bash|ExecuteShellCommand" hanya digunakan untuk peralatan shell (pola diposisikan sebagai ^(Bash|ExecuteShellCommand)$).
failMode: block memblokir hasil alat jika skrip itu sendiri mengalami crash (mode ketat).
Mengembalikan "block" dengan alasan ketika pola berbahaya ditemukan.

Format respon hook

Kait prompt dan kait perintah menggunakan format respons yang berbeda.

Kait pemicu perintah

Prompt hooks mengembalikan JSON sederhana:

{"ok": true}

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

Kait perintah (command hooks)

Hook komando mengembalikan JSON yang diperluas:

{"decision": "allow"}

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

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

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

Kode keluar	Perilaku
`0` tanpa output	Allow
`0` dengan JSON	Mengurai JSON
`2`	Blokir (stderr menjadi alasannya)
Other	Kembali ke `failMode`

Perhatian

Penolakan tanpa alasan diperlakukan sebagai persetujuan. Selalu sertakan reason saat menolak.

Memverifikasi

Setelah Anda mengonfigurasi dan menguji kait, konfirmasikan kondisi berikut:

Anda mengonfigurasi kait tingkat agen kustom dengan menggunakan REST API v2. Mereka hanya berlaku untuk agen kustom tersebut.
Anda membuat kait tingkat agen di Builder > Hooks. Peraturan ini berlaku di seluruh agen.
Kait penghenti menyebabkan agen menambahkan penanda === RESPONSE COMPLETE === sebelum berhenti.
PostToolUse hook audit mencatat pesan log [AUDIT] untuk panggilan alat.
Kait kebijakan memblokir perintah berbahaya seperti rm -rf dan sudo.

Troubleshooting

Masalah dan solusi umum untuk kait agen tercantum dalam tabel berikut.

Masalah	Solusi
Hooks tidak terlihat di tab YAML portal	Diharapkan bahwa tab YAML hanya menampilkan v1. Kait tingkat agen kustom yang dibuat melalui API aktif dan terlihat di Builder>Hooks atau taman bermain.
`Unsupported kind: ExtendedAgent`	Gunakan titik akhir v2: `PUT /api/v2/extendedAgent/agents/{name}`.
`Handoffs cannot be null`	Tambahkan `"handoffs": []` ke payload JSON.
Hook tidak berpengaruh	Sertakan `reason` kolom saat menolak. Tanpa itu, penolakan diperlakukan sebagai persetujuan.
Agen mengulang selamanya	Lebih rendah `maxRejections` (default: 3, rentang: 1-25).

Langkah selanjutnya

Pelajari tentang kait agen.

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-03-28