الدرس: تكوين خطافات الوكلاء (API) في Azure SRE Agent

نصيحة

تفضل واجهة البوابة؟ يمكنك الآن إنشاء وإدارة الروابط مباشرة في البوابة دون استخدام واجهة برمجة تطبيقات REST. توفر البوابة محرر صور للنماذج والشيفرة. لا curl حاجة لأي أوامر.

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

الوقت المقدر: 15 دقيقة

ملحوظة

خطافات على مستوى الوكيل مقابل الخطافات على مستوى الوكيل المخصص: هذا الدرس ينشئ خطافات على وكيل مخصص (خطافات على مستوى الوكيل المخصص). هذه الخطاف لا تطلق إلا عندما يعمل ذلك الوكيل المخصص تحديدا.

لإنشاء خطافات على مستوى الوكيل تنطبق على الوكيل بأكمله (جميع الخيوط، جميع الوكلاء المخصصين)، استخدم خطافات البناء> في البوابة.

المستوى	كيفية الإبداع	النطاق
مستوى الوكيل	البوابة: خطافات البناء >	ينطبق على جميع الخيوط والوكلاء المخصصين
مستوى وكيل مخصص	واجهة برمجة تطبيقات REST (هذا الدرس) أو بوابة: Agent Canvas >> Custom Agent Manage Hooks	ينطبق فقط على وكيل مخصص واحد

في هذا البرنامج التعليمي، تتعلم كيفية:

• أنشئ وكيل مخصص باستخدام خطاف إيقاف باستخدام واجهة برمجة تطبيقات REST
• سلوك خطاف الاختبار في ملعب الاختبار الخاص بالبوابة
• إضافة خطاف PostToolUse لتدقيق استخدام الأدوات
• حجب الأوامر الخطرة باستخدام خطاف سياسة

المتطلبات المسبقه

• وكيل Azure SRE في حالة التشغيل
• curl لاستدعاء واجهة برمجة تطبيقات REST
• Azure CLI سجل الدخول (az login) للحصول على رمز وصول

فهم تنسيق واجهة برمجة التطبيقات الخاصة بالخطافات

يستخدم هذا الدرس واجهة برمجة التطبيقات REST إصدار 2 لإنشاء خطافات على وكيل مخصص. تبويب محرر YAML في البوابة يظهر تنسيق v1 ولا يعرض الخطافات المهيأة عبر واجهة برمجة التطبيقات (API)، لكن الخطافات لا تزال نشطة. يمكنك التحقق منها في صفحة Builder>Hooks أو في ملعب الاختبار.

نصيحة

متى تستخدم واجهة برمجة التطبيقات مقابل البوابة:

• Portal (خطافات البناء > ): الأفضل للخطافات على مستوى العميل في شكل بصري. لا توجد تعليمات برمجية ضرورية.
• واجهة برمجة التطبيقات (هذا الدرس): الأفضل للخطافات على مستوى الوكيل المخصص، أو خطوط أنابيب CI/CD، أو الإدارة البرمجية.

ابحث عن رابط واجهة برمجة التطبيقات الخاصة بوكيلك

رابط قاعدة واجهة برمجة التطبيقات الخاص بوكيلك يتبع هذا النمط:

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

للعثور عليه:

1. افتح sre.azure.com واختر وكيلك.
2. في الشريط الجانبي الأيسر، اختر Builder>Agent Canvas.
3. افتح أدوات المطور في متصفحك (F12 أو انقر > بزر الفحص).
4. اذهب إلى تبويب الشبكة ، وفلتر حسب "api"، وابحث عن طلبات إلى عنوان URL ينتهي ب .azuresre.ai.
5. رابط القاعدة هو كل ما قبل /api/....

بدلا من ذلك، تحقق من السمة src في تبويب العناصر . ابحث عن التي <iframe>src تبدأ ب https://{agent-name}--.

الحصول على رمز مميز للوصول

شغل الأمر التالي للحصول على رمز وصول لواجهة برمجة تطبيقات وكيل SRE:

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

أنشئ وكيل مخصص باستخدام خطاف إيقاف

تنشئ هذه الخطوة وكيلا مخصصا يسمى my_hooked_agent بخطاف إيقاف يتحقق مما إذا كانت الاستجابة تنتهي ب === RESPONSE COMPLETE ===. إذا كانت العلامة مفقودة، يرفض الخطاف الرد ويأمر الوكيل بإضافة العلامة.

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

تحصل على HTTP 202 مقبولة مع تكوين الوكيل الكامل في جسم الرد.

المثال التالي يوضح نفس التكوين بصيغة v2 YAML للرجوع إليه:

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

كيف يعمل خطاف الإيقاف

يقيم خطاف الإيقاف استجابة الوكيل قبل أن يعود إلى المستخدم:

• يستبدل $ARGUMENTS JSON بالسياق الخطافي، والذي يتضمن رد الوكيل النهائي.
• يقوم نموذج اللغة الكبيرة بتقييم السؤال ويعيد {"ok": true} أو {"ok": false, "reason": "..."}.
• إذا تم رفضه، يستمر الوكيل في العمل بعد حقن السبب كرسالة مستخدم.
• بعد ثلاث حالات رفض (الوضع الافتراضي)، يتوقف الوكيل.

اختبر الخطاف في البوابة

اتبع هذه الخطوات لاختبار خطاف الإيقاف:

1. اذهب إلى وكيلك في البوابة واختر Builder>Agent Canvas.

2. اختر زر اختبار راديو ملعب اللعب.

3. اختر قائمة الوكيل الفرعي/الأداة ، وابحث عن my_hooked_agent، واختر تطبيق.

   

4. اكتب What is 2+2? في الدردشة واختر إرسال.

شاهد ما سيحدث:

• يرد الوكيل أولا برقم 4.
• خطاف التوقف يقيم ويرفض الاستجابة (بدون علامة إكمال).
• تظهر خطوة عملية التفكير حيث يواصل الوكيل.
• يظهر الرد النهائي: 4 === اكتمال الرد ===.

نجح الخطاف. أجبر الوكيل على إضافة العلامة قبل التوقف.

إضافة خطاف PostToolUse للتدقيق

أضف خطاف PostToolUse الذي يسجل كل أداة يستخدمها الوكيل. قم بتحديث نفس الوكيل بإرسال طلب جديد PUT مع كلا الخطافين:

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: "*" يعني أن هذا الخطاف يعمل لكل نداء أداة. يقوم السكربت بتسجيل اسم الأداة ويحقن [AUDIT] رسالة في المحادثة.

لاختبار الخطاف، اسأل الوكيل سؤالا يشغل أداة (مثل "تشغيل echo hello").

حجب الأوامر الخطرة

أضف خطاف PostToolUse ثان يمنع rm -rf، sudo، و 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"}))

الاختلافات الرئيسية عن خطاف التدقيق:

• matcher: "Bash|ExecuteShellCommand" تعمل فقط لأدوات الشل (النمط مثبت ك ^(Bash|ExecuteShellCommand)$).
• failMode: block يحظر نتيجة الأداة إذا تعطل السكريبت نفسه (الوضع الصارم).
• يعود "block" مع سبب عندما يتم اكتشاف نمط خطير.

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

خطافات الأوامر وخطافات الأوامر تستخدم صيغ استجابة مختلفة.

خطافات المحفز

تعيد خطافات الأوامر JSON بسيط:

{"ok": true}

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

خطافات القيادة

خطافات الأوامر تعيد JSON موسع:

{"decision": "allow"}

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

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

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

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

تنبيه

الرفض بدون سبب يعتبر موافقة. دائما أدرج reason عند الرفض.

تحقق

بعد أن تقوم بتكوين واختبار الخطافات، تأكد من الشروط التالية:

• تقوم بتكوين الخطافات على مستوى الوكيل المخصص باستخدام REST API v2. تنطبق فقط على ذلك الوكيل المخصص.
• أنت تنشئ خطافات على مستوى الوكيل في Builder > Hooks. تنطبق على جميع الوكلاء.
• خطاف الإيقاف يجعل العامل يضيف العلامة === RESPONSE COMPLETE === قبل التوقف.
• خطاف التدقيق PostToolUse يسجل [AUDIT] رسائل استدعاءات الأدوات.
• خطاف السياسة يمنع الأوامر الخطرة مثل rm -rf و sudo.

استكشاف الأخطاء وإصلاحها

الجدول التالي يوضح المشكلات الشائعة والحلول لخطافات الوكيل.

المشكلة	الحل
الخطاطيف غير مرئية في تبويب YAML الخاص بالبوابة	متوقع - تبويب YAML يظهر الإصدار الأول فقط. الروابط المخصصة على مستوى الوكيل التي يتم إنشاؤها عبر واجهة برمجة التطبيقات تكون نشطة ومرئية في خطافات البناء> أو في ساحة اللعب.
Unsupported kind: ExtendedAgent	استخدم نقطة النهاية v2: PUT /api/v2/extendedAgent/agents/{name}.
Handoffs cannot be null	أضف "handoffs": [] إلى حمولة JSON.
الخطاف لا يؤثر	أضف حقلا reason عند الرفض. بدونه، يعامل الرفض كموافقة.
حلقات الوكيل إلى الأبد	أقل maxRejections (الافتراضي: 3، النطاق: 1-25).

الخطوة التالية

تعرف على Agent Hooks.

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

• نظرة عامة على قدرات خطافات الوكيل
• إنشاء وإدارة الروابط (البوابة)
• أوضاع التشغيل
• تنفيذ كود بايثون