Azure SRE Ajanı'nda aracı bağlayıcılar

Kancalar, önemli anlarda aracı davranışını engelleyen ve denetleen özel denetim noktalarıdır. Kancaları kullanarak aracı yanıtlarına kalite geçitleri uygulayın, araç kullanımını denetleyin ve kontrol edin, politikaları uygulayarak tehlikeli işlemleri engelleyin ve aracı çıkışını doğrulayarak erken görev tamamlanmasını önleyin.

Aracı kancalarının çözdüğü sorun

Ajanınız, olayları araştırarak, araçları çalıştırarak ve yanıtlar üreterek görevleri otonom olarak yerine getirir. Ancak gözetim olmadan özerklik risk oluşturur:

Tamamlanmamış yanıtlar: Aracı, istediğiniz her şeyi cevaplamadan önce "tamam" diyor.
Sessiz araç kullanımı: Aracının hangi araçları çağırdığını veya hangi sonuçları aldığını göremezsiniz.
İlke uygulama yok: Tehlikeli işlemler (yıkıcı komutlar, yetkisiz değişiklikler) kontrolsüz bir şekilde devam eder.
Kalite boşlukları: Doğrulama adımı olmadığından yanıtlar kritik bilgileri kaçırır.

Aracı davranışını yavaşlatmadan veya özerkliğini tamamen kaldırmadan önemli anlarda kesmenin bir yoluna ihtiyacınız vardır.

Temsilci kancaları nasıl çalışır?

Hook'lar, belirli ajan olaylarına eklediğiniz özel denetim noktalarıdır. Bir olay tetiklendiğinde, hook'unuz durumu değerlendirir ve eyleme izin verilip verilmeyeceğine karar verir.

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

Şu anda iki web kancası olayı desteklenmektedir.

Etkinlik	Tetikleyiciler:	Yapabilecekleriniz
Durdur	Ajan son yanıtı vermek üzere	Tamlığı doğrula, ajanı reddet ve devam etmeye zorla
PostToolUse	Araç başarıyla yürütülüyor	Kullanımı denetleme, sonuçları engelleme, ek bağlam ekleme

İki kanca seviyesi

Kancalar iki düzeyde çalışır:

Seviye	Nerede yapılandırılır?	Scope
Aracı düzeyi	Portalda Oluşturucu → Kancaları	Tüm iş parçacıkları ve tüm özelleştirilmiş aracılar dahil olmak üzere tüm temsilci için geçerlidir.
Özel ajan düzeyi	Aracı Tuvali → Özel Aracı → Kancaları Yönet veya REST API v2 aracılığıyla	Yalnızca belirli bir özel aracı çalıştırıldığında uygulanır

Her iki düzey de bir arada bulunabilir. Aracı düzeyinde bir kanca ve özel bir aracı düzeyi kanca aynı olayla eşleşiyorsa, her ikisi de çalıştırılır. Önce aracı düzeyinde kancalar ateş eder.

Yürütme türleri

LLM veya kabuk komut dosyası kullanarak kancaları uygulayabilirsiniz.

Türü	Nasıl çalışır?	En iyi kullanım alanı:
İstem	LLM, isteminizi değerlendirir ve bir JSON kararı döndürür	Nüanslı doğrulama ("Bu yanıt tamamlandı mı?")
Command	Bash veya Python betiği kapsüllü bir ortamda çalışır	Belirleyici denetimler, ilke uygulama, denetim

İstem kancaları , bir yanıtın tüm kullanıcı endişelerini giderip gidermediğini denetleme veya araştırmanın yeterince kapsamlı olduğunu doğrulama gibi öznel değerlendirme için güçlü bir araçtır. Tam kanca bağlamını almak için $ARGUMENTS yer tutucu kullanılır. Eğer $ARGUMENTS istemde yoksa, bağlam otomatik olarak eklenir. Konuşma metni mevcut olduğunda, istem kancaları ReadFile ve GrepSearch araçlarını da alır; bu, LLM'nin tüm konuşma geçmişi hakkında mantık yürütebilmesine olanak tanır.

Komut kancaları , bir yanıtın gerekli işaretçileri içerdiğini doğrulama, tehlikeli komutları engelleme veya dış sistemde araç kullanımını günlüğe kaydetme gibi belirleyici denetimler için daha iyidir.

Kancalı ve kancasız aracı davranışı

Aşağıdaki tablo, aracı davranışını kancalarla ve kancalar olmadan karşılaştırır.

Kanca olmadan	Kancalarla
Aracı, ne zaman "bittiğine" karar verir	"Bitti" ifadesinin ne anlama geldiğini tanımlarsınız
Araç kullanımı görünmez	Her araç çağrısı denetlenebilir
Tehlikeli komutlar sessizce devam eder	Politika uygulama, bunları otomatik olarak engeller.
Kalite yalnızca istem mühendisliğine bağlıdır	Otomatik kalite kontrolları eksiklikleri yakalar

Kancalar çalıştırma modu güvenlik denetimlerinin yerini değiştirmez. Bunun yerine, bunları tamamlarlar. Çalıştırma modları aracının neler yapabileceğini denetler. Kancalar, ne derece iyi olduğunu ve sonuçlarla ne olacağını kontrol eder.

Ajan kancalarını eklemeden önce ve sonra

Scenario	Önce	Sonra
Yanıt kalitesi	Ajan, bittiğini düşündüğü zaman durur	Durdurma kancanız yanıt kullanıcılara ulaşmadan önce tamlığı doğrular
Araç görünürlüğü	Araç çalıştırılmasına dair denetim kaydı yok	Her araç çağrısını günlüğe kaydetmek ve doğrulamak için PostTool çekleri kullanılır.
Politika uygulama	Tehlikeli komutlar işaretsiz çalışıyor	Betikler, `rm -rf`, `sudo` ve diğer riskli desenleri otomatik olarak engeller.
Kalite güvencesi	Komut mühendisliği tek kozunuz.	LLM tabanlı bağlantılar ince ayrımları değerlendirir; betikler kesin kuralları uygular

Aracı kancalarını yapılandırın

Portal kullanıcı arabirimi aracılığıyla kancalar oluşturun:

Aracı düzeyinde kancalar:Oluşturucu → Kancalar'a gidin → Kanca oluştur'u seçin.
Özel aracı düzeyinde kancalar:Aracı Tuvali'ne gidin → Kancaları Yönet → özel bir aracı seçin.

Adım adım yönergeler için bkz. Portalda kanca oluşturma ve yönetme.

Tip

Ayrıca kullanarak PUT /api/v2/extendedAgent/agents/{agentName} aracılığıyla kancaları yapılandırabilirsiniz. Aşağıdaki bölümdeki YAML biçimi, tam yapılandırma şemasını gösterir. Daha fazla bilgi edinmek için API öğreticisine bakın.

Aracı Tuvali YAML sekmesi v1 biçimini görüntüler ve kancaları göstermez. Kancaları görüntülemek ve yönetmek için Oluşturucu altındaki Kancalar sayfasını kullanın.

Aşağıdaki örnekte tam bir kanca yapılandırması gösterilmektedir:

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

Kanca yanıt biçimi

Kancalar JSON çıkışı yapmalıdır. İki biçim desteklenir:

Basit biçim (istem kancaları için önerilir):

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

Genişletilmiş biçim (komut kancaları için önerilir):

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

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

Çıkış kodu	Davranış
`0` çıkış yok	İzin ver (itiraz yok)
`0` JSON ile	Karar verme için JSON ayrıştırma
`2`	Her zaman engelle. stderr nedeni olur
Other	`failMode` ayarını (`allow` veya `block`) kullanır

Dikkat

Durdurma kancaları için, nedeni olmayan bir reddetme onay olarak kabul edilir ve aracı normal şekilde durur. Reddederken her zaman bir reason alan sağlayın.

Uyarı

Aynı etkinlik için birden çok "hook" tanımlayabilirsiniz. PostToolUse için, eşleşen matcher desene sahip her kanca bağımsız olarak çalışır. Birden çok kanca sağlarsa additionalContext, son kancanın bağlamı konuşmaya eklenir.

Yapılandırma referansı

Aşağıdaki tabloda tüm kullanılabilir kanca yapılandırma seçenekleri açıklanmaktadır.

Seçenek	Türü	Varsayılan	Açıklama
`type`	String	`prompt`	`prompt` veya `command`
`prompt`	String	(yok)	LLM başlangıç metni (bağlantı noktaları için gereklidir). `$ARGUMENTS` bağlam ekleme için kullanın.
`command`	String	(yok)	Satır içi kabuk komutu (komut kancaları için, `script` ile birbirini dışlar).
`script`	String	(yok)	Çok satırlı betik (komut kancaları için, `command` ile birbirini dışlayan).
`matcher`	String	(yok)	Araç adları için regex deseni (PostToolUse kancaları için gereklidir). `*` tüm araçlarla eşleşir. Desenler, büyük/küçük harfe duyarlı bir şekilde `^(pattern)$` olarak sabitlenir ve eşleştirilir. Boş veya null hiçbir şeyle eşleşmez.
`timeout`	int	`30`	Saniyeler içinde yürütme zaman aşımı (pozitif olmalıdır; CLI doğrulaması sırasında 300'ü aşan değerler işaretlenir).
`failMode`	String	`allow`	Kanca hatalarını işleme: `allow` veya `block`.
`model`	String	`ReasoningFast`	İstem kancaları modeli (senaryo adı veya dağıtım adı).
`maxRejections`	int	`3` (temsilci varsayılanı)	Durmayı zorlamadan önce en fazla reddetme sayısı. Aralık: 1-25 arası. Yalnızca istem tipi Durdurma kancaları için geçerlidir. Komut türü Durdurma kancalarının örtük sınırı yoktur. Birden çok istem kancası farklı değerler belirttiğinde maksimum değer kullanılır.

Kanca bağlam şeması

Kancalar, mevcut olay hakkında yapılandırılmış JSON bağlamı alır. İstem kancaları , istem metnindeki $ARGUMENTS yer tutucu aracılığıyla bağlam alır. Komut kancaları JSON biçiminde bağlamı stdin alır.

Her iki kanca türü için de, execution_summary alan konuşma transkriptinin (satır içi içerik değil) bir dosya yolunu içerir. İstem kancaları için, LLM bu dosyaya erişmek amacıyla gereken ReadFile ve GrepSearch araçlarını alır. Komut kancaları için dosya, korumalı alan içinde belirtilen yolda mevcuttur.

Ortak alanlar

Tüm kancalar aşağıdaki alanları alır:

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

Kanca alanlarını durdurma

Durdurma kancaları, ajanın son çıktısı hakkında ek alanlar alır.

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

PostToolUse yapılandırma alanları

PostToolUse kancaları, aracın yürütülmesi hakkında ek alanlar sağlar.

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

Model düzeyleri

İstem kancaları, aracının davranışını değerlendirmek için bir yapay zeka modeli kullanır. Kancanın hangi model katmanını kullandığını seçerek değerlendirme kalitesini maliyet ve gecikme süresine karşı dengeleyebilirsiniz.

Katman	En iyi kullanım alanı:	Ödünleşme
Reasoning	Karmaşık ilke zorlama, çok adımlı doğrulama, nüanslı uyumluluk denetimleri	En yüksek kalite, daha yüksek maliyet ve gecikme süresi
Hızlı Akıl Yürütme (varsayılan)	Çoğu kanca, yanıt doğrulama, denetim denetimleri, güvenlik uygulaması	Düşük gecikme süresiyle iyi mantık yürütme
Genel Amaçlı	Basit biçim denetimleri, temel uyumluluk doğrulaması	Dengeli doğruluk, maliyet ve hız
Hızlı	Hafif denetimler, varlık doğrulaması, biçim doğrulaması	En düşük maliyet, en hızlı yanıt
Uzun Bağlam	Büyük çıktıları işleyen kancalar, tam belge analizi, kapsamlı araç sonuçları	Daha büyük girdileri, daha yüksek maliyetle destekler

Tip

Hook’lar, her ajan yanıtında veya araç çağrısında çalıştıkları için varsayılan olarak Hızlı Akıl Yürütme kullanır; bu nedenle düşük gecikme önemlidir. Reasoning'i yalnızca doğruluğun kritik önem taşıdığı karmaşık politikaları uygulayan kancalar için kullanın.

Limits

Aracı kancaları için aşağıdaki sınırlar geçerlidir.

Limit	Değer
Betik boyutu	En fazla 64 KB
Zaman Aşımı	1 - 300 saniye
Maksimum reddetme (durdurma kancaları)	1 - 25 (varsayılan: 3)
Desteklenen betik shebang'ler	`#!/bin/bash`, `#!/usr/bin/env python3`
Betik yürütme ortamı	Korumalı kod yorumlayıcı

Örnek: Tüm araç kullanımını denetleme

Aşağıdaki PostToolUse işlevi, her araç çağrısını loglar ve bir denetim bağlamı mesajı ekler:

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

Alan additionalContext konuşmaya kullanıcı iletisi olarak eklenir, bu sayede aracının denetim izini görmesini sağlar.

Örnek: Tamamlama işaretçisi gereklidir

Aşağıdaki Durdurma kancası, "Görev tamamlandı" ile bitmeyen yanıtları reddeder:

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

En iyi uygulamalar

Ajan kancalarını yapılandırdığınızda:

Reddederken her zaman bir neden sağlayın. Reddetmeleri nedensiz olarak onay olarak değerlendirin.
Uygun zaman aşımlarını kullanın: Uzun süre çalışan bağlamalar aracı yürütmeyi yavaşlatır.
Hataları düzgün bir şekilde işleyin: Katı zorlama gerekmediği sürece failMode: allow kullanın.
Eşleştiricileri belirginleştirin: Aşırı geniş PostToolUse eşleştiriciler performans sorunlarına neden olabilir.
Kancaları kapsamlı bir şekilde test edin: Her zaman reddeden kancalar döngülere neden olabilir (bu, maxRejections ile azaltılır).
stderr'e kaydet: Çıkışta hata ayıklamak için stderr kullanın. Sistem, stdout'ı kanca sonucu olarak ayrıştırır.

Agent hook'larını kendiniz deneyin

Aşağıdaki ekran görüntüsünde, bir Durdurma kancası gösterilmektedir. Aracı başlangıçta yalnızca "4" ile yanıt verir, ancak tamamlama işaretçisi eksik olduğundan kanca yanıtı reddeder. Ardından aracı işlemi sürdürür ve işaretçiyi ekler.

Başlayın

Kaynak	Öğrendikleriniz
Hook'ları oluştur ve yönet (portal)	Portal kullanıcı arabiriminde görsel olarak kancalar oluşturun, API çağrısı gerekmez.
Aracı kancalarını yapılandırma (API)	REST API v2 ve YAML kullanarak kancaları ayarlayın.

Kapasite	Nasıl İlişkili
Çalıştırma modları	Bağlamalar çalışma modu güvenlik denetimlerini tamamlar. Modlar ne çalıştırılacağını denetler, kancalar ne kadar iyi çalıştırılacağını denetler.
Python araçları	Kancaların denetleyebileceği ve doğrulayabileceğiniz özel araçlar oluşturun.

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-06-04