Dela via

Skapa ett system för körning av hotidentifiering för Copilot Studio-agenter

Organisationer kan lägga till ett säkerhetslager till sina Copilot Studio-agenter genom att ansluta dem till ett system för körningshotidentifiering. När agenten är ansluten anropas systemet vid körning. Agenten förser systemet med data så att systemet kan avgöra om ett verktyg som agenten planerar att anropa är legitimt eller inte. Systemet svarar sedan på Copilot Studio med ett svar på antingen "godkänn" eller "blockera", vilket gör att agenten anropar eller hoppar över verktyget i enlighet med detta. Mer information om hur du ansluter agenter till ett befintligt system för extern hotidentifiering finns i Aktivera extern hotidentifiering och skydd för anpassade Copilot Studio-agenter.

Den här artikeln riktar sig till utvecklare och beskriver hur du integrerar dina egna funktioner för hotidentifiering som säkerhetsleverantör för Copilot Studio-agenter.

Integreringen baseras på ett API som består av två slutpunkter. Den huvudslutpunkt som du behöver implementera är analyze-tool-execution slutpunkten. Du måste exponera den här slutpunkten som ett gränssnitt för ditt system för hotidentifiering. När kunderna har konfigurerat systemet som sitt externa system för hotidentifiering anropar agenten detta API varje gång det avser att anropa ett verktyg.

analyze-tool-execution Förutom slutpunkten måste du också exponera en andra slutpunkt med namnet validate. Slutpunkten validate används för att kontrollera hälsotillståndet och beredskapen för slutpunkten som en del av systemkonfigurationen.

I följande avsnitt beskrivs varje slutpunkt i detalj.

POST /validera

Avsikt: Verifierar att slutpunkten för hotidentifiering kan nås och fungera. Används för inledande konfigurations- och konfigurationstestning.

Verifiera begäran

  • Metod: POST

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

  • Headers:

    • Auktorisering: Ägartoken för API-autentisering

    • x-ms-correlation-id: GUID för spårning

  • Kropp: Tom

Verifiera svar

200 OK-svarsexempel

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

Exempel på felsvar

Om ett fel inträffar (misslyckad HTTP-kod) returnerar slutpunkten en felkod, ett meddelande och valfri diagnostik.

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

POST /analys-verktyg-exekvering

Avsikt: Skickar verktygskörningskontext för riskutvärdering. Utvärderar körningsbegäran för verktyget och svarar på om du vill tillåta eller blockera verktygskörningen.

Begäran om att analysera verktygskörning

  • Metod: POST

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

  • Headers:

    • Auktorisering: Ägartoken för API-autentisering
    • Innehållstyp: program/json

  • Kropp: JSON-objekt

Exempel på begäran om analysverktygskörning

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å analysverktygskörning

200 Okej

När begäran är giltig utvärderas det verktyg som anges i begäran och tillåts eller blockeras, baserat på de definierade kriterierna. Svaret kan innehålla följande fält:

  • blockAction (booleskt): Om åtgärden ska blockeras
  • reasonCode (heltal, valfritt): Numerisk kod som förklarar orsaken till blocket
  • reason (sträng, valfritt): Förklaring som kan läsas av människor
  • diagnostik (objekt, valfritt): Annan information för spårning eller felsökning

Exempel på tillåtna svar

{
  "blockAction": false
}

Exempel på blockeringssvar

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

Exempel på felsvar

Om begäran inte är giltig returneras ett felsvar med en felkod, ett meddelande, HTTP-status och valfri diagnostik.

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

Referens för brödtexten för begäran och svar

I följande tabeller beskrivs innehållet i olika objekt som används i begärande- och svarsorganen för slutpunkterna.

ValidationResponse

Namn Type Obligatoriskt Beskrivning
isSuccessful Boolean Yes Anger om valideringen har godkänts.
status snöre Yes Valfritt statusmeddelande eller partnerspecifik information.

AnalyzeToolExecutionResponse

Namn Type Obligatoriskt Beskrivning
blockAction Boolean Yes Anger om åtgärden ska blockeras.
orsakskod integer Nej Valfri numerisk orsakskod som bestäms av partner.
reason snöre Nej Valfri förklaring som kan läsas av människor.
diagnostics snöre Nej Valfri diagnostikinformation för frihandsfigur för felsökning eller telemetri. Måste vara preserialiserad.

ErrorResponse

Namn Type Obligatoriskt Beskrivning
felkod integer Yes Numerisk identifierare för felet (till exempel 1001 = fältet saknas, 2003 = autentiseringsfel).
meddelande snöre Yes Förklaring av felet som kan läsas av människor.
httpStatus (på engelska) integer Yes HTTP-statuskod som returneras av partnern.
diagnostics snöre Nej Valfri diagnostikinformation för frihandsfigur för felsökning eller telemetri. Måste vara preserialiserad.

EvaluationRequest

Namn Type Obligatoriskt Beskrivning
plannerContext PlannerContext Yes Planner-kontextdata.
toolDefinition ToolDefinition Yes Information om verktygsdefinition.
inputValues JSON-objekt Yes Ordlista över nyckel/värde-par som tillhandahålls till verktyget.
conversationMetadata ConversationMetadata Yes Metadata om konversationskontext, användare och planspårning.

PlannerContext

Namn Type Obligatoriskt Beskrivning
användarmeddelande snöre Yes Det ursprungliga meddelandet som skickades av agenten.
tanke snöre Nej Planner-förklaring till varför det här verktyget har valts.
chatHistory ChatMessage[] Nej Lista över de senaste chattmeddelanden som har utväxlades med användaren.
previousToolsOutputs ToolExecutionOutput[] Nej Lista över de senaste verktygsutdata.

ChatMessage

Namn Type Obligatoriskt Beskrivning
Id-nummer snöre Yes Unik identifierare för det här meddelandet i konversationen.
None needed, as the translation is already accurate and fluent. snöre Yes Källan till meddelandet (till exempel användare, assistent).
innehåll snöre Yes Meddelandetexten.
tidsstämpel sträng (datum-tid) Nej ISO 8601-tidsstämpel som anger när meddelandet skickades.

ToolExecutionOutputs

Namn Type Obligatoriskt Beskrivning
toolId snöre Yes Unik identifierare för det här meddelandet i konversationen.
toolName snöre Yes Namnet på verktyget.
Utgångar ExecutionOutput[] Yes Lista över verktygskörningens utdata.
tidsstämpel sträng (datum-tid) Nej ISO 8601-tidsstämpel som anger när verktygskörningen var klar.

ExecutionOutput

Namn Type Obligatoriskt Beskrivning
name snöre Yes Namnet på utdataparametern.
beskrivning snöre Nej Förklaring av utdatavärdet.
type objekt Nej Datatyp för utdata.
värde JSON-datavärde Yes Utdatavärdet.

ToolDefinition

Namn Type Obligatoriskt Beskrivning
Id-nummer snöre Yes Unik identifierare för verktyget.
type snöre Yes Anger vilken typ av verktyg som används i planeraren.
name snöre Yes Mänskligt läsbart namn på verktyget.
beskrivning snöre Yes Sammanfattning av vad verktyget gör.
inputParameters ToolInput[] Nej Indataparametrar för verktyget.
outputParameters ToolOutput[] Nej Utdataparametrar som verktyget returnerar efter körningen.

ToolInput

Namn Type Obligatoriskt Beskrivning
name snöre Yes Namnet på indataparametern.
beskrivning snöre Nej Förklaring av det förväntade värdet för den här indataparametern.
type JSON-objekt Nej Datatyp för indataparametern.

ToolOutput

Namn Type Obligatoriskt Beskrivning
name snöre Yes Namnet på utdataparametern.
beskrivning snöre Nej Förklaring av utdatavärdet.
type JSON-objekt Nej Typ av utdatavärde.

ConversationMetadata

Namn Type Obligatoriskt Beskrivning
agent AgentContext Yes Information om agentkontext.
user UserContext Nej Information om användaren som interagerar med agenten.
trigger TriggerContext Nej Information om vad som utlöste planeringskörningen.
conversationId snöre Yes ID för den pågående konversationen.
planId snöre Nej ID för den plan som används för att uppfylla användarbegäran.
planStepId snöre Nej Steg i planen som motsvarar den här verktygskörningen.
parentAgentComponentId snöre Nej ID för den överordnade agentkomponenten.

AgentContext

Namn Type Obligatoriskt Beskrivning
Id-nummer snöre Yes Agentens ID.
tenantId snöre Yes Klientorganisation där agenten finns.
environmentId snöre Yes Miljö där agenten publiceras.
version snöre Nej Agentversion (valfritt om isPublished det är falskt).
isPublished Boolean Yes Om den här körningskontexten är en publicerad version.

UserContext

Namn Type Obligatoriskt Beskrivning
Id-nummer snöre Nej Microsoft Entra-objekt-ID för användaren.
tenantId snöre Nej Användarens klientorganisations-ID.

TriggerContext

Namn Type Obligatoriskt Beskrivning
Id-nummer snöre Nej ID:t för utlösaren som utlöste planeraren.
schemaName snöre Nej Namnet på utlösarschemat som utlöste planeraren.

Authentication

Den integrering du utvecklar bör använda Microsoft Entra-ID-autentisering. Följ anvisningarna i Integrera appar som utvecklarna skapar.

Stegen för att utföra inkluderar följande:

  • Skapa en appregistrering för resursen i klientorganisationen.
  • Exponera ett omfång för ditt webb-API. Det exponerade omfånget måste vara bas-URL:en för resursen som kunderna anropar. Om API-URL:en till exempel är https://security.contoso.com/api/threatdetectionmåste det exponerade omfånget vara https://security.contoso.com.
  • Beroende på hur du implementerar din tjänst måste du implementera auktoriseringslogik och verifiera inkommande token. Du måste dokumentera hur kunden måste auktorisera sina appar. Det finns flera sätt att göra det, till exempel genom att använda en tillåtslista med app-ID:n eller rollbaserad åtkomstkontroll (RBAC).

Krav på svarstid

Agenten förväntar sig ett svar från hotidentifieringssystemet inom mindre än 1 000 ms. Du bör se till att slutpunkten svarar på anropet inom den här tidsramen. Om systemet inte svarar i tid beter sig agenten som om ditt svar är "tillåt" och anropar verktyget.

API-versionshantering

I begäranden anges API-versionen via en api-version frågeparameter (till exempel api-version=2025-05-01). Implementeringen bör vara tolerant mot andra oväntade fält och bör inte misslyckas om nya värden läggs till i framtiden. Partner bör inte verifiera API-versionen eftersom alla versioner för tillfället anses vara icke-icke-bakåtkompatibla. Partner bör spåra API-versionerna men inte misslyckas med begäran om att se en ny version.

  • Last updated on