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

현재 두 개의 후크 이벤트가 지원됩니다.

두 가지 수준의 후크

후크는 다음 두 수준에서 작동합니다.

두 수준 모두 공존할 수 있습니다. 에이전트 수준 후크와 사용자 지정 에이전트 수준 후크가 모두 동일한 이벤트와 일치하면 둘 다 실행됩니다. 에이전트 수준의 후크가 가장 먼저 실행됩니다.

실행 형식

LLM 또는 셸 스크립트를 사용하여 후크를 구현할 수 있습니다.

프롬프트 후크는 응답이 모든 사용자 문제를 해결하는지 확인하거나 조사가 충분히 철저했는지 확인하는 등 주관적인 평가에 강력합니다. 그들은 $ARGUMENTS 자리 표시자를 사용하여 전체 후크 컨텍스트를 받습니다. 프롬프트에 없는 경우 $ARGUMENTS 컨텍스트가 자동으로 추가됩니다. 대화 대본을 사용할 수 있는 경우, 프롬프트 후크는 ReadFile 및 GrepSearch 도구를 활용하여 LLM이 전체 대화 기록을 이해할 수 있도록 합니다.

명령 후크는 응답에 필요한 표식이 포함되어 있는지 확인하거나, 위험한 명령을 차단하거나, 도구 사용을 외부 시스템에 로깅하는 등 결정적 검사에 더 적합합니다.

이 접근 방식이 다른 이유

다음 표에서는 후크를 사용 또는 사용하지 않는 에이전트 동작을 비교합니다.

후크는 실행 모드 안전 컨트롤을 대체하지 않으며 이를 보완합니다. 실행 모드는 에이전트가 수행할 수 있는 작업을 제어합니다. 후크는 얼마나 잘 수행하고 결과에 어떤 일이 일어나는지 제어합니다.

이전 및 이후

후크 구성

후크를 만드는 가장 쉬운 방법은 포털 UI를 사용하는 것입니다.

1. 에이전트 수준 후크:빌더 → 후크로 이동 → 후크 만들기를 선택합니다.
2. 사용자 지정 에이전트 수준 후크:에이전트 캔버스로 이동하여 → 사용자 지정 에이전트를 선택 → 후크 관리.

다음 예제에서는 전체 후크 구성을 보여줍니다.

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 출력 대신 종료 코드를 사용할 수도 있습니다.

구성 참조

다음 표에서는 사용 가능한 모든 후크 구성 옵션을 설명합니다.

후크 컨텍스트 스키마

후크는 현재 이벤트에 대한 구조적 JSON 컨텍스트를 받습니다. 프롬프트 후크는 프롬프트 텍스트의 $ARGUMENTS 자리 표시자를 통해 컨텍스트를 수신합니다. 명령 훅은 stdin에서 JSON으로 컨텍스트를 수신합니다.

두 후크 형식 execution_summary 의 경우 필드에는 대화 내용에 대한 파일 경로 (인라인 콘텐츠 아님)가 포함됩니다. 프롬프트 후크의 경우 LLM은 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
}

제한

에이전트 후크에는 다음 제한이 적용됩니다.

예제: 모든 도구 사용 감사

다음 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. 매처를 구체적으로 명확히 하십시오. 지나치게 광범위한 PostToolUse 매처는 성능 문제를 일으킬 수 있습니다.
5. 후크를 철저히 테스트하라: 항상 거부하는 후크는 루프를 발생시킬 수 있습니다(maxRejections에 의해 완화됨).
6. stderr에 로그: 디버깅 출력을 위해 stderr를 사용합니다. 시스템은 stdout을 후크의 결과로 구문 분석합니다.

직접 사용해 보기

다음 스크린샷은 정지 후크의 동작을 보여줍니다. 처음에는 에이전트가 "4"로 응답하지만 완료 표식이 누락되어 후크가 응답을 거부합니다. 그런 다음 에이전트가 계속하여 표식을 추가합니다.

시작하기

관련 콘텐츠