Tutorial: Creación y administración de enlaces en el portal

En este tutorial, creará dos enlaces de gobernanza mediante el portal: un enlace stop que aplica el formato de datos (tablas markdown con encabezados en negrita) y un enlace PostToolUse que bloquea comandos peligrosos de shell. Los enlaces se configuran en el nivel de agente (se aplica a todos los subprocesos y subagentes) y al nivel de subagente (se aplica a un subagente específico).

Tiempo estimado: 10 minutos

En este tutorial aprenderá a:

Prerrequisitos

• Un agente de SRE de Azure en estado en ejecución
• Rol de colaborador o superior en el recurso de agente SRE

Información sobre dónde se encuentran los enlaces en el portal

Los ganchos funcionan en dos niveles. Comprender esta distinción es un concepto arquitectónico clave.

Crear enlaces de nivel de agente

Los enlaces de nivel de agente se aplican a todo el agente, incluidos todos los subprocesos y cada subagente. Tienen modos de activación que controlan cuándo están activos.

Abrir la página Hooks

Siga estos pasos para ir a la página Hooks.

1. Vaya a sre.azure.com y seleccione el agente.
2. En la barra lateral, expanda Generador.
3. Seleccione Hooks.

Verá el encabezado Enlaces con una descripción, un botón Crear enlace y una cuadrícula de datos vacía (o una lista de enlaces existentes).

Creación de un gancho de parada

Un gancho Stop se activa cuando el agente está a punto de devolver una respuesta final. Úselo para validar la calidad de respuesta y aplicar reglas de formato.

1. Seleccione Crear enlace.

2. Rellene los campos del formulario:

   Campo	Importancia
   Nombre	require-table-format
   Tipo de evento	Parar
   Modo de activación	Siempre
   Descripción	Garantiza que las respuestas presentan datos estructurados como tablas markdown con encabezados en negrita

3. En Definición de enlace, mantenga el tipo de enlace establecido en Preguntar.

4. Mantenga el valor de Model establecido en Razonamiento rápido (valor predeterminado).

5. En el editor del prompt, introduzca el siguiente texto:

   Check the agent response below.
   
   $ARGUMENTS
   
   Does the response present any structured data (lists of items, comparisons, metrics) as a markdown table with **bold** column headers?
   If no structured data is present, approve.
   If structured data IS present as a table with bold headers: {"ok": true}
   If structured data is present but NOT formatted as a table: {"ok": false, "reason": "Reformat the structured data as a markdown table with **bold** column headers."}
   

6. Deje Tiempo de espera (s) en 30, Modo de error en Allowy Rechazos máximos en 3.

7. Haga clic en Guardar.

El cuadro de diálogo se cierra con una notificación de éxito. El enlace aparece en la cuadrícula de datos con tipo de evento Stop y Activation Always.

Probar el gancho Stop

Siga estos pasos para comprobar que el enlace Detener funciona correctamente.

1. En la barra lateral, seleccione Chat.
2. Escriba Comparar las ventajas y desventajas de Python frente a Go para compilar microservicios y seleccione Enviar.
3. Vea la respuesta del agente:
   • Inicialmente, el agente responde con una comparación de texto sin formato.
   • El enlace Stop evalúa y rechaza la respuesta porque los datos no están en una tabla.
   • El agente vuelve a formatear su respuesta como una tabla markdown con encabezados en negrita .

La respuesta final presenta la comparación como una tabla con formato similar al ejemplo siguiente:

Crear un gancho PostToolUse

Un enlace PostToolUse se activa después de que una herramienta termine de ejecutarse. Úselo para auditar el uso de herramientas, bloquear comandos peligrosos o agregar contexto adicional.

1. Vuelva a Builder>Hooks.

2. Seleccione Crear enlace.

3. Rellene el formulario:

   Campo	Importancia
   Nombre	block-dangerous-commands
   Tipo de evento	Uso de la herramienta de publicación
   Modo de activación	Siempre
   Descripción	Bloquea rm -rf, sudo y chmod 777 en comandos de shell
   Tipo de enlace	Comando
   Buscador de coincidencias de herramientas	Bash\|ExecuteShellCommand

4. Seleccione Python como lenguaje de script.

5. En el editor de scripts , escriba el siguiente 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"}))
   

6. Configura Modo de error en Bloquear (si el script falla, el resultado de la herramienta queda bloqueado).

7. Haga clic en Guardar.

Ambos ganchos aparecen ahora en la cuadrícula de datos de Hooks.

Probar el enlace PostToolUse

Siga estos pasos para comprobar que el enlace PostToolUse funciona correctamente.

1. En la barra lateral, seleccione Chat.
2. Pida al agente que ejecute un comando seguro: "Ejecute echo hello". El enlace permite este comando.
3. Pida al agente que ejecute un comando peligroso: "Ejecute rm -rf /tmp/test". El enlace bloquea este comando.

El comando seguro se ejecuta normalmente. El comando peligroso está bloqueado y el agente recibe un mensaje que explica por qué.

Edición y eliminación de enlaces de nivel de agente

Puede modificar o quitar enlaces existentes de la cuadrícula de datos Enlaces.

• Editar: seleccione el icono de edición en cualquier fila de enlace de la cuadrícula de datos, modifique los campos y seleccione Guardar.
• Eliminar: active la casilla situada junto a los enlaces que desea quitar, seleccione Eliminar en la barra de herramientas y confirme.

La cuadrícula de datos refleja inmediatamente los cambios.

Cree enlaces de nivel de subagente

Los ganchos a nivel de subagente se configuran directamente en la definición de un subagente. Solo se aplican cuando se ejecuta ese subagente específico, y no se aplican al agente principal ni a otros subagentes.

Abra el panel de enlaces de subagentes

Siga estos pasos para acceder a la configuración del hook de un subagente específico.

1. En la barra lateral, expanda Generador y seleccione Generador de subagentes.
2. Seleccione un subagente existente para editarlo o seleccione Crear para iniciar uno nuevo.
3. En el formulario de subagente, desplácese hacia abajo hasta la sección Enlaces .
4. Seleccione Administrar enlaces.

Se abre un panel lateral con secciones Stop y Post Tool Use . Si no hay ganchos configurados, verá estados vacíos con texto de guía.

Añada un enlace a un subagente

Los pasos siguientes agregan un gancho de parada que garantiza que este subagente siempre responda con una sección de resumen.

1. En el panel Administrar enlaces , seleccione Agregar enlace en la parte inferior del panel.

2. En el cuadro de diálogo, rellene el formulario de enganche:

   Campo	Importancia
   Tipo de evento	Parar
   Tipo de enlace	Pronto
   Aviso	Check the response below. $ARGUMENTS Does it include a clear summary section at the end? If yes: {"ok": true} If no: {"ok": false, "reason": "Add a Summary section at the end of your response."}
   Tiempo de espera (s)	30
   Modo de fallo	Permitir
   Número máximo de rechazos	3

3. Seleccione Guardar en el enlace.

4. Seleccione Crear (o Guardar) en el subagente para guardar la configuración completa.

El enlace aparece en el panel Administrar enlaces en la sección Detener . El formulario de subagente muestra Administrar Hooks (1) en el botón.

Administre los enlaces por subproceso

Los enlaces de nivel de agente que están activados Siempre están activos en cada conversación de forma predeterminada. Debe activar manualmente los enlaces con la activación A demanda por subproceso.

Alterne enlaces en una conversación

Siga estos pasos para activar o desactivar enlaces en un subproceso específico.

1. Abra un hilo de chat.
2. Seleccione el + botón en el pie de página de chat.
3. Seleccione Administrar enlaces.
4. Active y desactive enlaces para el subproceso actual.

Puede desactivar los ganchos Always temporalmente. Puede activar enlaces A demanda cuando sea necesario. No se pueden activar y desactivar los enlaces que requiere el sistema.

Los cambios de enlaces se aplican inmediatamente en el subproceso actual.

Solución de problemas

En la tabla siguiente se enumeran los problemas y soluciones comunes al crear y administrar enlaces en el portal.

Paso siguiente

Contenido relacionado

• Introducción a la funcionalidad de enlaces de agente
• Tutorial: Configuración de enlaces de agente a través de la API REST
• Modos de ejecución