Microsoft Agent 365

Microsoft Agent 365 responde qué agentes existen, quién los posee y a qué pueden acceder. Beak responde cómo se comportan en tiempo de ejecución. Esta integración conecta ambos, en ambas direcciones:

Entrante — los agentes de su entorno de Agent 365 / Entra Agent ID se sincronizan en Beak, donde pueden incorporarse al Registro de Agentes y gestionarse como cualquier otro agente.
Saliente — cualquier agente de Beak puede agregar o actualizar propiedades personalizadas en un agente de Agent 365. Esas propiedades son atributos de seguridad personalizados de Entra en la entidad de servicio del agente, sobre los que una política de Acceso Condicional puede filtrar.

La segunda dirección es el propósito de la integración: permite que una política de Acceso Condicional actúe sobre una señal de comportamiento que solo Beak puede producir.

El uso propio de Beak de ese canal es el Agent Risk Score — una puntuación consolidada de 0 a 100 por agente gobernado, escrita en cada entidad de servicio vinculada para que una política de Acceso Condicional pueda aplicarla. Configure primero la credencial a continuación; los ajustes de sincronización de riesgo se almacenan junto a ella.

Requisitos previos

Registre una aplicación de Entra ID en su propio inquilino y concédale:

Permiso	Usado para
`Application.Read.All`	lectura del inventario de agentes
`CustomSecAttributeAssignment.ReadWrite.All`	escritura de propiedades personalizadas
`CustomSecAttributeAssignment.Read.All`	lectura de las mismas
`IdentityRiskyServicePrincipal.Read.All`	superposición del estado de riesgo propio de Entra (opcional)

Conceda el consentimiento del administrador para cada uno. También necesita un conjunto de atributos de seguridad personalizados definido en Entra para contener las propiedades que Beak escribe — el nombre predeterminado que usa Beak es Beak.

Advertencia: El permiso de Graph solo no es suficiente. La escritura de atributos de seguridad personalizados también requiere que la aplicación tenga el rol de directorio Attribute Assignment Administrator. Sin él, cada escritura falla con 403, aunque el permiso de API esté consentido y aparezca como concedido.

Configuración

Vaya a Integraciones → Microsoft Agent 365 (consulte Integraciones).

Campo	Significado
Application (client) ID, Directory (tenant) ID, Client secret	El registro de aplicación de Entra. El secreto se cifra en reposo con la clave propia de su inquilino y nunca es devuelto por la API — déjelo en blanco al editar para conservar el almacenado.
Agents filter / Agent tag	Limita el inventario a agentes reales. Agents filter viene relleno con un valor predeterminado razonable — consulte a continuación antes de cambiarlo o borrarlo.
Onboarding mode	`Staged` (predeterminado) o `Auto` — consulte Incorporación.
Attribute set (avanzado)	El conjunto de atributos de seguridad personalizados de Entra en el que Beak escribe. Debe existir previamente en Entra. Valor predeterminado: `Beak`.
Property prefix (avanzado)	Cada nombre de propiedad que pueda escribirse debe comenzar con este prefijo. Valor predeterminado: `beak`.
Agents URL / Risky agents URL (avanzado)	Solo para inquilinos cuyo Graph expone una colección diferente. Déjelo en blanco en caso contrario.

Use Test connection antes de depender de ella. El resultado informa cuántas entidades de servicio se devolvieron y — lo que es importante — si la consulta fue limitada. Sync now ejecuta un único paso de inventario de forma inmediata.

Nota: Todo lo que aparece en esta pantalla también está disponible a través de la API — PUT /aisecurity/agent365 para guardar la credencial y las opciones, POST /aisecurity/agent365/test y .../sync para las dos acciones. Útil para la incorporación automatizada entre inquilinos.

Dónde encontrar todo

Dos lugares, y la división es deliberada.

Los agentes que Beak ya gobierna residen en el Registro de Agentes — el inventario único para cada agente gobernado, independientemente del entorno del que provenga. Un agente de Agent 365 incorporado aparece allí junto a los registrados de forma nativa, con un Origen de Agent 365 y el ID de objeto de entidad de servicio de Entra por el que es conocido allí. Filtre el registro por origen para ver solo estos; la página de Agent 365 enlaza directamente a esa vista filtrada.

Los agentes que Beak ha encontrado pero aún no gobierna residen en la página de Agent 365 bajo Configurar, que tiene tres pestañas:

Pestaña	Contenido
Discovery	Candidatos del último ciclo de sincronización. Promueva uno con Onboard o use Ignore para excluirlo. Una vez gobernado, desaparece de esta pestaña — el Registro de Agentes es donde reside.
Write grants	Las autorizaciones de escritura entre agentes. Créelas y revóquelas aquí.
Property writes	El registro de auditoría — cada intento, incluidas las denegaciones.

Nota: El Registro de Agentes muestra agentes Governed de forma predeterminada. Cambie su filtro Governance a Discovered o Excluded para verlos también allí — están en la misma lista, solo que no adoptados. La pestaña Discovery de la página de Agent 365 es la superficie de flujo de trabajo para actuar sobre ellos.

Advertencia: El estado de gobernanza no es lo mismo que el Estado. Status (Activo / Inactivo / Suspended) indica si un agente que Beak gobierna puede actuar en este momento. El estado de gobernanza indica si Beak lo gobierna en absoluto. Un agente Discovered no es un agente suspendido — aún no es suyo, y no puede autenticarse independientemente de lo que diga el Estado.

Todos estos elementos incluyen los controles estándar del panel: búsqueda y filtros que cubren el conjunto de datos completo en lugar de solo la página visible, filtros y ordenación por columna, un selector de columnas que recuerda su selección, exportación a CSV y PDF según los filtros aplicados, y un intervalo de actualización automática. La pestaña de auditoría agrega un rango de tiempo.

Limitar el inventario a agentes

Los agentes de Agent 365 son entidades de servicio de Entra, y el directorio en el que residen mayoritariamente no contiene agentes — un inquilino típico alberga cientos de aplicaciones empresariales y registros de aplicaciones junto a un puñado de agentes.

Beak limita el inventario por usted de forma predeterminada. El campo Agents filter viene relleno con:

servicePrincipalType eq 'ServiceIdentity'

Entra clasifica una identidad de agente de Agent 365 o Copilot Studio como ServiceIdentity, mientras que las aplicaciones ordinarias y los registros de aplicaciones son Application. Como ese es un valor definido por Microsoft y no una convención que su inquilino eligió, es seguro aplicarlo sin necesidad de conocer nada sobre su directorio. En el primer inquilino donde se ejecutó, redujo el inventario de 353 entidades de servicio a un único agente real.

Puede reemplazarlo con cualquier filtro OData, o borrarlo para obtener el directorio sin limitar. Opciones de limitación:

Agents filter — un filtro OData evaluado por Graph. Predeterminado como se indica arriba; reemplácelo si su inquilino identifica agentes de otra manera.
Agent tag — una etiqueta que Beak compara en el lado del cliente, para inquilinos donde el filtro del lado del servidor no está disponible. No configurado de forma predeterminada: a diferencia de servicePrincipalType, una etiqueta de agente varía genuinamente según el inquilino y la etapa de implementación, por lo que adivinar una coincidiría silenciosamente con nada.

Si el filtro no coincide con nada, Test connection lo indica explícitamente en lugar de reportar un simple cero — distingue "limitado y sin coincidencias" de "este inquilino no tiene agentes", y nombra el filtro para que pueda ampliarlo.

Con el filtro borrado, la sincronización devuelve todas las entidades de servicio de su inquilino. Beak lo indica en lugar de ocultarlo: Test connection y cada informe de sincronización muestran si la consulta estaba limitada, y describen el recuento como entidades de servicio en lugar de agentes. La página de Agent 365 muestra un banner mientras el inventario no está limitado.

Nota: Esto importa sobre todo en el modo Auto, que incorpora todo lo que descubre la sincronización. Contra un directorio sin filtrar, eso registraría cada aplicación empresarial de su inquilino como agente gobernado por Beak en un solo ciclo. Por ello, Beak se niega a incorporar automáticamente un inventario sin filtrar y retrocede a solo descubrimiento, registrando el motivo. Configure un filtro — o, si realmente pretende gobernar todo el directorio, opte explícitamente por ello con allow_unfiltered_auto_onboard.

Incorporación: `Staged` vs `Auto`

Modo	Comportamiento
`Staged` (predeterminado)	La sincronización descubre agentes en una cola. Un administrador promueve cada uno deliberadamente.
`Auto`	La sincronización incorpora cada agente recién descubierto por sí misma — siempre que el inventario esté limitado.

Cada agente sincronizado obtiene una entrada en el Registro de Agentes en el momento en que se detecta — por lo que el registro es realmente una sola lista — pero la entrada lleva un estado de gobernanza que indica si Beak lo ha adoptado:

Discovered — presente en Agent 365, aún no adoptado. No puede autenticarse: Beak rechazará una solicitud que reclame la identidad de este agente, porque nadie ha decidido gobernarlo aún.
Governed — adoptado, gobernado en tiempo de ejecución y capaz de autenticarse. Esto es lo que el Registro de Agentes muestra de forma predeterminada.
Excluded — deliberadamente mantenido fuera de la adopción. Como un candidato, no puede autenticarse.

Excluded se respeta en ambos modos. Cambiar un inquilino de Staged a Auto nunca resucita un agente que fue previamente excluido.

El ID de perfil de Beak de un agente se deriva del ID de objeto de entidad de servicio de Entra, por lo que una nueva sincronización nunca crea un duplicado. Adoptar uno mueve su estado de gobernanza a Governed y refleja el indicador de habilitación propio de Microsoft en su Estado, en lugar de asumir que debe estar activo.

La sincronización se ejecuta cada hora; Sync now ejecuta un único paso de forma inmediata. Promueva un agente descubierto con Onboard, o exclúyalo con Ignore.

Propiedades personalizadas

Quién puede escribir

Dado que estas propiedades alimentan el Acceso Condicional, escribir una cambia lo que Microsoft permitirá que ese agente alcance. Cuatro condiciones deben cumplirse antes de que Beak llame a Graph:

el destino es un agente que Beak ha sincronizado realmente desde su inventario — no un ID de objeto arbitrario,
cada nombre de propiedad está dentro de su prefijo configurado,
el llamante está autorizado para ese destino, y
cuando una concesión nombra propiedades específicas, cubre cada propiedad de la solicitud.

Un agente siempre puede escribir en su propia entidad de servicio vinculada. Escribir en las propiedades de un agente diferente requiere una concesión de escritura explícita.

Esa restricción es el punto: sin ella, un agente podría reducir el beakRiskScore de otro agente y desactivar la política de Acceso Condicional destinada a contenerlo. Una concesión puede limitarse a propiedades con nombre — por ejemplo, permitiendo beakGuardrailStatus pero no beakRiskScore.

Escribir desde un agente

POST /aisecurity/agent365/properties
Content-Type: application/json
x-agent-signature: <base64 Ed25519 signature>
x-agent-timestamp: 2026-08-13T09:00:00Z
x-agent-nonce: <unique per request>

{
  "agent_id": "my-agent",
  "object_id": "11111111-2222-3333-4444-555555555555",
  "properties": { "beakRiskScore": "72", "beakGuardrailStatus": "blocked" }
}

object_id es el ID de objeto de entidad de servicio de Entra del agente. Se muestra en la fila del agente tanto en la pestaña Discovery como en la columna Origen del Registro de Agentes, y es el mismo valor que Entra muestra para esa entidad de servicio.

Advertencia: Una solicitud firmada es obligatoria aquí. Este endpoint requiere una atestación Ed25519 válida incluso cuando el perfil del agente no requiere atestación de otro modo. Un agente sin clave de firma activa es rechazado con 403. Genere primero un par de claves desde el Registro de Agentes.

Dos comportamientos que vale la pena conocer:

Los valores siempre se almacenan como cadenas. Los filtros de aplicación de Acceso Condicional solo coinciden con atributos de tipo cadena, por lo que una puntuación escrita como número se guardaría correctamente y luego nunca sería coincidente por la política destinada a consumirla. Beak convierte por usted.
Las escrituras se fusionan. Las propiedades que no nombra conservan su valor actual, por lo que agregar o actualizar es una sola llamada. Envíe null como valor para eliminar una propiedad.

Escribir como administrador

Abra un agente desde la pestaña Discovery, o desde el Registro de Agentes una vez gobernado, y use Details para ver y editar sus propiedades. El editor rechaza un nombre fuera del prefijo permitido antes de que pueda enviarlo, y borrar un valor elimina el atributo en lugar de almacenar una cadena vacía. Requiere el permiso agents:update. Las concesiones no se aplican a un administrador, pero las reglas de inventario y prefijo sí.

Auditoría

Cada intento queda registrado en la pestaña Property writes — incluidos los rechazados. Una escritura denegada repetidamente es en sí misma una señal de seguridad significativa, por lo que el registro sería engañoso si solo contuviera éxitos.

Cada registro conserva el valor anterior de la propiedad, porque Graph en sí no mantiene historial de atributos: lo que Beak no capture en el momento de la escritura es irrecuperable.

Actuar sobre las propiedades en el Acceso Condicional

Confirme que el atributo aparece en la entidad de servicio del agente en Entra.
Cree una política de Acceso Condicional y delimítela usando filter for applications sobre su atributo, por ejemplo beakRiskScore.
La política ahora actúa sobre el veredicto en tiempo de ejecución de Beak.

El atributo debe ser de tipo cadena y debe residir en la entidad de servicio. El Acceso Condicional no puede filtrar por atributos de seguridad personalizados de un usuario, por lo que escribir en el tipo de objeto incorrecto produce una política que silenciosamente nunca coincide.

Solución de problemas

Síntoma	Causa probable
`403` que menciona Attribute Assignment Administrator	La aplicación carece del rol de directorio. El permiso de API solo no es suficiente.
`403 Write denied: … no write grant`	Una escritura entre agentes sin concesión. Agregue una, o escriba en la propia entidad de servicio del agente.
`403 … outside the allowlisted … namespace`	El nombre de la propiedad no comienza con su prefijo configurado.
`403 … has no active signing key`	Genere un par de claves para el agente llamante.
`401 Attestation failed`	Firma ausente o no válida, un nonce repetido, o desfase de reloj superior a cinco minutos.
`403 … not in this tenant's synced Agent 365 inventory`	Ejecute una sincronización, o compruebe el ID de objeto de entidad de servicio.
La sincronización devuelve muchos más agentes de lo esperado	No hay filtro configurado, por lo que la consulta devuelve todas las entidades de servicio.
El modo `Auto` no incorpora nada	El inventario no está filtrado, por lo que la incorporación automática fue retenida por diseño. Configure un filtro.
El atributo está establecido pero el Acceso Condicional nunca se activa	El valor no es de tipo cadena, o está en el objeto incorrecto.

Buenas prácticas

No borre el filtro antes de configurar Auto. Auto contra un inventario sin limitar es la única combinación que puede saturar su Registro de Agentes, razón por la que Beak lo rechaza. El filtro predeterminado ya gestiona esto; si lo reemplaza o lo borra, confirme el recuento con Test connection antes de cambiar de modo.
Comience en Staged. Incluso con un filtro, ejecute una sincronización en Staged y revise la cola antes de promover. Es la forma más económica de descubrir que su filtro es incorrecto.
Conceda al agente que gobierna, no a todos los agentes. Un agente no necesita concesión para escribir en su propia entidad de servicio. Reserve las concesiones explícitas para el uno o dos agentes cuya función es puntuar a otros, y limite cada concesión a las propiedades que realmente establece.
Nombre las propiedades por lo que significan, no por quién las estableció. beakRiskScore se lee claramente en un filtro de Acceso Condicional; beakAgentXOutput no, y el autor de la política rara vez es la persona que escribió el agente.
Trate las escrituras denegadas como una señal. Filtre la pestaña Property writes por denied — un recuento creciente de denegaciones contra un agente merece atención — un agente correctamente configurado no intenta repetidamente escrituras para las que no tiene concesión.
Verifique el atributo después de la primera escritura. Confirme en Entra que el valor llegó a la entidad de servicio y es de tipo cadena, antes de construir una política de Acceso Condicional que dependa de él.

Requisitos previos​

Configuración​

Dónde encontrar todo​

Limitar el inventario a agentes​

Incorporación: Staged vs Auto​

Propiedades personalizadas​

Quién puede escribir​

Escribir desde un agente​

Escribir como administrador​

Auditoría​

Actuar sobre las propiedades en el Acceso Condicional​

Solución de problemas​

Buenas prácticas​

Páginas relacionadas​