Agent hooks in Azure SRE Agent

الخطافات هي نقاط تفتيش مخصصة تعترض وتتحكم في سلوك الوكلاء في اللحظات الحاسمة. استخدم الخطافات لفرض بوابات الجودة على استجابات الوكلاء، واستخدام أدوات التدقيق والتحكم، ومنع العمليات الخطرة من خلال تطبيق السياسات، ومنع إكمال المهام المبكر من خلال التحقق من مخرجات الوكيل.

المشكلة

يقوم وكيلك بتنفيذ المهام بشكل مستقل - التحقيق في الحوادث، تشغيل الأدوات، وتوليد الردود. لكن الاستقلالية بدون رقابة تخلق مخاطر:

• ردود غير مكتملة: يقول الوكيل "تم" قبل أن يطرح كل ما طلبته.
• استخدام الأدوات غير المدقق: ليس لديك رؤية لأي الأدوات يستدعي الوكيل أو ما هي النتائج التي يحصل عليها.
• لا يوجد تطبيق للسياسات: العمليات الخطرة (أوامر مدمرة، تغييرات غير مصرح بها) تسير دون رادع.
• فجوات الجودة: الردود تفوت معلومات حاسمة لأنه لا توجد خطوة تحقق.

تحتاج إلى طريقة لاعتراض سلوك العميل في اللحظات الحاسمة دون إبطاءه أو فقدان استقلاليته تماما.

كيف تعمل خطاطيف الوكيل

الخطافات هي نقاط تفتيش مخصصة تربطها بأحداث وكيل محددة. عندما يحدث حدث، يقوم الخطاف بتقييم الوضع ويقرر ما إذا كان سيسمح بالحركة أو منعه.

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

يتم حاليا دعم حدثين للهوك:

الحدث	المحفزات عندما	ما يمكنك القيام به
إيقاف	العميل على وشك أن يرد ردا أخيرا	تحقق من الاكتمال، ارفض وأجبر الوكيل على الاستمرار
استخدام ما بعد الأدوات	تنهي الأداة تنفيذها بنجاح	استخدام التدقيق، نتائج الكتلة، إضافة سياقات إضافية

مستويين من الخطاطيف

تعمل الخطاطيف على مستويين:

المستوى	مكان التكوين	النطاق
مستوى الوكيل	البناء → الخطاطيف في البوابة	ينطبق على الوكيل بالكامل بما في ذلك جميع الخيوط وجميع الوكلاء المخصصين
مستوى وكيل مخصص	Agent Canvas → وكيل مخصص → إدارة الخطاطيف، أو عبر واجهة برمجة التطبيقات REST v2	ينطبق فقط عندما يعمل ذلك الوكيل المخصص المحدد

كلا المستويين يمكن أن يتعايشوا. إذا كان خطاف مستوى الوكيل والخطاف على مستوى العميل المخصص يتطابقان مع نفس الحدث، يتم تشغيل كلاهما. خطاطيف مستوى العميل تبدأ أولا.

أنواع التنفيذ

يمكنك تنفيذ الخطافات باستخدام نموذج لغوي كبير (LLM) أو سكريبت shell:

النوع	طريقة العمل	مناسب لـ
المطالبة	يقوم نموذج اللغة الكبيرة بتقييم طلبك ويعيد قرار JSON	التحقق الدقيق ("هل اكتمل هذا الرد؟")
Command	يعمل سكريبت bash أو بايثون في بيئة مفتوحة	الفحص الحتمي، تطبيق السياسات، التدقيق

خطافات التوجيه قوية للتقييم الذاتي، مثل التحقق مما إذا كان الرد يعالج جميع مخاوف المستخدم أو التحقق من أن التحقيق كان دقيقا بما فيه الكفاية. يستخدمون العنصر $ARGUMENTS المؤقت لاستقبال السياق الكامل للخطاف. إذا $ARGUMENTS لم يكن هناك في الطلب، يتم إضافة السياق تلقائيا. عندما يتوفر نص المحادثة، تحصل أيضا ReadFile خطافات الأوامر على أدوات GrepSearch ، مما يسمح للنموذج بالتفكير في تاريخ المحادثة الكامل.

خطافات الأوامر أفضل للفحوصات الحتمية، مثل التحقق من احتواء الاستجابة على علامات مطلوبة، أو حجب الأوامر الخطرة، أو تسجيل استخدام الأدوات إلى نظام خارجي.

ما الذي يجعل هذا النهج مختلفا

يقارن الجدول التالي سلوك الوكيل مع وبدون خطاطيف.

بدون خطاطيف	مع خطافات
العميل يقرر متى "ينتهي" الأمر	أنت تحدد معنى "تم الفعل"
استخدام الأدوات غير مرئي	يمكن تدقيق كل استدعاء أداة
الأوامر الخطرة تسير بصمت	تطبيق السياسات يحظرها تلقائيا
الجودة تعتمد فقط على الهندسة الفورية	البوابات الآلية ذات الجودة تلتقط الفجوات

الخطاطيف لا تحل محل ضوابط الأمان في وضع الجري - بل تكملها. أوضاع التشغيل تتحكم فيما يمكن للوكيل فعله. الخطاطيف تتحكم في مدى جودة الأداء وما سيحدث للنتائج.

قبل وبعد

السيناريو	قبل	بعد
جودة الاستجابة	العميل يتوقف عندما يظن أنه انتهى	خطاف الإيقاف الخاص بك يتحقق من اكتمال الجميع قبل أن يصل الرد إلى المستخدمين
رؤية الأدوات	لا يوجد سجل تدقيق لتنفيذ الأدوات	PostToolUse يقوم بتسجيل والتحقق من كل استدعاء أداة
إنفاذ النُهج	الأوامر الخطرة تنفذ دون رقابة	تقوم السكربتات بحظر rm -rf، sudo، والأنماط الخطرة الأخرى تلقائيا
ضمان الجودة	هندسة التوجيه هي الرافعة الوحيدة لديك	الخطافات القائمة على LLM تقيم الفروق الدقيقة؛ تفرض النصوص قواعد حتمية

تكوين الخطافات

أسهل طريقة لإنشاء الخطافات هي من خلال واجهة البوابة:

1. خطافات على مستوى الوكيل: اذهب إلى Builder → Hooks → اختر إنشاء خطاف.
2. خطافات على مستوى الوكيل المخصص: اذهب إلى Agent Canvas → اختر وكيل مخصص → إدارة الخطاطيف.

نصيحة

يمكنك أيضا تكوين الخطافات عبر REST API v2 باستخدام PUT /api/v2/extendedAgent/agents/{agentName}. يعرض تنسيق YAML في القسم التالي مخطط التكوين الكامل. لمعرفة المزيد، راجع دليل واجهة برمجة التطبيقات.

تبويب YAML في Agent Canvas يعرض صيغة v1 ولا يظهر الخطافات. استخدم صفحة الخطافات تحت قسم البناء لعرض وإدارة الخطافات.

المثال التالي يوضح تكوين الخطاف الكامل:

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

صيغة الاستجابة الخطافية

يجب أن تخرج الخطاطيف JSON. يتم دعم تنسيقين.

تنسيق بسيط (موصى به لخطافات الطلب):

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

تنسيق موسعة (موصى به لخطافات الأوامر):

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

يمكن أيضا استخدام خطافات الأوامر رموز الخروج بدلا من مخرجات JSON:

رمز الإنهاء	سلوك
0 بدون مخرج	السماح (لا اعتراض)
0 مع JSON	تحليل JSON للقرار
2	دائما ما تحظر. تصبح stderr السبب
أخرى	يستخدم failMode إعداد (allow أو block)

تنبيه

بالنسبة لخطافات التوقف، يعتبر الرفض بدون سبب موافقة، ويتوقف الوكيل بشكل طبيعي. دائما قدم حقلا reason عند الرفض.

ملحوظة

يمكنك تعريف عدة خطافات لنفس الحدث. بالنسبة ل PostToolUse، كل خطاف بنمط مطابق matcher يعمل بشكل مستقل. إذا وفرت additionalContextعدة خطافات ، يتم حقن سياق الخطاف الأخير في المحادثة.

مرجع التكوين

الجدول التالي يصف جميع خيارات تكوين الخطاف المتاحة.

خيار	النوع	افتراضي	الوصف
type	string	prompt	prompt او command
prompt	string	—	نص مطالبة لنموذج اللغة الكبيرة (مطلوب لخطافات الطلب). استخدامه $ARGUMENTS لحقن السياق.
command	string	—	أمر shell داخل الخط (لخطافات الأوامر، متناقضي مع script).
script	string	—	سكريبت متعدد الأسطر (لخطاطيفات الأومر، غير متعارض مع command).
matcher	string	—	نمط Regex لأسماء الأدوات (مطلوب لخطافات PostToolUse اللازمة). * تطابق جميع الأدوات. الأنماط تثبت وتكون ^(pattern)$ متطابقة بحساسية لحروف الحروف. الفارغ أو الفارغ لا يتطابق مع شيء.
timeout	الفترة	30	مهلة التنفيذ بالثواني (يجب أن تكون موجبة؛ القيم التي تزيد عن 300 يتم تمييزها أثناء التحقق من CLI).
failMode	string	allow	كيفية التعامل مع أخطاء الخطاف: allow أو block.
model	string	ReasoningFast	نموذج لخطافات الأوامر (اسم السيناريو أو اسم النشر).
maxRejections	الفترة	3 (افتراضي الوكيل)	أقصى درجات الرفض قبل فرض التوقف. المسافة: 1–25. ينطبق فقط على خطافات الإيقاف من نوع الطلب. خطافات الإيقاف من نوع الأوامر ليس لها حد ضمني. عندما تحدد عدة خطافات أوامر قيما مختلفة، يتم استخدام الحد الأقصى.

مخطط السياق الخطافي

يحصل الخطاف على سياق JSON منظم حول الحدث الحالي. تتلقى خطافات الأوامر السياق عبر العنصر $ARGUMENTS المؤقت في نص الطلب. خطافات الأوامر تستقبل السياق ك JSON على stdin.

لكلا نوعي الخطاف، يحتوي الحقل execution_summary على مسار ملف إلى نص المحادثة (وليس محتوى داخلي). بالنسبة لخطافات التوجيه، تستقبل ReadFile النموذج الكبير أدوات GrepSearch للوصول إلى هذا الملف. بالنسبة لخطافات الأوامر، يتوفر الملف عند المسار المحدد في صندوق الرمل.

الحقول الشائعة

جميع الخطاطيف تستقبل الحقول التالية:

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

إيقاف حقول الخطاف

تتلقى خطاطيف الإيقاف حقول إضافية حول الناتج النهائي للوكيل.

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

حقول PostToolUse

تلقى خطافات PostToolUse حقول إضافية حول تنفيذ الأداة.

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

الحدود

تنطبق الحدود التالية على خطافات الوكيل.

Limit	قيمة
حجم النص	الحد الأقصى 64 كيلوبايت
المهلة	1–300 ثانية
أقصى الرفض (خطافات إيقاف محفز)	1–25 (الإعداد الافتراضي: 3)
الخطط المدعومة للسكريبت	#!/bin/bash، #!/usr/bin/env python3
بيئة تنفيذ السكريبتات	مفسر الشيفرة المدمج في صندوق الرمل

مثال: تدقيق كل استخدام الأدوات

يقوم خطاف PostToolUse التالي بتسجيل كل استدعاء أداة ويضيف رسالة سياق التدقيق:

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

يضاف الحقل additionalContext كرسالة مستخدم إلى المحادثة، مما يمنح الوكيل رؤية لمسار التدقيق.

مثال: يتطلب علامة إكمال

خطاف الإيقاف التالي يرفض الردود التي لا تنتهي ب "تم إكمال المهمة":

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

أفضل الممارسات

اتبع هذه الإرشادات عند تكوين خطافات الوكلاء:

1. دائما قدم سببا عند الرفض. اعتبر الرفض بدون أسباب موافقة.
2. استخدم الفترات المستقطعة المناسبة: الخطاف طويل الأمد يبطئ تنفيذ الوكيل.
3. التعامل مع الأخطاء برقة: استخدم failMode: allow ما لم يكن هناك حاجة لتطبيق صارم.
4. كن محددا مع المطابقات: المطابقات الواسعة جدا بعد استخدام الأدوات يمكن أن تسبب مشاكل في الأداء.
5. اختبر الخطاطيف بدقة: الخطاطيف التي ترفض دائما يمكن أن تسبب حلقات (يتم التخفيف منها بواسطة maxRejections).
6. تسجيل الدخول إلى stderr: استخدم stderr لتصحيح المخرجات. يقوم النظام بتحليل stdout كنتيجة الخطاف.

جرب بنفسك

تظهر لقطة الشاشة التالية خطاف إيقاف أثناء التنفيذ. يرد الوكيل في البداية ب "4" فقط، لكن الخطاف يرفض الرد لأن علامة الإكمال مفقودة. ثم يواصل الوكيل ويضيف العلامة.

الشروع في العمل

مورد	ما ستتعلمه
تكوين خطافات الوكيل (API)	قم بإعداد الوصلات باستخدام REST API v2 و YAML

المحتوى ذو الصلة

القدرة	كيف يرتبط الأمر
أوضاع التشغيل	الخطافات تكمل ضوابط الأمان في وضع الجري. الأوضاع تتحكم فيما يركض، والخطافات تتحكم في مدى جودة الجري.
أدوات بايثون	أنشئ أدوات مخصصة يمكن للهوكس تدقيقها والتحقق منها.