Saltar al contenido principal

Microsoft Copilot Studio

Copilot Studio permite a una organización designar un proveedor externo de detección de amenazas. Una vez configurado, cada vez que el orquestador de un agente generativo decide invocar una herramienta, Copilot Studio envía la llamada propuesta a Beak AI Security y retiene la herramienta hasta que Beak responde. Si Beak la bloquea, el agente se detiene e informa al usuario que su mensaje fue bloqueado.

Este es el único control de Beak que ve una llamada a herramienta con sus argumentos resueltos, antes de que la herramienta se ejecute. El análisis a nivel de prompt ve lo que el usuario escribió; este ve lo que el agente está a punto de hacer — la dirección a la que un correo electrónico está a punto de enviarse en CCO, la ruta que se indicó a una herramienta de archivos que lea, la URL a la que se indicó a una herramienta de solicitudes que haga POST.

Nota: La detección externa de amenazas es una característica en vista previa de Microsoft. Microsoft indica que las características en vista previa no están destinadas para uso en producción y pueden cambiar. Trate esta integración como un piloto hasta que Microsoft la publique de forma general.

Para la configuración paso a paso — el lado de Beak, la aplicación de Entra y Power Platform, en el orden en que deben realizarse — consulte Configuración de la protección de Copilot Studio.

Qué ve Beak y qué no ve​

VeEl mensaje del usuario y el historial de conversación reciente, la razón declarada del planificador para elegir esta herramienta, las salidas de herramientas ejecutadas anteriormente, la definición de la herramienta y los valores de argumento resueltos
No veConversaciones que no invocan ninguna herramienta. Este gancho se activa únicamente en la invocación de herramientas — la cobertura a nivel de prompt en las superficies de Microsoft permanece con el análisis en línea de Beak
No se llama en absoluto paraAgentes clásicos. Copilot Studio omite la detección externa de amenazas a menos que el agente utilice orquestación generativa
No puede hacerRedacción. La respuesta del protocolo es un booleano — una llamada a herramienta puede bloquearse, pero nunca sanearse

Beak evalúa todo lo anterior según las políticas que ya utiliza en otras partes de AI Security. No se involucran nuevos validadores ni tipos de política.

Antes de comenzar​

Necesita:

  • Un Administrador de Power Platform para configurar la conexión.

  • Permiso para registrar una aplicación en su inquilino de Microsoft Entra.

  • La URL del endpoint para su entorno de Beak, proporcionada por su contacto de Beak. Úsela exactamente como se indica — la ruta es parte de cómo se enruta la solicitud, por lo que una versión abreviada llega al servicio incorrecto y devuelve una página web en lugar de una decisión. Tiene el siguiente aspecto:

    https://aisecurity.beakops.com/api/aisecurity/agentsecurity/t42-AbCdEfGhIjKlMnOpQrStUv

Nota: Regístrese en Beak primero. Realice el lado de Beak antes de presionar Guardar en el centro de administración de Power Platform — Guardar llama al endpoint /validate de Beak y falla si su aplicación de Entra no está registrada aún, y el error que muestra Microsoft ("There was a problem connecting to the protection provider") no indica que esa sea la razón.

Paso 1 — Registrarse en Beak​

Proporcione a su administrador de Beak dos valores de su inquilino de Entra:

ValorDónde encontrarlo
ID de directorio (inquilino)Entra ID → Información general
ID de aplicación (cliente)El registro de aplicación que crea en el Paso 2

Beak registra este par como el único emisor autorizado a usar su endpoint. Un token de cualquier otro inquilino o aplicación es rechazado, incluso contra la URL correcta.

Su administrador de Beak configura el resto en la misma pantalla — qué política evalúa estas llamadas a herramientas, si Beak aplica o solo observa, qué debe hacer una política de redacción aquí, qué ocurre si Beak no puede responder a tiempo y, opcionalmente, qué entornos de Power Platform están en ámbito. Cada uno se describe en Configuración de la protección de Copilot Studio, y todos pueden modificarse posteriormente sin afectar la URL de su endpoint.

Paso 2 — Configurar una aplicación de Microsoft Entra​

Copilot Studio se autentica utilizando Credenciales de identidad federada, que no requieren secretos: usted registra una aplicación, Copilot Studio se federa en ella y nunca se crea ni almacena ningún secreto compartido. No hay nada que rotar.

Microsoft proporciona un script que realiza todo el paso, y es la ruta recomendada porque calcula los valores codificados por usted:

.\Create-CopilotWebhookApp.ps1 `
  -TenantId "11111111-2222-3333-4444-555555555555" `
  -Endpoint "https://aisecurity.beakops.com/api/aisecurity/agentsecurity/t42-AbCdEfGhIjKlMnOpQrStUv" `
  -DisplayName "Beak AI Security - Production" `
  -FICName "BeakProductionFIC"

Descárguelo desde la PowerShell Gallery. Anote el App ID que imprime — el Paso 3 lo necesita, y también Beak (Paso 1).

Hacerlo manualmente​

Si registra la aplicación de forma manual, el Emisor y el Identificador de sujeto explícito de la credencial federada deben coincidir exactamente. Solicite ambas cadenas a su administrador de Beak — Beak las calcula a partir de su ID de inquilino y su URL de endpoint, lo que evita los errores de codificación que son la causa de la mayoría de las configuraciones fallidas:

  • Emisor — https://login.microsoftonline.com/{su ID de inquilino}/v2.0
  • Tipo — Identificador de sujeto explícito
  • Valor — /eid1/c/pub/t/{ID de inquilino codificado}/a/{segmento de aplicación}/{URL de endpoint codificada}

Los dos segmentos codificados son base64url sin relleno, y el ID de inquilino se codifica desde su orden de bytes de .NET, no el orden en que se escribe el GUID. Ese detalle es la razón por la que la codificación manual generalmente produce un sujeto que parece correcto pero nunca coincide.

Paso 3 — Configurar la detección de amenazas en Power Platform​

  1. Inicie sesión en el centro de administración de Power Platform.
  2. Vaya a Seguridad → Detección de amenazas → Detección de amenazas adicional.
  3. Seleccione el entorno que desea proteger y luego Configurar.
  4. Marque Permitir que Copilot Studio comparta datos con un proveedor de detección de amenazas.
  5. En ID de aplicación de Azure Entra, ingrese el App ID del Paso 2.
  6. En Enlace de endpoint, ingrese la URL del endpoint de Beak — exactamente la misma cadena que utilizó en el Paso 2, byte a byte.
  7. En Establecer comportamiento de error, elija qué ocurre cuando Beak no responde a tiempo. Consulte a continuación.
  8. Guardar.

Establecer el comportamiento de error — e informar a Beak lo que eligió​

El valor predeterminado de Microsoft es Permitir que el agente responda: si Beak no responde en un segundo, la herramienta se ejecuta. La alternativa es Bloquear la consulta.

Beak no puede leer esta configuración, así que informe a su administrador de Beak cuál eligió. Beak tiene un timeout_action correspondiente que debe coincidir: si no coincide, un momento en que Beak es lento produce una respuesta mientras su configuración de Power Platform espera la otra.

Nota: Esta configuración decide qué ocurre cuando el control no está disponible. Dejarla en Permitir que el agente responda significa que una interrupción de Beak devuelve silenciosamente sus agentes a una operación sin protección. Elegir Bloquear la consulta significa que una interrupción de Beak impide que sus agentes utilicen herramientas. Ninguna es incorrecta — pero es una decisión sobre qué fallo prefiere, y debe ser una decisión deliberada.

La configuración es por entorno​

No existe un interruptor a nivel de inquilino. Cada entorno de Power Platform debe configurarse individualmente, y un entorno recién creado no está protegido hasta que alguien active esto en él. Microsoft no proporciona ninguna API, cmdlet de PowerShell ni configuración del centro de administración para aplicarlo globalmente.

Incluya un paso en el proceso que utiliza su organización para crear entornos. De lo contrario, la cobertura decae silenciosamente a medida que crece el parque.

Comience en modo de observación​

Copilot Studio no tiene un modo de seguimiento propio, por lo que Beak proporciona uno, y está activado de forma predeterminada: Beak evalúa cada llamada a herramienta en su totalidad y registra lo que habría bloqueado, mientras responde "permitir".

Úselo. El radio de explosión de un falso positivo en este gancho no es un banner de advertencia — es un agente que se niega a completar una tarea que el usuario solicitó. El modo de observación le permite ver eso con tráfico real primero.

La secuencia recomendada:

  1. Observar — Beak registra los bloqueos que habría aplicado. Nada se bloquea; los usuarios no notan nada. Revise el Registro de Auditoria y ajuste la política.
  2. Aplicar, comportamiento de error = Permitir — Beak ahora bloquea. Una interrupción de Beak degrada a no protegido en lugar de roto.
  3. Comportamiento de error = Bloquear — solo una vez que esté satisfecho tanto con la tasa de bloqueos como con los tiempos de respuesta de Beak.

Solicite a su administrador de Beak que cambie entre etapas; cada una es una configuración por inquilino, modificada en el panel de Beak descrito en Configuración de la protección de Copilot Studio.

Decisiones que toma su administrador​

ConfiguraciónValor predeterminadoQué significa
AplicarDesactivado (observar)Si un bloqueo calculado se aplica realmente
Comportamiento de redacciónBloquearQué ocurre cuando una política dice "permitir esto con los valores sensibles eliminados". Este protocolo no puede reescribir un argumento de herramienta, por lo que no hay forma de respetar eso aquí. Bloquear es el valor predeterminado porque permitir enviaría la llamada a herramienta con el valor sensible intacto mientras la política seguía reportando como activa. Puede configurarse para permitir, como una elección deliberada
Comportamiento de tiempo de esperaPermitirQué responde Beak si la evaluación se aproxima a su plazo interno. Debe coincidir con su elección de Establecer comportamiento de error
PolíticaTodas las políticas activas en ámbitoQué política evalúa estas llamadas a herramientas
EntornosTodosOpcionalmente, reducir el ámbito a IDs de entorno de Power Platform específicos. Las llamadas a herramientas de otros entornos se permiten sin evaluación y se registran como fuera de ámbito

Cómo se ve una llamada a herramienta bloqueada​

El agente deja de procesar e informa al usuario que su mensaje fue bloqueado. Beak devuelve una breve explicación que nombra el tipo de contenido que lo activó — por ejemplo, "tarjeta de crédito", "SSN" — y nunca el valor en sí.

Esto es deliberado. El detalle que necesita un investigador (qué coincidió, dónde, qué regla se activó, qué política) se escribe en el Registro de Auditoria de Beak dentro de su inquilino, y nunca se envía a Microsoft. Un control que enviara el secreto que acaba de detectar a la telemetría de un tercero sería peor que ningún control.

Cada evaluación se registra, tanto si bloqueó, permitió, habría bloqueado en modo de observación, estaba fuera de ámbito o no pudo responderse a tiempo — de modo que "no se encontró nada" siempre sea distinguible de "no se examinó nada".

Manejo de datos​

Una vez configurado, Copilot Studio comparte los datos enumerados en Qué ve Beak con Beak AI Security en tiempo de ejecución.

Confirme con su contacto de Beak qué región procesa este tráfico y verifique que cumpla con los requisitos de su organización antes de habilitarlo en un entorno de producción. Puede desconectarlo en cualquier momento desmarcando la casilla del Paso 3, lo que detiene el intercambio de datos inmediatamente.

Solución de problemas​

Errores de Microsoft al presionar Guardar:

ErrorQué suele significar
There was a problem connecting to the protection providerBeak no aceptó la llamada. Lo más habitual es que la aplicación de Entra aún no esté registrada en Beak (Paso 1), o que la integración no esté habilitada para su entorno de Beak
The application ID in your authentication token doesn't match the registered applicationEl App ID en Power Platform no es el registrado en Beak. Compruebe si se copió el ID de objeto en lugar del ID de aplicación
AADSTS700016: Application with identifier … wasn't foundEl App ID no existe en su inquilino
AADSTS70025: … has no configured federated identity credentialsEl Paso 2 no se completó, o la credencial se añadió a una aplicación diferente
AADSTS7002111: No matching federated identity record found for presented assertion issuerEl Emisor de la FIC es incorrecto. Debe ser https://login.microsoftonline.com/{tenant ID}/v2.0
AADSTS7002137: No matching federated identity record found for presented assertion subjectEl sujeto de la FIC es incorrecto — generalmente un error de codificación, o una URL de endpoint que difiere de la introducida en Power Platform por una barra diagonal al final. Solicite a Beak la cadena exacta
To change a configuration, make sure you have Power Platform admin permissionsNecesita el rol de Administrador de Power Platform

Seleccione Copiar información de error en Power Platform para obtener el detalle completo.

La URL del endpoint no puede cambiarse posteriormente​

La URL del endpoint está codificada en el sujeto de la credencial federada, y Entra la coteja exactamente. Cambiarla — incluso añadiendo una barra diagonal al final — rompe la credencial, Copilot Studio ya no puede obtener un token, y como el protocolo falla abierto, sus agentes vuelven a invocar herramientas sin control sin que se muestre ningún error en ningún lugar de Power Platform.

Si alguna vez necesita una URL diferente, trátelo como un cambio coordinado: actualice la credencial federada y el enlace de endpoint juntos, y luego confirme que una llamada a herramienta sigue apareciendo en el Registro de Auditoria de Beak.

Relacionado​