Creare un sistema di rilevamento delle minacce in fase di esecuzione per gli agenti di Copilot Studio

Le organizzazioni possono aggiungere un livello di sicurezza ai loro agenti Copilot Studio collegandoli a un sistema di rilevamento delle minacce in fase di esecuzione. Una volta connesso, l'agente chiama questo sistema in fase di esecuzione. L'agente fornisce al sistema i dati affinché il sistema possa determinare se lo strumento che l'agente intende invocare sia legittimo oppure no. Il sistema risponde quindi a Copilot Studio con una risposta di "approvazione" o "blocco", consentendo all'agente di richiamare o ignorare lo strumento di conseguenza. Per altre informazioni su come connettere gli agenti a un sistema di rilevamento delle minacce esterno esistente, vedi Abilitare il rilevamento e la protezione dalle minacce esterni per gli agenti personalizzati di Copilot Studio.

Questo articolo è rivolto agli sviluppatori e descrive come integrare le proprie funzionalità di rilevamento delle minacce come provider di sicurezza per gli agenti Copilot Studio.

L'integrazione si basa su un'API composta da due endpoint. Il principale endpoint che devi implementare è l'endpoint analyze-tool-execution. Devi esporre questo endpoint come interfaccia per il tuo sistema di rilevamento delle minacce. Una volta che i clienti configurano il sistema come sistema esterno di rilevamento delle minacce, l'agente chiama questa API ogni volta che intende invocare uno strumento.

Oltre all'endpoint analyze-tool-execution, devi anche esporre un secondo endpoint, chiamato validate. L'endpoint validate viene usato per controllare l'integrità e la conformità dell'endpoint come parte della configurazione del sistema.

Le sezioni seguenti descrivono i dettagli per ciascun endpoint.

POST /validate

Scopo: Verifica che l'endpoint di rilevamento delle minacce sia raggiungibile e funzionante. Utilizzato per l'impostazione iniziale e la verifica della configurazione.

Convalida richiesta

  • Metodo: POST

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

  • Intestazioni:

    • Autorizzazione: token di connessione per l'autenticazione API

    • x-ms-correlation-id: GUID per la tracciabilità

  • Corpo: Vuoto

Convalida risposta

esempio 200 risposte OK

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

Esempio di risposta all'errore

In caso di errore (codice HTTP di errore), l'endpoint restituisce un codice di errore, un messaggio e informazioni diagnostiche opzionali.

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

POST /analyze-tool-execution

Scopo: Invia il contesto di esecuzione dello strumento per la valutazione del rischio. Valuta la richiesta di esecuzione dello strumento e risponde se consentire o bloccare l'esecuzione.

Richiesta analyze-tool-execution

  • Metodo: POST

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

  • Intestazioni:

    • Autorizzazione: token di connessione per l'autenticazione API
    • Content-Type: application/json

  • Corpo: oggetto JSON

Esempio di richiesta per l'endpoint analyze-tool-execution

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

Risposta analyze-tool-execution

200 - OK

Quando la richiesta è valida, l'uso dello strumento specificato nella richiesta viene valutato e consentito o bloccato, in base ai criteri definiti. La risposta può includere i seguenti campi:

  • blockAction (booleano): Indica se l'azione deve essere bloccata
  • reasonCode (integer, opzionale): Codice numerico che indica il motivo del blocco
  • motivo (stringa, opzionale): Spiegazione comprensibile
  • diagnostica (oggetto, opzionale): Altri dettagli per tracciamento o debug

Esempio di risposta abilitata

{
  "blockAction": false
}

Esempio di risposta di blocco

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

Esempio risposta all'errore

Se la richiesta non è valida, viene restituita una risposta di errore contenente un codice di errore, un messaggio, il codice di stato HTTP e informazioni diagnostiche opzionali.

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

Informazioni di riferimento sulle strutture del corpo della richiesta e della risposta

Le seguenti tabelle descrivono i contenuti dei vari oggetti utilizzati all'interno dei corpi della richiesta e dei corpi della risposta per gli endpoint.

ValidationResponse

Nome Tipo Obbligatorio Descrizione
isSuccessful Booleano Sì Indica se la validazione ha avuto esito positivo.
elaborazione string Sì Messaggio di stato opzionale o dettaglio relativo al partner.

AnalyzeToolExecutionResponse

Nome Tipo Obbligatorio Descrizione
blockAction Booleano Sì Indica se l'azione deve essere bloccata.
reasonCode integer No Codice motivo numerico facoltativo, determinato dal partner.
reason string No Spiegazione opzionale leggibile da un umano.
diagnostica string No Informazioni diagnostiche opzionali in formato libero per il debug o la telemetria. Deve essere preserializzato.

ErrorResponse

Nome Tipo Obbligatorio Descrizione
errorCode integer Sì Identificatore numerico per l'errore (es. 1001 = campo mancante, 2003 = fallimento dell'autenticazione).
messaggio string Sì Spiegazione leggibile dall'uomo dell'errore.
httpStatus integer Sì Codice di stato HTTP restituito dal partner.
diagnostica string No Informazioni diagnostiche opzionali in formato libero per il debug o la telemetria. Deve essere preserializzato.

EvaluationRequest

Nome Tipo Obbligatorio Descrizione
plannerContext PlannerContext Sì Dati di contesto del planner.
toolDefinition ToolDefinition Sì Dettagli della definizione dello strumento.
inputValues Oggetto JSON Sì Dizionario delle coppie chiave-valore fornito allo strumento.
conversationMetadata ConversationMetadata Sì Metadati sul contesto della conversazione, sull'utente e sul monitoraggio del piano.

PlannerContext

Nome Tipo Obbligatorio Descrizione
userMessage string Sì Il messaggio originale inviato dall'agente.
pensiero string No Motivazione fornita dal planner per la scelta di questo strumento.
chatHistory ChatMessage[] No Elenco dei messaggi di chat recenti scambiati con l'utente.
previousToolsOutputs ToolExecutionOutput[] No Elenco degli output recenti degli strumenti.

ChatMessage

Nome Tipo Obbligatorio Descrizione
ID. string Sì Identificatore univoco per questo messaggio nella conversazione.
ruolo string Sì Fonte del messaggio (es. utente, assistente).
contenuto string Sì Il testo del messaggio.
timestamp stringa (data e ora) No Timestamp ISO 8601 che indica quando il messaggio è stato inviato.

ToolExecutionOutputs

Nome Tipo Obbligatorio Descrizione
toolId string Sì Identificatore univoco per questo messaggio nella conversazione.
toolName string Sì Nome dello strumento.
output ExecutionOutput[] Sì Elenco degli output di esecuzione degli strumenti.
timestamp stringa (data e ora) No Timestamp ISO 8601 che indica quando l'esecuzione dello strumento si è conclusa.

ExecutionOutput

Nome Tipo Obbligatorio Descrizione
nome. string Sì Nome del parametro di output.
description string No Spiegazione del valore di output.
Tipo object No Tipo di dati di output.
value valore dati JSON Sì Il valore di output.

ToolDefinition

Nome Tipo Obbligatorio Descrizione
ID. string Sì Identificatore univoco dello strumento.
Tipo string Sì Specifica il tipo di strumento utilizzato nel planner.
nome. string Sì Nome comprensibile dello strumento.
description string Sì Riassunto di cosa fa lo strumento.
inputParameters ToolInput[] No Parametri di input dello strumento.
outputParameters ToolOutput[] No Parametri di output che lo strumento restituisce dopo l'esecuzione.

ToolInput

Nome Tipo Obbligatorio Descrizione
nome. string Sì Nome del parametro di input.
description string No Spiegazione del valore atteso per questo parametro di input.
Tipo Oggetto JSON No Tipo di dati del parametro di input.

ToolOutput

Nome Tipo Obbligatorio Descrizione
nome. string Sì Nome del parametro di output.
description string No Spiegazione del valore di output.
Tipo Oggetto JSON No Tipo di valore di output.

ConversationMetadata

Nome Tipo Obbligatorio Descrizione
agente AgentContext Sì Informazioni sul contesto agente.
Utente di UserContext No Informazioni sull'utente che interagisce con l'agente.
trigger TriggerContext No Informazioni su cosa ha innescato l'esecuzione del planner.
conversationId string Sì ID della conversazione in corso.
planId string No ID del piano utilizzato per soddisfare la richiesta dell'utente.
planStepId string No Passaggio all'interno del piano relativo all'esecuzione di questo strumento.
parentAgentComponentId string No ID del componente agente padre.

AgentContext

Nome Tipo Obbligatorio Descrizione
ID. string Sì ID dell'agente.
tenantId string Sì Tenant che ospita l'agente.
environmentId string Sì Ambiente in cui viene pubblicato l'agente.
versione string No Versione dell'agente (opzionale se isPublished è falso).
isPublished Booleano Sì Indica se questo contesto di esecuzione è una versione pubblicata.

UserContext

Nome Tipo Obbligatorio Descrizione
ID string No ID oggetto Microsoft Entra dell'utente.
tenantId string No ID tenant dell'utente.

TriggerContext

Nome Tipo Obbligatorio Descrizione
ID. string No L'ID del trigger che ha attivato il planner.
schemaName string No Il nome dello schema di trigger che ha attivato il planner.

Autenticazione

L'integrazione da sviluppare dovrebbe utilizzare l'autenticazione Microsoft Entra ID. Segui le istruzioni riportate in Integra le app sviluppate dai tuoi sviluppatori.

I passaggi da eseguire sono i seguenti:

  • Creare una registrazione dell'app per la risorsa nel tenant.
  • Esporre un ambito per l'API Web. L'ambito esposto deve essere l'URL base per la risorsa chiamata dai clienti. Ad esempio, se l'URL dell'API è https://security.contoso.com/api/threatdetection, allora l'ambito esposto deve essere https://security.contoso.com.
  • A seconda di come implementi il tuo servizio, devi implementare la logica di autorizzazione e validare i token in arrivo. È necessario documentare come il cliente deve autorizzare le proprie app. Ci sono diversi modi per farlo, ad esempio utilizzando una lista di autorizzazione degli ID delle app o il controllo degli accessi basato sui ruoli (RBAC).

Requisiti di tempo di risposta

L'agente si aspetta una risposta dal sistema di rilevamento delle minacce entro 1.000 ms. Dovresti assicurarti che il tuo endpoint risponda alla chiamata entro questo intervallo di tempo. Se il tuo sistema non risponde in tempo, l'agente presume che la tua risposta sia "allow" e invoca lo strumento.

Controllo delle versioni API

Nelle richieste, la versione dell'API viene specificata tramite un parametro di query api-version (ad esempio, api-version=2025-05-01). La tua implementazione dovrebbe accettare campi inaspettati e non restituire errori se in futuro vengono aggiunti nuovi valori. I partner non devono verificare la versione dell'API, perché tutte le versioni al momento sono considerate non di rilievo. I partner dovrebbero monitorare le versioni API ma non fallire la richiesta quando ne vedono una nuova versione.

  • Ultimo aggiornamento: