Compartir a través de

Creación de 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 mediante la conexión 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 proporciona al sistema datos para que el sistema pueda determinar si una herramienta que el agente planea invocar es legítima o no. A continuación, el sistema responde a Copilot Studio con una respuesta de "aprobar" o "bloquear", lo que hace que el agente invoque o omita la herramienta en consecuencia. Para obtener más información sobre cómo conectar agentes a un sistema de detección de amenazas externo existente, consulte Habilitación de la detección y protección de amenazas externas para agentes personalizados de Copilot Studio.

Este artículo está dirigido a desarrolladores y describe cómo integrar sus propias funcionalidades de detección de amenazas como proveedor de seguridad para 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 analyze-tool-execution punto de conexión. Debe exponer este punto de conexión como una interfaz para el sistema de detección de amenazas. Una vez que los clientes configuran el sistema como su sistema de detección de amenazas externo, el agente llama a esta API cada vez que pretende invocar una herramienta.

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

En las secciones siguientes se describe cada punto de conexión con detalle.

POST /validate

Propósito: Comprueba que el punto de conexión de detección de amenazas es accesible y funciona. Se usa para la configuración inicial y las pruebas de configuración.

Validar solicitud

  • Método: EXPONER

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

  • Encabezados:

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

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

  • Cuerpo: Vacío

Validación de la respuesta

Ejemplo de respuesta ok 200

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

Ejemplo de respuesta de error

Si se produce un error (código HTTP incorrecto), el punto de conexión devuelve un código de error, un mensaje y un diagnóstico opcional.

{
  "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 se debe permitir o bloquear la ejecución de la herramienta.

Solicitud analyze-tool-execution

  • Método: EXPONER

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

  • Encabezados:

    • Autorización: token de portador para la autenticación de API
    • Content-Type: application/json

  • Cuerpo: Json (objeto)

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

Respuesta analyze-tool-execution

200 Ok

Cuando la solicitud es válida, el uso de la herramienta especificado en la solicitud se evalúa y se permite o bloquea, en función de 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 explica el motivo del bloque
  • reason (string, optional): Explicación legible del usuario
  • diagnósticos (objeto, opcional): otros detalles para el seguimiento o la depuración

Ejemplo de respuesta permitida

{
  "blockAction": false
}

Respuesta de bloque de ejemplo

{
  "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 solicitud y respuesta

En las tablas siguientes se describe el contenido de varios objetos usados en los cuerpos de solicitud y respuesta de los puntos de conexión.

ValidationResponse

Nombre Tipo Required Descripción
isSuccessful Boolean Sí Indica si se ha superado la validación.
estado cuerda / cadena Sí Mensaje de estado opcional o detalle específico del asociado.

AnalyzeToolExecutionResponse

Nombre Tipo Required Descripción
blockAction Boolean Sí Indica si la acción debe bloquearse.
códigoDeRazón entero No Código de motivo numérico opcional, determinado por el asociado.
reason cuerda / cadena No Explicación opcional legible.
diagnostics cuerda / cadena No Información de diagnóstico de forma libre opcional para la depuración o telemetría. Debe estar preserializado.

ErrorResponse

Nombre Tipo Required Descripción
código de error entero Sí Identificador numérico del error (por ejemplo, 1001 = campo que falta, 2003 = error de autenticación).
Mensaje cuerda / cadena Sí Explicación legible del error.
httpStatus entero Sí Código de estado HTTP devuelto por el asociado.
diagnostics cuerda / cadena No Información de diagnóstico de forma libre opcional para la depuración o telemetría. Debe estar preserializado.

EvaluationRequest

Nombre Tipo Required Descripción
plannerContext PlannerContext Sí Datos de contexto de Planner.
toolDefinition ToolDefinition Sí Detalles de la definición de la herramienta.
inputValues Json (objeto) Sí Diccionario de pares clave-valor proporcionados a la herramienta.
conversationMetadata ConversationMetadata Sí Metadatos sobre el contexto de conversación, el usuario y el seguimiento del plan.

PlannerContext

Nombre Tipo Required Descripción
mensajeDeUsuario cuerda / cadena Sí Mensaje original enviado por el agente.
pensamiento cuerda / cadena No Explicación de Planner para por qué se seleccionó esta herramienta.
chatHistory ChatMessage[] No Lista de mensajes de chat recientes intercambiados con el usuario.
previousToolsOutputs ToolExecutionOutput[] No Lista de salidas de herramientas recientes.

ChatMessage

Nombre Tipo Required Descripción
id cuerda / cadena Sí Identificador único de este mensaje en la conversación.
role cuerda / cadena Sí Origen del mensaje (por ejemplo, usuario, asistente).
contenido cuerda / cadena Sí Texto del mensaje.
marca de tiempo string (fecha y hora) No Marca de tiempo ISO 8601 que indica cuándo se envió el mensaje.

ToolExecutionOutputs

Nombre Tipo Required Descripción
toolId cuerda / cadena Sí Identificador único de este mensaje en la conversación.
toolName cuerda / cadena Sí Nombre de la herramienta.
Salidas ExecutionOutput[] Sí Lista de las salidas de ejecución de la herramienta.
marca de tiempo string (fecha y hora) No Marca de tiempo ISO 8601 que indica cuándo finalizó la ejecución de la herramienta.

ExecutionOutput

Nombre Tipo Required Descripción
nombre cuerda / cadena Sí Nombre del parámetro de salida.
descripción cuerda / cadena No Explicación del valor de salida.
type objeto No Tipo de datos de la salida.
value Valor de datos JSON Sí El valor de salida.

ToolDefinition

Nombre Tipo Required Descripción
id cuerda / cadena Sí Identificador único de la herramienta.
type cuerda / cadena Sí Especifica el tipo de herramienta que se usa en el planificador.
nombre cuerda / cadena Sí Nombre legible de la herramienta.
descripción cuerda / cadena 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 después de la ejecución.

ToolInput

Nombre Tipo Required Descripción
nombre cuerda / cadena Sí Nombre del parámetro de entrada.
descripción cuerda / cadena No Explicación del valor esperado para este parámetro de entrada.
type Json (objeto) No Tipo de datos del parámetro de entrada.

ToolOutput

Nombre Tipo Required Descripción
nombre cuerda / cadena Sí Nombre del parámetro de salida.
descripción cuerda / cadena No Explicación del valor de salida.
type Json (objeto) No Tipo del valor de salida.

ConversationMetadata

Nombre Tipo Required Descripción
agente AgentContext Sí Información de contexto del agente.
user UserContext No Información sobre el usuario que interactúa con el agente.
trigger TriggerContext No Información sobre lo que desencadenó la ejecución del planificador.
Id de conversación cuerda / cadena Sí Identificador de la conversación en curso.
planId cuerda / cadena No Identificador del plan usado para satisfacer la solicitud del usuario.
planStepId cuerda / cadena No Paso dentro del plan correspondiente a esta ejecución de la herramienta.
parentAgentComponentId cuerda / cadena No Identificador del componente primario del agente.

AgentContext

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

UserContext

Nombre Tipo Required Descripción
id cuerda / cadena No Id. de objeto de Microsoft Entra del usuario.
tenantId cuerda / cadena No Identificador de inquilino del usuario.

TriggerContext

Nombre Tipo Required Descripción
id cuerda / cadena No Identificador del desencadenador que desencadenó el planificador.
schemaName cuerda / cadena No Nombre del esquema de desencadenador que desencadenó el planificador.

Autenticación

La integración que desarrolle debe usar la autenticación de Id. de Microsoft Entra. Siga las instrucciones de Integración de aplicaciones compiladas por los desarrolladores.

Entre los pasos que se deben realizar se incluyen los siguientes:

  • Cree un registro de aplicación para el recurso en el inquilino.
  • Exponga un ámbito para la API web. El ámbito expuesto debe ser la dirección URL base del recurso al que llaman los clientes. Por ejemplo, si la dirección URL de la API es https://security.contoso.com/api/threatdetection, el ámbito expuesto debe ser https://security.contoso.com.
  • En función de cómo implemente el servicio, debe implementar la lógica de autorización y validar los tokens entrantes. Debe documentar cómo el cliente debe autorizar sus aplicaciones. Hay varias maneras de hacerlo, por ejemplo, usar una lista de permitidos de identificadores de aplicación o control de acceso basado en rol (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 el punto de conexión responde a la llamada dentro de este período de tiempo. Si el sistema no responde a tiempo, el agente se comporta como si la respuesta fuera "permitir", invocando la herramienta.

Control de versiones de API

En las solicitudes, la versión de la API se especifica a través de un api-version parámetro de consulta (por ejemplo, api-version=2025-05-01). La implementación debe ser tolerante a otros campos inesperados y no debería producir un error si se agregan nuevos valores en el futuro. Los asociados no deben comprobar la versión de la API, ya que todas las versiones en este momento se consideran no importantes. Los asociados deben realizar un seguimiento de las versiones de api, pero no producir un error en la solicitud al ver una nueva versión.

  • Last updated on