Een runtime-detectiesysteem voor bedreigingen bouwen voor Copilot Studio-agents

Organisaties kunnen een beveiligingslaag toevoegen aan hun Copilot Studio-agents door ze te verbinden met een runtime-detectiesysteem voor bedreigingen. Zodra er verbinding is gemaakt, roept de agent dit systeem aan tijdens runtime. De agent biedt het systeem gegevens, zodat het systeem kan bepalen of een hulpprogramma dat de agent wil aanroepen legitiem is of niet. Het systeem reageert vervolgens op Copilot Studio met een reactie van 'goedkeuren' of 'blokkeren', waardoor de agent het hulpprogramma dienovereenkomstig aanroept of overslaat. Zie Externe bedreigingsdetectie en -beveiliging inschakelen voor aangepaste Copilot Studio-agents voor meer informatie over het verbinden van agents met een bestaand systeem voor externe bedreigingsdetectie.

Dit artikel is gericht op ontwikkelaars en beschrijft hoe u uw eigen mogelijkheden voor detectie van bedreigingen integreert als beveiligingsprovider voor Copilot Studio-agents.

De integratie is gebaseerd op een API die bestaat uit twee eindpunten. Het belangrijkste eindpunt dat u moet implementeren, is het analyze-tool-execution eindpunt. U moet dit eindpunt beschikbaar maken als een interface voor uw detectiesysteem voor bedreigingen. Zodra klanten uw systeem als hun externe detectiesysteem voor bedreigingen hebben geconfigureerd, roept de agent deze API aan telkens wanneer het een hulpprogramma wil aanroepen.

Naast het analyze-tool-execution eindpunt moet u ook een tweede eindpunt beschikbaar maken, genaamd validate. Het validate eindpunt wordt gebruikt om de status en gereedheid van het eindpunt te controleren als onderdeel van de systeeminstallatie.

In de volgende secties wordt elk eindpunt gedetailleerd beschreven.

POST /validate

Doel: Controleert of het eindpunt voor bedreigingsdetectie bereikbaar en functioneert. Wordt gebruikt voor het testen van de eerste installatie en configuratie.

Aanvraag valideren

• Methode: VERZENDEN

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

• Kopteksten:

  • Autorisatie: Bearer-token voor API-verificatie

  • x-ms-correlation-id: GUID voor tracering

• Lichaam: Leeg

Antwoord valideren

Voorbeeld van 200 OK-antwoord

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

Voorbeeld van foutreactie

Als er een fout optreedt (mislukte HTTP-code), retourneert het eindpunt een foutcode, een bericht en optionele diagnostische gegevens.

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

POST /analyse-tool-uitvoering.

Doel: Hiermee wordt de context voor het uitvoeren van hulpprogramma's verzonden voor risico-evaluatie. Evalueert de aanvraag voor het uitvoeren van het hulpprogramma en reageert of de uitvoering van het hulpprogramma moet worden toegestaan of geblokkeerd.

Aanvraag voor het uitvoeren van het hulpprogramma analyseren

• Methode: VERZENDEN

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

• Kopteksten:

  • Autorisatie: Bearer-token voor API-verificatie
  • Inhoudstype: toepassing/json

• Lichaam: JSON-object

Voorbeeld van een aanvraag voor de uitvoering van het hulpprogramma analyseren

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

Reactie op het uitvoeren van het hulpprogramma analyseren

200 Akkoord

Wanneer de aanvraag geldig is, wordt het hulpprogramma dat is opgegeven in de aanvraag geëvalueerd en toegestaan of geblokkeerd, op basis van de gedefinieerde criteria. Het antwoord kan de volgende velden bevatten:

• blockAction (Booleaanse waarde): Of de actie moet worden geblokkeerd
• reasonCode (geheel getal, optioneel): Numerieke code waarin de reden voor het blok wordt uitgelegd
• reden (tekenreeks, optioneel): Leesbare uitleg
• diagnostische gegevens (object, optioneel): Overige details voor tracering of foutopsporing

Voorbeeld van antwoord toestaan

{
  "blockAction": false
}

Voorbeeld van blokreactie

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

Voorbeeld van een foutbericht

Als de aanvraag niet geldig is, wordt er een foutbericht geretourneerd met een foutcode, bericht, HTTP-status en optionele diagnostische gegevens.

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

Verwijzing naar hoofdtekststructuren voor aanvragen en antwoorden

In de volgende tabellen wordt de inhoud beschreven van verschillende objecten die worden gebruikt in de aanvraag- en antwoordteksten voor de eindpunten.

Validatieresponse

AnalyzeToolExecutionResponse

ErrorResponse

EvaluationRequest

PlannerContext

ChatMessage

ToolExecutionOutputs

ExecutionOutput

ToolDefinition

ToolInput

ToolOutput

ConversationMetadata

AgentContext

UserContext

TriggerContext

Authenticatie

De integratie die u ontwikkelt, moet gebruikmaken van Microsoft Entra ID-verificatie. Volg de instructies voor het integreren van apps die uw ontwikkelaars bouwen.

De stappen die u moet uitvoeren, zijn onder andere:

• Maak een app-registratie voor uw resource in uw tenant.
• Maak een bereik beschikbaar voor uw web-API. Het weergegeven bereik moet de basis-URL zijn voor de resource die de klanten bellen. Als de API-URL bijvoorbeeld is https://security.contoso.com/api/threatdetection, moet het beschikbaar gemaakte bereik zijn https://security.contoso.com.
• Afhankelijk van hoe u uw service implementeert, moet u autorisatielogica implementeren en binnenkomende tokens valideren. U moet documenteren hoe de klant zijn apps moet autoriseren. Er zijn meerdere manieren om dat te doen, bijvoorbeeld met een toelaatlijst van app-ID's of rolgebaseerde toegangscontrole (RBAC).

Vereisten voor reactietijd

De agent verwacht een reactie van het detectiesysteem voor bedreigingen binnen minder dan 1000 ms. Zorg ervoor dat uw eindpunt binnen dit tijdsbestek antwoordt op de oproep. Als uw systeem niet tijdig reageert, gedraagt de agent zich alsof uw antwoord 'toestaan' is en het hulpprogramma aanroept.

API-versiebeheer

In aanvragen wordt de API-versie opgegeven via een api-version queryparameter (bijvoorbeeld api-version=2025-05-01). Uw implementatie moet tolerant zijn voor andere onverwachte velden en mag niet mislukken als er in de toekomst nieuwe waarden worden toegevoegd. Partners moeten de API-versie niet verifiëren, omdat alle versies op dit moment als niet-brekend worden beschouwd. Partners moeten de API-versies bijhouden, maar de aanvraag niet mislukken bij het zien van een nieuwe versie.