Enlaces de agente en Azure SRE Agent

Los hooks son puntos de control personalizados que interceptan y controlan el comportamiento del agente en momentos clave. Use enlaces para aplicar puertas de calidad en las respuestas del agente, auditar y controlar el uso de herramientas, bloquear operaciones peligrosas con la aplicación de directivas y evitar la finalización temprana de tareas mediante la validación de la salida del agente.

El problema.

El agente ejecuta tareas de forma autónoma, investigando incidentes, ejecutando herramientas y generando respuestas. Pero la autonomía sin supervisión crea riesgos:

• Respuestas incompletas: el agente dice "listo" antes de abordar todo lo que solicitó.
• Uso de herramientas no estudiados: no tiene visibilidad sobre qué herramientas llama el agente o qué resultados obtiene.
• Sin aplicación de directivas: las operaciones peligrosas (comandos destructivos, cambios no autorizados) continúan sin control.
• Brechas de calidad: las respuestas pierden información crítica porque no hay ningún paso de validación.

Necesita una manera de interceptar el comportamiento del agente en momentos clave sin ralentizarlo ni quitar completamente su autonomía.

Funcionamiento de los enlaces de agente

Los enlaces son puntos de control personalizados que se adjuntan a eventos específicos de un agente. Cuando se desencadena un evento, el enlace evalúa la situación y decide si se debe permitir o bloquear la acción.

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

Actualmente se admiten dos eventos de enlace:

Dos niveles de ganchos

Los ganchos operan en dos niveles:

Ambos niveles pueden coexistir. Si un enlace de nivel de agente y un enlace de nivel de agente personalizado coinciden con el mismo evento, ambos se ejecutan. Los enlaces de nivel de agente se activan primero.

Tipos de ejecución

Puede implementar ganchos mediante un LLM o un script de shell.

Los enlaces de solicitud son eficaces para la evaluación subjetiva, como comprobar si una respuesta aborda todos los problemas del usuario o comprueba que una investigación era lo suficientemente exhaustiva. Usan el marcador de posición $ARGUMENTS para recibir el contexto completo del hook. Si $ARGUMENTS no está presente en la indicación, el contexto se anexa automáticamente. Cuando hay una transcripción de la conversación disponible, los enlaces de solicitud también reciben herramientas ReadFile y GrepSearch, lo que permite al LLM razonar acerca del historial completo de la conversación.

Los enlaces de comandos son mejores para las comprobaciones deterministas, como validar que una respuesta contiene marcadores necesarios, bloquear comandos peligrosos o usar herramientas de registro en un sistema externo.

Lo que hace que este enfoque sea diferente

En la siguiente tabla se compara el comportamiento del agente con y sin ganchos.

Los ganchos no reemplazan los controles de seguridad del modo de ejecución. Ellos los complementan. Los modos de ejecución controlan lo que el agente puede hacer. Los hooks controlan qué tan bien lo hace y lo que sucede con los resultados.

Antes y después

Configuración de enlaces

La manera más fácil de crear enlaces es a través de la interfaz de usuario del portal:

1. Enlaces de nivel de agente: Vaya a Generador → Enlaces → seleccione Crear enlace.
2. Ganchos de nivel de agente personalizados: Ir a Lienzo del agente → seleccione un agente personalizado → Administrar ganchos.

En el ejemplo siguiente se muestra una configuración de enlace completa:

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

Formato de respuesta del enlace

Los enlaces deben generar JSON. Se admiten dos formatos.

Formato simple (recomendado para enlaces de solicitud):

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

Formato expandido (recomendado para enlaces de comandos):

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

Los enlaces de comandos también pueden usar códigos de salida en lugar de la salida JSON:

Referencia de configuración

En la tabla siguiente se describen todas las opciones de configuración de enlace disponibles.

Esquema de contexto del enlace

Los enlaces reciben contexto JSON estructurado sobre el evento actual. Los enlaces de solicitud reciben contexto a través del marcador de posición $ARGUMENTS en el texto de la solicitud. Los enlaces de comandos reciben contexto como JSON en stdin.

Para ambos tipos de enlace, el campo execution_summary contiene una ruta de acceso de archivo a la transcripción de conversación (no contenido insertado). Para los enlaces de solicitud, el LLM obtiene las herramientas ReadFile y GrepSearch para acceder a este archivo. Para los enlaces de comandos, el archivo está disponible en la ruta de acceso especificada en el espacio aislado.

Campos comunes

Todos los ganchos reciben los siguientes campos:

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

Campos de enlace de detención

Los enlaces de detención reciben campos adicionales referentes a la salida final del agente.

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

Campos de enlace PostToolUse

Los ganchos de PostToolUse reciben campos adicionales sobre la ejecución de la herramienta.

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

Límites

Los siguientes límites se aplican a los enlaces del agente.

Ejemplo: Auditar todo el uso de herramientas

El siguiente enlace PostToolUse registra cada llamada de herramienta y agrega un mensaje de contexto de auditoría:

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

El additionalContext campo se agrega como mensaje de usuario a la conversación, lo que proporciona al agente visibilidad de la pista de auditoría.

Ejemplo: Requerir un marcador de finalización

El siguiente gancho Stop rechaza las respuestas que no terminan con "Task complete."

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

procedimientos recomendados

Siga estas instrucciones al configurar enlaces de agente:

1. Proporcione siempre un motivo al rechazar. Trate los rechazos sin razones como aprobaciones.
2. Usar tiempos de espera adecuados: los enlaces de larga duración ralentizan la ejecución del agente.
3. Controlar los errores de manera correcta: use failMode: allow a menos que se requiera una aplicación estricta.
4. Ser específico con los emparejadores: los emparejadores de postToolUse demasiado amplios pueden causar problemas de rendimiento.
5. Probar los enlaces exhaustivamente: los enlaces que siempre rechazan pueden provocar bucles (mitigados por maxRejections).
6. Registrar en stderr: use stderr para la salida de depuración. El sistema analiza sintácticamente stdout como el resultado del enlace.

Pruebe por sí mismo

En la captura de pantalla siguiente se muestra un gancho de detención en acción. El agente responde inicialmente con solo "4", pero el enlace rechaza la respuesta porque falta el marcador de finalización. A continuación, el agente continúa y agrega el marcador.

Empieza ahora

Contenido relacionado