Créer un système de détection des menaces runtime pour les agents Copilot Studio

Les organisations peuvent ajouter une couche de sécurité à leurs agents Copilot Studio en les connectant à un système de détection des menaces runtime. Une fois connecté, l’agent appelle ce système au moment de l’exécution. L’agent fournit au système des données afin que le système puisse déterminer si un outil que l’agent prévoit d’appeler est légitime ou non. Le système répond ensuite à Copilot Studio avec une réponse « approuver » ou « bloquer », ce qui amène l'agent à invoquer ou à ignorer l'outil en conséquence. Pour plus d’informations sur la façon de connecter des agents à un système existant de détection et de protection contre les menaces externes, consultez Activer la détection et la protection des menaces externes pour les agents personnalisés de Copilot Studio.

Cet article est destiné aux développeurs et décrit comment intégrer vos propres fonctionnalités de détection des menaces en tant que fournisseur de sécurité pour les agents Copilot Studio.

L’intégration est basée sur une API composée de deux points de terminaison. Le point de terminaison principal que vous devez implémenter est analyze-tool-execution. Vous devez exposer ce point de terminaison en tant qu’interface à votre système de détection des menaces. Une fois que les clients configurent votre système comme système de détection des menaces externe, l’agent appelle cette API chaque fois qu’il a l’intention d’appeler un outil.

Outre le analyze-tool-execution point de terminaison, vous devez également exposer un deuxième point de terminaison, appelé validate. Le validate point de terminaison est utilisé pour vérifier l’intégrité et la préparation du point de terminaison dans le cadre de la configuration du système.

Les sections suivantes décrivent chaque point de terminaison en détail.

POST /valider

But: Vérifie que le point de terminaison de détection des menaces est accessible et fonctionne. Utilisé pour le test initial d’installation et de configuration.

Valider la demande

• Méthode : POST

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

• En-têtes :

  • Autorisation : jeton du porteur pour l’authentification d’API

  • x-ms-correlation-id : GUID pour le traçage

• Corps: Vide

Valider la réponse

Exemple de réponse OK 200

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

Exemple de réponse d’erreur

Si une erreur se produit (code HTTP non réussi), le point de terminaison retourne un code d’erreur, un message et des diagnostics facultatifs.

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

POST /analyze-tool-execution

But: Envoie le contexte d’exécution de l’outil pour l’évaluation des risques. Évalue la demande d’exécution de l’outil et répond s’il faut autoriser ou bloquer l’exécution de l’outil.

Requête d’exécution de l’outil d’analyse

• Méthode : POST

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

• En-têtes :

  • Autorisation : jeton du porteur pour l’authentification d’API
  • Content-Type : application/json

• Corps: Objet JSON

Exemple de requête d’exécution de l’outil d’analyse

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

Réponse d’exécution de l’outil d’analyse

200 OK

Lorsque la requête est valide, l’outil utilisé dans la requête est évalué et autorisé oubloqué, en fonction des critères définis. La réponse peut inclure les champs suivants :

• blockAction (booléen) : indique si l’action doit être bloquée
• reasonCode (entier, facultatif) : code numérique expliquant la raison du bloc
• raison (chaîne, facultatif) : explication lisible par l’homme
• diagnostics (objet, facultatif) : autres détails pour le traçage ou le débogage

Exemple de réponse d’autorisation

{
  "blockAction": false
}

Exemple de réponse de bloc

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

Exemple de réponse d’erreur

Si la requête n’est pas valide, une réponse d’erreur est retournée avec un code d’erreur, un message, un état HTTP et des diagnostics facultatifs.

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

Informations de référence sur les structures de corps de requête et de réponse

Les tableaux suivants décrivent le contenu des différents objets utilisés dans les corps de requête et de réponse pour les points de terminaison.

RéponseDeValidation

AnalyzeToolExecutionResponse

Réponse d'erreur

Demande d'évaluation

PlannerContext

Message de chat

Résultats d'Exécution d'Outil

Résultat d'exécution

Définition d'Outil

ToolInput

Résultat de l'outil

ConversationMetadata

AgentContext

ContexteUtilisateur

ContexteDéclencheur

Authentification

L’intégration que vous développez doit utiliser l’authentification Microsoft Entra ID. Suivez les instructions sur l’intégration d’applications que vos développeurs créent.

Les étapes à suivre sont les suivantes :

• Créez un enregistrement d'application pour votre ressource dans votre client.
• Exposez une étendue pour votre API web. L’étendue exposée doit être l’URL de base de la ressource que les clients appellent. Par exemple, si l’URL de l’API est https://security.contoso.com/api/threatdetection, l’étendue exposée doit être https://security.contoso.com.
• Selon la façon dont vous implémentez votre service, vous devez implémenter la logique d’autorisation et valider les jetons entrants. Vous devez documenter la façon dont le client doit autoriser ses applications. Il existe plusieurs façons de procéder, par exemple en utilisant une liste de permissions d'identifiants d'application, ou un contrôle d'accès basé sur les rôles (RBAC).

Exigences en matière de temps de réponse

L’agent attend une réponse du système de détection des menaces dans moins de 1 000 ms. Vous devez vous assurer que votre point de terminaison répond à l’appel dans ce délai. Si votre système ne répond pas dans le temps, l’agent se comporte comme si votre réponse est « autoriser », appelant l’outil.

Contrôle de version des API

Dans les requêtes, la version de l’API est spécifiée via un api-version paramètre de requête (par exemple). api-version=2025-05-01 Votre implémentation doit être tolérante à d’autres champs inattendus et ne doit pas échouer si de nouvelles valeurs sont ajoutées à l’avenir. Les partenaires ne doivent pas vérifier la version de l’API, car toutes les versions sont actuellement considérées comme compatibles. Les partenaires doivent suivre les versions de l’API, mais ne pas échouer à la demande lors de l’affichage d’une nouvelle version.