Ein Runtime-Bedrohungserkennungssystem für Copilot Studio-Agents erstellen

Organisationen können ihren Copilot Studio-Agent eine zusätzliche Schutzebene hinzufügen, indem sie diese mit einem Bedrohungserkennungssystem zur Laufzeit verbinden. Sobald die Verbindung hergestellt ist, ruft der Agent dieses System zur Laufzeit auf. Der Agent übermittelt dem System Daten, damit dieses feststellen kann, ob ein Tool, das der Agent ausführen möchte, legitim ist oder nicht. Das System antwortet dann auf Copilot Studio mit einer Genehmigen- oder Sperren-Antwort, wodurch der Agent das Tool entsprechend aufruft bzw. überspringt. Weitere Informationen darüber, wie Sie Agents mit einem bestehenden externen Bedrohungserkennungssystem verbinden, finden Sie unter Externe Bedrohungserkennung und Schutz für Copilot Studio benutzerdefinierte Agents aktivieren.

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

Die Integration basiert auf einer API mit zwei Endpunkten. Der wichtigste Endpunkt, den Sie implementieren müssen, ist der analyze-tool-execution Endpunkt. Sie müssen diesen Endpunkt als Schnittstelle zu Ihrem Bedrohungserkennungssystem bereitstellen. Sobald Kunden Ihr System als externes Bedrohungserkennungssystem eingerichtet haben, ruft der Agent diese API bei jedem geplanten Toolaufruf auf.

Neben dem analyze-tool-execution-Endpunkt müssen Sie auch einen zweiten Endpunkt bereitstellen, der validate genannt wird. Der validate-Endpunkt wird verwendet, um die Gesundheit und Funktionsfähigkeit des Endpunkts im Rahmen der Systemeinrichtung zu überprüfen.

Die folgenden Abschnitte beschreiben jeden Endpunkt detailliert.

POST /validate

Zweck: Überprüft, ob der Bedrohungserkennungsendpunkt erreichbar und funktionsfähig ist. Verwendet für die Ersteinrichtung und Konfigurationstests.

Anforderung validieren

  • Methode: POST

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

  • Headers:

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

    • x-ms-correlation-id: GUID zur Nachverfolgung

  • Text: Leer

Antworten validieren

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 Nachricht und optionale Diagnoseinformationen zurück.

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

POST /analyze-tool-execution

Zweck: Sendet den Kontext der Tool-Ausführung zur Risikobewertung. Bewertet die Tool-Ausführungsanfrage und entscheidet, ob die Tool-Ausführung erlaubt oder blockiert wird.

Tool-Ausführungsanforderung analysieren

  • Methode: POST

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

  • Headers:

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

  • Body: JSON Objekt

Beispiel für eine Analysieren-Tool-Ausführungsanfrage

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

Analysieren-Tool-Ausführungsantwort

200 OK

Wenn die Anfrage gültig ist, wird die in der Anfrage angegebene Toolnutzung bewertet und entweder erlaubt oder blockiert, basierend auf den definierten Kriterien. Die Antwort kann die folgenden Felder enthalten:

  • blockAction (boolesch): Ob die Aktion blockiert werden sollte
  • reasonCode (integer, optional): Numerischer Code, der den Grund für die Blockierung erklärt
  • reason (String, optional): Menschenlesbare Erklärung
  • diagnostics (object, optional): Weitere Details zum Nachverfolgen oder Debuggen

Beispiel für Antwort zulassen

{
  "blockAction": false
}

Beispiel für 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\\}"
}

Beispiel für Fehlerantwort

Falls die Anfrage ungültig ist, wird eine Fehlerantwort mit einem Fehlercode, einer Nachricht, einem HTTP-Status und optionalen Diagnoseinformationen zurückgegeben.

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

Referenz zu Anforderungs- und Antworttextstrukturen

Die folgenden Tabellen beschreiben die Inhalte verschiedener Objekte, die in den Anfrage- und Antwortkörpern der Endpunkte verwendet werden.

ValidationResponse

Name Type Erforderlich Beschreibung
isSuccessful Boolesch Ja Gibt an, ob die Validierung erfolgreich war.
status string Ja Optionale Statusnachricht oder partnerspezifisches Detail.

AnalyzeToolExecutionResponse

Name Type Erforderlich Beschreibung
blockAction Boolesch Ja Gibt an, ob die Aktion blockiert werden soll.
reasonCode Integer Nein Optionaler numerischer Grundcode, der vom Partner bestimmt wird.
reason Zeichenfolge Nein Optionale, für Menschen verständliche Erklärung.
diagnostics string Nein Optionale frei gestaltete Diagnoseinformationen für Debugging oder Telemetrie. Muss vorab serialisiert werden.

ErrorResponse

Name Type Erforderlich Beschreibung
errorCode Integer Ja Numerische Kennung für den Fehler (zum Beispiel 1001 = fehlendes Feld, 2003 = Authentifizierungsfehler).
Nachricht string Ja Für Menschen verständliche Erklärung des Fehlers.
httpStatus Integer Ja HTTP-Statuscode, der vom Partner zurückgegeben wird.
diagnostics string Nein Optionale frei gestaltete Diagnoseinformationen für Debugging oder Telemetrie. Muss vorab serialisiert werden.

EvaluationRequest

Name Type Erforderlich Beschreibung
plannerContext PlannerContext Ja Planer-Kontextdaten.
toolDefinition ToolDefinition Ja Details zur Definition des Tools.
inputValues JSON-Objekt Ja Dictionary mit Schlüssel-Wert-Paaren, das dem Tool bereitgestellt wird.
conversationMetadata ConversationMetadata Ja Metadaten über den Unterhaltungskontext, den Nutzer und die Planverfolgung.

PlannerContext

Name Type Erforderlich Beschreibung
userMessage string Ja Die ursprüngliche Nachricht des Agent.
Gedanken string Nein Erläuterung des Planners, warum dieses Tool ausgewählt wurde
chatHistory ChatMessage[] Nein Liste der kürzlich ausgetauschten Chatnachrichten mit dem Nutzer.
previousToolsOutputs ToolExecutionOutput[] Nein Liste der letzten Toolausgaben.

ChatMessage

Name Type Erforderlich Beschreibung
id Zeichenfolge Ja Eindeutige Kennung für diese Nachricht in der Unterhaltung.
role string Ja Quelle der Nachricht (z. B. Benutzer, Assistent).
Inhalt string Ja Der Nachrichtentext.
timestamp string (Datum/Uhrzeit) Nein ISO 8601 Zeitstempel, der angibt, wann die Nachricht gesendet wurde.

ToolExecutionOutputs

Name Type Erforderlich Beschreibung
toolId string Ja Eindeutige Kennung für diese Nachricht in der Unterhaltung.
toolName string Ja Name des Tools.
gibt aus ExecutionOutput[] Ja Liste der Toolausführungsausgaben.
timestamp string (Datum/Uhrzeit) Nein ISO 8601 Zeitstempel, der angibt, wann die Ausführung des Tools abgeschlossen wurde.

ExecutionOutput

Name Type Erforderlich Beschreibung
Name Zeichenfolge Ja Name des Ausgabeparameters.
Beschreibung Zeichenfolge Nein Erklärung des Ausgabewerts.
Typ object Nein Datentyp der Ausgabe.
value JSON Datenwert Ja Der Ausgabewert.

ToolDefinition

Name Type Erforderlich Beschreibung
id Zeichenfolge Ja Eindeutiger Bezeichner des Tools.
Typ string Ja Gibt die Art des im Planner verwendeten Tools an.
Name Zeichenfolge Ja Menschlich lesbarer Name des Tools.
Beschreibung Zeichenfolge Ja Zusammenfassung der Funktionen des Tools
inputParameters ToolInput[] Nein Eingabeparameter des Tools.
outputParameters ToolOutput[] Nein Ausgabeparameter, die das Tool nach der Ausführung zurückgibt.

ToolInput

Name Type Erforderlich Beschreibung
Name Zeichenfolge Ja Name des Eingabeparameters.
Beschreibung Zeichenfolge Nein Erklärung des erwarteten Werts für diesen Eingabeparameter.
Typ JSON-Objekt Nein Datentyp des Eingabeparameters.

ToolOutput

Name Type Erforderlich Beschreibung
Name Zeichenfolge Ja Name des Ausgabeparameters.
Beschreibung Zeichenfolge Nein Erklärung des Ausgabewerts.
Typ JSON-Objekt Nein Der Typ des Ausgabewerts.

ConversationMetadata

Name Type Erforderlich Beschreibung
Agent AgentContext Ja Agentkontextinformation.
-Benutzer UserContext Nein Informationen über den Nutzer, der mit dem Agent interagiert.
Trigger (trigger) TriggerContext Nein Informationen dazu, was die Planner-Ausführung ausgelöst hat.
conversationId string Ja ID der laufenden Unterhaltung.
planId string Nein ID des Plans, der zur Erfüllung der Nutzeranfrage verwendet wird.
planStepId string Nein Schritt innerhalb des Plans, der dieser Tool-Ausführung entspricht.
parentAgentComponentId string Nein ID der übergeordneten Agent-Komponente.

AgentContext

Name Type Erforderlich Beschreibung
id Zeichenfolge Ja Die ID des Agents.
tenantId string Ja Mandant, in dem sich der Agent befindet.
environmentId string Ja Umgebung, in der der Agent veröffentlicht wird.
version string Nein Agent-Version (optional, wenn isPublished falsch).
isPublished Boolesch Ja Gibt an, ob dieser Ausführungskontext eine veröffentlichte Version ist.

UserContext

Name Type Erforderlich Beschreibung
id Zeichenfolge Nein Microsoft Entra-Objekt-ID des Benutzers.
tenantId string Nein Mandanten-ID des Benutzers.

TriggerContext

Name Type Erforderlich Beschreibung
id Zeichenfolge Nein Die ID des Auslösers, der den Planner ausgelöst hat.
schemaName string Nein Der Name des Trigger-Schemas, das den Planner ausgelöst hat.

Authentifizierung

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

Durchzuführende Schritte, einschließlich der Folgenden:

  • Erstellen einer App-Registrierung für Ihre Ressource in Ihrem Mandanten.
  • Verfügbarmachen eines Umfangs für Ihre Web-API. Der verfügbar gemachte Bereich muss die Basis-URL für die Ressource sein, die Kunden aufrufen. Wenn die API-URL beispielsweise https://security.contoso.com/api/threatdetection lautet, muss der verfügbar gemachte Umfang https://security.contoso.com sein.
  • Je nachdem, wie Sie Ihren Service implementieren, müssen Sie die Autorisierungslogik implementieren und eingehende Token validieren. Sie müssen dokumentieren, wie der Kunde seine Apps autorisieren muss. Es gibt mehrere Möglichkeiten, dies zu tun, zum Beispiel durch die Verwendung einer Zulassen-Liste von App-IDs oder rollenbasierte Zugriffskontrolle (RBAC).

Antwortzeitanforderungen

Der Agent erwartet innerhalb von weniger als 1.000 ms eine Antwort vom Bedrohungserkennungssystem. Stellen Sie sicher, dass Ihr Endpunkt innerhalb dieses Zeitrahmens auf die Anfrage antwortet. Wenn Ihr System nicht rechtzeitig antwortet, verhält sich der Agent so, als wäre die Antwort „zulassen“ und führt das Tool aus.

API-Versionsverwaltung

In Anfragen wird die API-Version mittels eines api-version-Abfrageparameters (z. B. api-version=2025-05-01) angegeben. Ihre Implementierung sollte tolerant gegenüber anderen unerwarteten Feldern sein und 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 verfolgen, aber die Anfrage nicht fehlschlagen lassen, wenn eine neue Version erkannt wird.

  • Last updated on