Erstellen eines Laufzeit-Bedrohungserkennungssystems für Copilot Studio-Agents

Organisationen können ihren Copilot Studio-Agents eine Sicherheitsebene hinzufügen, indem sie sie mit einem Laufzeit-Bedrohungserkennungssystem verbinden. Nach der Verbindung ruft der Agent dieses System zur Laufzeit auf. Der Agent stellt das System mit Daten bereit, damit das System ermitteln kann, ob ein Tool, das der Agent aufruft, legitim ist oder nicht. Das System antwortet dann auf Copilot Studio mit einer Antwort von "genehmigen" oder "Blockieren", wodurch der Agent das Tool aufruft oder entsprechend überspringt. Weitere Informationen zum Verbinden von Agents mit einem vorhandenen externen Bedrohungserkennungssystem finden Sie unter Enable external threat detection and protection for Copilot Studio custom agents.

Dieser Artikel richtet sich an Entwickler und beschreibt, wie Sie Ihre eigenen Bedrohungserkennungsfunktionen als Sicherheitsanbieter für Copilot Studio-Agents integrieren.

Die Integration basiert auf einer API, die aus zwei Endpunkten besteht. Der Hauptendpunkt, den Sie implementieren müssen, ist der analyze-tool-execution Endpunkt. Sie müssen diesen Endpunkt als Schnittstelle für Ihr Bedrohungserkennungssystem verfügbar machen. Sobald Kunden Ihr System als externes Bedrohungserkennungssystem konfigurieren, ruft der Agent diese API jedes Mal auf, wenn es ein Tool aufrufen möchte.

Neben dem analyze-tool-execution-Endpunkt müssen Sie auch einen zweiten Endpunkt mit dem Namen validate verfügbar machen. Der validate Endpunkt wird verwendet, um den Status und die Bereitschaft des Endpunkts im Rahmen der Systemeinrichtung zu überprüfen.

In den folgenden Abschnitten werden die einzelnen Endpunkte ausführlich beschrieben.

POST /validate

Zweck: Überprüft, ob der Endpunkt für die Bedrohungserkennung erreichbar und funktioniert. Wird für anfängliche Setup- und Konfigurationstests verwendet.

Überprüfen der Anforderung

• Methode: POST

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

• Kopfzeilen:

  • Autorisierung: Bearer-Token für die API-Authentifizierung

  • x-ms-correlation-id: GUID für die Ablaufverfolgung

• Körper: Leer

Überprüfen der Antwort

200 OK-Antwortbeispiel

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

Beispiel für Fehlerantwort

Wenn ein Fehler auftritt (nicht erfolgreicher HTTP-Code), gibt der Endpunkt einen Fehlercode, eine Meldung und optionale Diagnose zurück.

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

POST /analyze-tool-execution - Ausführung des Analysewerkzeugs

Zweck: Sendet den Toolausführungskontext für die Risikobewertung. Wertet die Toolausführungsanforderung aus und antwortet, ob die Ausführung des Tools zugelassen oder blockiert werden soll.

Analyse-Tool-Ausführungsanforderung

• Methode: POST

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

• Kopfzeilen:

  • Autorisierung: Bearer-Token für die API-Authentifizierung
  • Inhaltstyp: application/json

• Körper: JSON-Objekt

Beispiel für Ausführung einer Analyse-Tool-Anforderung

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

Antwort auf die Ausführung des Analysetools

200 OK (Anforderung erfolgreich)

Wenn die Anforderung gültig ist, wird die in der Anforderung angegebene Toolverwendung basierend auf den definierten Kriterien ausgewertet und entweder zugelassen oder blockiert. Die Antwort kann die folgenden Felder enthalten:

• blockAction (Boolean): Gibt an, ob die Aktion blockiert werden soll.
• reasonCode (ganze Zahl, optional): Numerischer Code, der den Grund für den Block erklärt
• Grund (Zeichenfolge, optional): Menschlich lesbare Erklärung
• Diagnose (Objekt, optional): Weitere Details zur Ablaufverfolgung oder zum Debuggen

Beispiel für antwort zulassen

{
  "blockAction": false
}

Beispiel für eine Blockantwort

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

Beispielfehlerantwort

Wenn die Anforderung ungültig ist, wird eine Fehlerantwort mit einem Fehlercode, einer Nachricht, einem HTTP-Status und einer optionalen Diagnose zurückgegeben.

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

Referenz zu Anforderungs- und Antwortkörperstrukturen

In den folgenden Tabellen werden die Inhalte verschiedener Objekte beschrieben, die in den Anforderungs- und Antworttexten für die Endpunkte verwendet werden.

Validierungsantwort

AnalyzeToolExecutionResponse

Fehlerantwort

Evaluierungsanfrage

PlannerContext

Chatnachricht

Werkzeugausführungsausgaben

ExecutionOutput

Werkzeugdefinition

Werkzeugeingabe

Werkzeugausgabe

ConversationMetadata

AgentContext

UserContext

Auslöserkontext

Authentifizierung

Die von Ihnen entwickelte Integration sollte Microsoft Entra ID Authentifizierung verwenden. Befolgen Sie die Anweisungen zum Integrieren von Apps, die Ihre Entwickler erstellen.

Schritte, die sie ausführen müssen, umfassen Folgendes:

• Erstellen Sie eine App-Registrierung für Ihre Ressource in Ihrem Mandanten.
• Machen Sie einen Bereich für Ihre Web-API verfügbar. Der verfügbar gemachte Bereich muss die Basis-URL für die Ressource sein, die der Kunden aufruft. Wenn die API-URL beispielsweise lautet https://security.contoso.com/api/threatdetection, muss https://security.contoso.comder verfügbar gemachte Bereich sein.
• Je nachdem, wie Sie Ihren Dienst implementieren, müssen Sie Autorisierungslogik implementieren und eingehende Token überprüfen. Sie müssen dokumentieren, wie der Kunde seine Apps autorisieren muss. Es gibt mehrere Möglichkeiten, dies zu tun, zum Beispiel durch eine Erlaubnisliste von App-IDs oder rollenbasierte Zugriffskontrolle (RBAC).

Antwortzeitanforderungen

Der Agent erwartet eine Antwort vom Bedrohungserkennungssystem innerhalb von weniger als 1.000 ms. Sie sollten sicherstellen, dass Ihr Endpunkt innerhalb dieses Zeitrahmens auf den Anruf antwortet. Wenn Ihr System nicht rechtzeitig reagiert, verhält sich der Agent so, als ob Ihre Antwort "zulassen" ist und das Tool aufruft.

API-Versionsverwaltung

In Anforderungen wird die API-Version über einen api-version Abfrageparameter angegeben (z. B api-version=2025-05-01. ). Ihre Implementierung sollte gegenüber anderen unerwarteten Feldern tolerant sein und sollte nicht fehlschlagen, wenn in Zukunft neue Werte hinzugefügt werden. Partner sollten die API-Version nicht überprüfen, da derzeit alle Versionen als nicht unterbrechend betrachtet werden. Partner sollten die API-Versionen nachverfolgen, die Anfrage jedoch nicht fehlschlagen lassen, wenn eine neue Version verfügbar ist.