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 provoque l’appel de l’agent ou ignore l’outil en conséquence. Pour plus d’informations sur la connexion d’agents à un système de détection des menaces externe existant, consultez Activer la détection et la protection externes des menaces pour les agents personnalisés 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 le analyze-tool-execution point de terminaison. 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 /validate

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: PUBLIER

• 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 suivi

• 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: PUBLIER

• 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.

ValidationResponse

AnalyzeToolExecutionResponse

ErrorResponse

EvaluationRequest

PlannerContext

ChatMessage

ToolExecutionOutputs

ExecutionOutput

ToolDefinition

ToolInput

ToolOutput

ConversationMetadata

AgentContext

UserContext

TriggerContext

Authentication

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 une inscription d’application pour votre ressource dans votre locataire.
• 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, à l’aide d’une liste verte d’ID d’application ou d’un contrôle d’accès en fonction du rôle (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 considérées comme non cassants. Les partenaires doivent suivre les versions de l’API, mais ne pas échouer à la demande lors de l’affichage d’une nouvelle version.