Lägga till ett skyddsräcke för innehåll till en värdbaserad agent

Den här artikeln visar hur du kopplar ett skyddsräcke för innehåll till en värdbaserad agent i Microsoft Foundry. En skyddsmekanism granskar de promptar som din agent tar emot och de svar som den returnerar mot en policy för ansvarsfull AI (RAI), så att skadligt innehåll filtreras enligt din organisations säkerhetskonfiguration.

Du hänvisar till skyddsräcket med resurs-ID:t för RAI-policyn i agentdefinitionen. Plattformen tillämpar sedan policyn på agenten under körning. Du kan ange ett skyddsräcke när du distribuerar med Azure Developer CLI (azd), Python SDK eller REST-API:et. Information om vad skyddsräcken är, vilka risker de identifierar och hur du skapar ett finns i Översikt över skyddsräcken och kontroller.

Prerequisites

  • Ett Microsoft Foundry-projekt.

  • En värdbaserad agent eller en containeravbildning som är redo att distribueras som en. Se Distribuera en värdbaserad agent.

  • Ett skyddsräcke (RAI-princip) som redan har skapats på Foundry-resursen och dess fullständiga resurs-ID för Azure Resource Manager (ARM). Information om hur du skapar en finns i Konfigurera skyddsräcken och kontroller. ARM-resurs-ID:t har det här formuläret:

    /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<account>/raiPolicies/<policy-name>

  • För Azure Developer CLI-metoden: tillägget azd ai agent, version 0.1.38-preview eller senare.

  • För metoden Python SDK: klientbiblioteket Azure AI Projects för Python version 2.2.0 eller senare:

    pip install "azure-ai-projects>=2.2.0"

Så här gäller skyddsräcken för värdbaserade agenter

En värdbaserad agentdefinition har en valfri rai_config inställning med ett rai_policy_name fält. Ange rai_policy_name som det fullständiga ARM-resurs-ID:t för guardrailens RAI-policy. Plattformen tillämpar den principen på agentens uppmaningar och svar.

När du utelämnar rai_configkörs agenten utan ett skyddsräcke för innehållssäkerhet. När du inkluderar rai_config men utelämnar rai_policy_nametillämpar plattformen standardprincipen . Microsoft.DefaultV2 Ange en anpassad princip när du behöver striktare eller organisationsspecifik filtrering.

Använd alltid det fullständiga ARM-resurs-ID:t för rai_policy_name, inte det tomma principnamnet.

Lägga till ett skyddsräcke med Azure Developer CLI

När du använder azddeklarerar du skyddsräcket för azure.ai.agent tjänsten i azure.yaml. Ange rai_config.rai_policy_name till det fullständiga ARM-resurs-ID:t för RAI-principen.

  1. I din azure.yaml lägger du till rai_config i agenttjänsten:

    services:
  my-agent:
    host: azure.ai.agent
    project: src/my-agent
    kind: hosted
    name: my-hosted-agent
    description: A hosted agent with a content safety guardrail
    rai_config:
      # Full ARM resource ID of the RAI policy on the Foundry resource.
      rai_policy_name: /subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<account>/raiPolicies/<policy-name>
    protocols:
      - protocol: responses
        version: "2.0.0"

  2. Distribuera agenten:

    azd deploy

Plattformen kopplar skyddsmekanismen när den skapar agentversionen.

Lägg till ett skyddsräcke med Python SDK

När du skapar en agentversion med SDK:t skickar du en RaiConfig till parametern rai_config i HostedAgentDefinition.

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
    AgentEndpointProtocol,
    ContainerConfiguration,
    HostedAgentDefinition,
    ProtocolVersionRecord,
    RaiConfig,
)
from azure.identity import DefaultAzureCredential

# Format: "https://<resource-name>.services.ai.azure.com/api/projects/<project-name>"
PROJECT_ENDPOINT = "your_project_endpoint"

# Full ARM resource ID of the RAI policy.
RAI_POLICY_ID = (
    "/subscriptions/<subscription-id>/resourceGroups/<resource-group>"
    "/providers/Microsoft.CognitiveServices/accounts/<account>"
    "/raiPolicies/<policy-name>"
)

credential = DefaultAzureCredential()
project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=credential,
    allow_preview=True,
)

agent = project.agents.create_version(
    agent_name="my-agent",
    definition=HostedAgentDefinition(
        cpu="1",
        memory="2Gi",
        container_configuration=ContainerConfiguration(
            image="your-registry.azurecr.io/your-image:tag",
        ),
        protocol_versions=[
            ProtocolVersionRecord(
                protocol=AgentEndpointProtocol.RESPONSES, version="1.0.0"
            )
        ],
        rai_config=RaiConfig(rai_policy_name=RAI_POLICY_ID),
    ),
)

print(f"Agent created: {agent.name}, version: {agent.version}")

Referens: HostedAgentDefinition, ContainerConfiguration och RaiConfig.

Lägga till ett skyddsräcke med REST-API:et

När du skapar agenten via REST lägger du till ett rai_config objekt i definition.

BASE_URL="https://{account}.services.ai.azure.com/api/projects/{project}"
API_VERSION="v1"
TOKEN=$(az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv)

curl -X POST "$BASE_URL/agents?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-agent",
    "definition": {
      "kind": "hosted",
      "container_configuration": {
        "image": "myacr.azurecr.io/my-agent:v1"
      },
      "cpu": "1",
      "memory": "2Gi",
      "protocol_versions": [
        {"protocol": "responses", "version": "1.0.0"}
      ],
      "rai_config": {
        "rai_policy_name": "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<account>/raiPolicies/<policy-name>"
      }
    }
  }'

Kontrollera att skyddsräcket har tillämpats

Hämta agentens version och bekräfta att rai_config.rai_policy_name innehåller ditt policy-ID.

curl -s -X GET "$BASE_URL/agents/my-agent/versions/1?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN" | jq '.definition.rai_config'

Svaret innehåller den princip som du anger:

{
  "rai_policy_name": "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.CognitiveServices/accounts/<account>/raiPolicies/<policy-name>"
}

Testa skyddsräcket vid körning

För att bekräfta att skyddsräcket filtrerar innehåll skickar du en uppmaning som bryter mot din säkerhetsprincip till agentens svarsslutpunkt. Plattformen granskar prompten vid inmatningen och avvisar den innan agenten startar.

curl -i -X POST "$BASE_URL/agents/my-agent/endpoint/protocols/openai/responses?api-version=$API_VERSION" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"input":"<a prompt that your policy is configured to block>","store":true}'

En blockerad fråga returneras HTTP 400 med ett content_filter fel:

{
  "error": {
    "code": "content_filter",
    "message": "The request was blocked due to content safety policy violation at input stage.",
    "type": "content_safety_error"
  }
}

En prompt som uppfyller policyn returnerar HTTP 200 med agentens svar. Om en skadlig prompt inte blockeras, bekräfta att principen som rai_policy_name hänvisar till är konfigurerad för att filtrera den relevanta innehållskategorin och allvarlighetsgraden.

Relaterat innehåll

  • Last updated on