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 Enable external threat detection and protection for Copilot Studio custom agents.

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. 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: POST

• 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 200 OK

{
  "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 /analizar-ejecucion-herramienta

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 de ejecución de herramienta de análisis

• Método: POST

• 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
  • Tipo-Contenido: application/json

• Cuerpo: objeto JSON

Ejemplo de solicitud de ejecución de herramienta de análisis

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 de ejecución de herramienta de análisis

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 autorizada

{
  "blockAction": false
}

Ejemplo de respuesta de bloque

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

RespuestaDeEjecuciónDeHerramientaDeAnálisis

ErrorResponse

SolicitudDeEvaluación

PlannerContext

Mensaje de Chat

ResultadosDeEjecuciónDeHerramienta

ExecutionOutput

Definición de Herramienta

ToolInput

SalidaDeHerramienta

MetadatosDeConversación

AgentContext

Contexto de Usuario

TriggerContext

Autenticación

La integración que desarrolle debe usar Microsoft Entra ID autenticación. 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 su entidad.
• 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 formas de hacerlo, por ejemplo, usando una lista de permisos de IDs 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 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 que no rompen la compatibilidad. Los socios deben realizar un seguimiento de las versiones de API, pero no deben fallar la solicitud al ver una nueva versión.