Öğretici: Azure SRE Aracısı'nda aracı kancalarını (API) yapılandırma

İpucu

Portal kullanıcı arabirimini mi tercih ediyorsunuz? Artık REST API'yi kullanmadan doğrudan portalda kanca oluşturabilir ve yönetebilirsiniz. Portal bir görsel form ve kod düzenleyicisi sağlar. Komut curl gerekmez.

Bu öğreticide, aracıyı her yanıta tamamlama işaretçisi eklemeye zorlayan bir Durdurma kancası ile özel bir aracı oluşturursunuz. Kancayı REST API aracılığıyla yapılandırır, ardından portalın oyun alanında test edersiniz.

Tahmini süre: 15 dakika

Uyarı

Aracı düzeyi ve özel aracı düzeyi kancaları: Bu eğitim rehberi, özel bir aracının düzeyinde (özel aracı düzeyi kancalar) kancalar oluşturur. Bu kancalar yalnızca belirli bir özel aracı çalıştırıldığında tetikler.

Aracının tamamına (tüm iş parçacıkları, tüm özel aracılar) uygulanan aracı düzeyinde kancalar oluşturmak için portalda Builder>Kancaları'nı kullanın.

Seviye	Nasıl Oluşturulur	Scope
Aracı düzeyi	Portal: Oluşturucu > Kancaları	Tüm iş parçacıkları ve özel aracılar üzerinde geçerlidir.
Özel ajan düzeyi	REST API (bu öğretici) veya Portal: Aracı Tuvali > Özel Aracı > Kancaları Yönet	Yalnızca bir özel aracı için geçerlidir

Bu eğitimde şunları öğreniyorsunuz:

REST API kullanarak Durdurma kancası ile özel aracı oluşturma
Portalın Test deneme alanında kanca davranışını test et.
Denetim aracı kullanımı için PostToolUse kancası ekleme
İlke kancasıyla tehlikeli komutları engelleme

Önkoşullar

Çalışıyor durumunda bir Azure SRE Aracısı
REST API'yi çağırmak için curl
Azure CLI, erişim belirteci almak için oturum açtıaz login

Kanca API'sinin biçimini anlama

Bu eğitimde, özel bir aracıda kancalar oluşturmak için REST API v2 kullanılır. Portalın YAML düzenleyici sekmesi v1 biçimini gösterir ve API aracılığıyla yapılandırılmış kancaları görüntülemez, ancak kancalar hala etkindir. Oluşturucu>Kancaları sayfasında veya Test oyun alanında bunları doğrulayabilirsiniz.

İpucu

API ve portal ne zaman kullanılır:

Portal (Oluşturucu > Kancaları): Görsel formda aracı düzeyinde kancalar için en iyisidir. Kod gerekmez.
API (bu kılavuz): Özel temsilci düzeyinde kancalar, CI/CD işlem hatları veya programatik yönetim için en iyi yöntemdir.

Ajanınızın API URL'sini bulma

Aracınızın API temel URL'si şu desene uyar:

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

Bulmak için:

sre.azure.com açın ve temsilcinizi seçin.
Sol kenar çubuğunda Oluşturucu>Aracı Tuvali seçin.
Tarayıcınızın Geliştirici Araçları'nı açın (F12 veya İncele'ye sağ tıklayın > ).
Ağ sekmesine gidin, "api" ile filtreleyin ve .azuresre.ai ile biten URL'ye yapılan istekleri arayın.
Base URL, /api/... karakterinden önceki her şeydir.

Alternatif olarak, src özniteliğini Öğeler sekmesinde denetleyin. <iframe> ile başlayan bir srchttps://{agent-name}-- arayın.

Erişim belirteci alma

SRE Aracısı API'sine erişim belirteci almak için aşağıdaki komutu çalıştırın:

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

Durdurma kancası ile özel aracı oluşturma

Bu adım, yanıtın === RESPONSE COMPLETE === ile bitip bitmediğini denetleyen Stop kancasına sahip my_hooked_agent adlı özel bir aracı oluşturur. İşaretçi eksikse, kanca yanıtı reddeder ve aracıya işaretçiyi eklemesini söyler.

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

Yanıt gövdesinde tam aracı yapılandırmasıyla HTTP 202 Accepted alırsınız.

Aşağıdaki örnekte, başvuru için v2 YAML biçiminde aynı yapılandırma gösterilmektedir:

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

Durdurma kancası nasıl çalışır?

Durdurma Hook’u, kullanıcıya dönmeden önce ajanın yanıtını değerlendirir.

$ARGUMENTS öğesini, aracının son yanıtını içeren kanca bağlamı JSON ile değiştirir.
LLM, istemi değerlendirir ve {"ok": true} veya {"ok": false, "reason": "..."} döndürür.
Reddedilirse, neden kullanıcı iletisi olarak eklendikten sonra aracı çalışmaya devam eder.
Üç reddetmeden (varsayılan davranış) sonra, aracı durur.

Kancayı portalda test edin

Durdurma kancasını test etmek için şu adımları izleyin:

Portalda aracınıza gidin ve Oluşturucu>Aracı Tuvali'ni seçin.
Oyun parkını test et radyo düğmesini seçin.
Subagent/Tool açılan listesini seçin, my_hooked_agent bulun ve Uygula'yı seçin.
Sohbete yazın What is 2+2? ve Gönder'i seçin.

Neler olduğunu izleyin:

Aracı ilk olarak 4 ile yanıt verir.
Durdurma kancası yanıtı değerlendirir ve reddeder (tamamlama işaretçisi yoktur).
Ajanın devam ettiği bir Düşünme Süreci adımı görüntülenir.
Son yanıt görüntülenir: 4 === YANIT TAMAMLA ===.

Kanca işe yaradı. Ajanı durdurmadan işaretçiyi eklemeye zorladı.

Denetim için PostToolUse kancası ekleme

Ajanın kullandığı her aracı günlüğe kaydeden bir PostToolUse kancası ekleyin. Her iki kancayla da yeni PUT bir istek göndererek aynı aracıyı güncelleştirin:

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: "*" bu kancanın her araç çağrısı için çalıştığı anlamına gelir. Betik araç adını günlüğe kaydeder ve konuşmaya bir [AUDIT] ileti ekler.

Kancayı test etmek için aracıya bir aracı tetikleyen bir soru sorun (örneğin, "Çalıştır echo hello").

Tehlikeli komutları engelleme

İkinci bir PostToolUse kancası ekleyin; bu kanca rm -rf, sudo ve chmod 777'yi engeller:

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

Denetim kancasından önemli farklar:

matcher: "Bash|ExecuteShellCommand" yalnızca kabuk araçları için çalışır (desen olarak ^(Bash|ExecuteShellCommand)$sabitlenmiştir).
failMode: block betiğin kendisi çökerse araç sonucunu bloklar (katı mod).
Tehlikeli bir desen bulunduğunda, bir gerekçeyle "block" döndürür.

Çengel yanıt biçimleri

İstem kancaları ve komut kancaları farklı yanıt biçimleri kullanır.

İstem kancaları

İstem kancaları, basit bir JSON formatı döndürür.

{"ok": true}

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

Komut kancaları

Komut kancaları genişletilmiş JSON döndürür:

{"decision": "allow"}

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

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

Komut kancaları JSON yerine çıkış kodlarını da kullanabilir:

Çıkış kodu	Davranış
`0` çıkış yok	Allow
`0` JSON ile	JSON ayrıştırma
`2`	Blok (stderr nedeni olur)
Other	Önceki duruma geri döner `failMode`

Dikkat

Bir neden olmadan reddedilmesi onay olarak kabul edilir. Reddederken her zaman reason dahil edin.

Verify

Kancaları yapılandırıp test ettikten sonra aşağıdaki koşulları onaylayın:

REST API v2 kullanarak özel aracı düzeyinde kancalar yapılandırabilirsiniz. Yalnızca bu kişiselleştirilmiş aracı için geçerlidir.
Oluşturucu > oluşturursunuz. Bunlar tüm ajana uygulanır.
Durdurma kancası, ajanın durmadan önce === RESPONSE COMPLETE === işaretçisini eklemesine neden olur.
PostToolUse denetim kancası, araç çağrıları için [AUDIT] mesajları günlüğe kaydeder.
Politika kancası, rm -rf ve sudo gibi tehlikeli komutları engeller.

Sorun giderme

Aşağıdaki tabloda, aracı kancaları için yaygın sorunlar ve çözümler listelenmiştir.

Sorun	Çözüm
Portal YAML sekmesinde kancalar görünmüyor	Beklenen : YAML sekmesi yalnızca v1'i gösterir. API aracılığıyla oluşturulan özel aracı düzeyinde hook'lar, Builder>Hook'lar veya playground'da etkin ve görünür durumdadır.
`Unsupported kind: ExtendedAgent`	v2 uç noktasını kullanın: `PUT /api/v2/extendedAgent/agents/{name}`.
`Handoffs cannot be null`	JSON yük verisine `"handoffs": []` ekleyin.
Hook'un işlevi yok	Reddederken bir `reason` alan ekleyin. Bu olmadan, reddetme onay olarak kabul edilir.
Aracı sonsuz döngüde kalır	Daha düşük `maxRejections` (varsayılan: 3, aralık: 1-25).

Sonraki adım

Aracı kancaları hakkında bilgi edinin.

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-03-28