Policy Configuration

Policies let you control what flows through the relay. You can detect sensitive content, restrict which skills agents can use, rate-limit traffic, and escalate messages for human review. Policies are applied through a three-step process:

Create a policy — define what to detect and what action to take
Create a policy group — bundle one or more policies together
Create a policy binding — attach the group to a tenant, agent, or subscription

How Policies Work

Source Agent → [REQUEST_FROM_SOURCE] → Relay → [REQUEST_TO_SINK] → Sink Agent
                                                                        ↓
Source Agent ← [RESPONSE_TO_SOURCE] ← Relay ← [RESPONSE_FROM_SINK] ← Sink Agent

Every policy specifies which legs of this flow it applies to via enabledLegs:

Leg	Direction	Example use
`requestFromSource`	Source → Relay	Scan outgoing requests for PII before they leave
`requestToSink`	Relay → Sink	Restrict which skills can be invoked on the target agent
`responseFromSink`	Sink → Relay	Detect sensitive data in agent responses
`responseToSource`	Relay → Source	Mask data before returning to the caller

At least one leg must be enabled. The API will reject a policy where all four legs are false.

Policy Types

Regex Detection

Match message content against a regular expression. Useful for detecting specific patterns like internal project codes, secret formats, or prohibited keywords.

curl -X POST https://api.swarmd.ai/relay/v1/policies \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SWARMD_TOKEN" \
  -d '{
    "name": "Block AWS Keys",
    "description": "Detect AWS access keys in message content",
    "config": {
      "type": "REGEX_DETECTION",
      "enabledLegs": {
        "requestFromSource": true,
        "requestToSink": true,
        "responseFromSink": true,
        "responseToSource": true
      },
      "pattern": {
        "regex": "AKIA[0-9A-Z]{16}",
        "action": "BLOCK"
      }
    }
  }'

Field	Required	Description
`pattern.regex`	Yes	Java-compatible regular expression
`pattern.action`	Yes	`LOG`, `MASK`, `BLOCK`, `WARN`, or `HUMAN_REVIEW_REQUIRED`

PII Detection (Presidio)

Automatically detect personally identifiable information using Microsoft Presidio. Each entity type has a confidence score threshold.

curl -X POST https://api.swarmd.ai/relay/v1/policies \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SWARMD_TOKEN" \
  -d '{
    "name": "Mask Credit Cards",
    "description": "Detect and mask credit card numbers in all traffic",
    "config": {
      "type": "PRESIDIO_DETECTION",
      "enabledLegs": {
        "requestFromSource": true,
        "requestToSink": true,
        "responseFromSink": true,
        "responseToSource": true
      },
      "entity": {
        "type": "CREDIT_CARD",
        "scoreThreshold": 0.8,
        "action": "MASK"
      }
    }
  }'

Field	Required	Description
`entity.type`	Yes	Presidio entity type (see table below)
`entity.scoreThreshold`	Yes	Confidence threshold between `0.0` and `1.0`
`entity.action`	Yes	`LOG`, `MASK`, `BLOCK`, `WARN`, or `HUMAN_REVIEW_REQUIRED`

Supported Presidio Entity Types

Entity Type	Description
`CREDIT_CARD`	Credit card numbers
`CRYPTO`	Cryptocurrency wallet addresses
`EMAIL_ADDRESS`	Email addresses
`IBAN_CODE`	International bank account numbers
`IP_ADDRESS`	IP addresses
`LOCATION`	Physical locations
`PERSON`	Person names
`PHONE_NUMBER`	Phone numbers
`MEDICAL_LICENSE`	Medical licence numbers
`US_BANK_NUMBER`	US bank account numbers
`US_DRIVER_LICENSE`	US driver licence numbers
`US_ITIN`	US Individual Taxpayer Identification Numbers
`US_PASSPORT`	US passport numbers
`US_SSN`	US Social Security Numbers
`UK_NHS`	UK National Health Service numbers
`ES_NIF`	Spanish tax identification numbers
`IT_FISCAL_CODE`	Italian fiscal codes
`IT_DRIVER_LICENSE`	Italian driver licence numbers
`IT_VAT_CODE`	Italian VAT codes
`IT_PASSPORT`	Italian passport numbers
`IT_IDENTITY_CARD`	Italian identity card numbers
`SG_NRIC_FIN`	Singapore NRIC/FIN numbers
`AU_ABN`	Australian Business Numbers
`AU_ACN`	Australian Company Numbers
`AU_TFN`	Australian Tax File Numbers
`AU_MEDICARE`	Australian Medicare numbers
`IN_PAN`	Indian PAN card numbers
`IN_AADHAAR`	Indian Aadhaar numbers
`IN_VEHICLE_REGISTRATION`	Indian vehicle registration numbers

PII Detection (AWS Comprehend)

Uses AWS Comprehend for PII detection. Configuration is similar to Presidio — refer to the API Reference for the full list of Comprehend entity types.

Skill Restriction

Control which skills an agent is allowed to use. You can allowlist or blocklist skills by ID, name, or tag.

curl -X POST https://api.swarmd.ai/relay/v1/policies \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SWARMD_TOKEN" \
  -d '{
    "name": "Block File System Access",
    "description": "Prevent agents from using file system skills",
    "config": {
      "type": "SKILL_RESTRICTION",
      "enabledLegs": {
        "requestFromSource": true,
        "requestToSink": true,
        "responseFromSink": false,
        "responseToSource": false
      },
      "mode": "BLOCKLIST",
      "action": "BLOCK",
      "skillIds": [],
      "skillNames": ["read_file", "write_file", "delete_file"],
      "skillTags": ["filesystem"]
    }
  }'

Field	Required	Description
`mode`	Yes	`ALLOWLIST` (only these skills permitted) or `BLOCKLIST` (these skills denied)
`action`	Yes	`LOG`, `WARN`, or `BLOCK`
`skillIds`	No	Set of skill IDs to match
`skillNames`	No	Set of skill names to match
`skillTags`	No	Set of skill tags to match

Use ALLOWLIST mode for high-security environments where agents should only use explicitly approved skills. Use BLOCKLIST when you want to permit everything except specific dangerous operations.

Rate Limiting

Throttle the volume of requests flowing through a subscription or agent.

curl -X POST https://api.swarmd.ai/relay/v1/policies \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SWARMD_TOKEN" \
  -d '{
    "name": "Rate Limit - 100 RPM",
    "description": "Limit requests to 100 per minute",
    "config": {
      "type": "RATE_LIMIT",
      "enabledLegs": {
        "requestFromSource": true,
        "requestToSink": false,
        "responseFromSink": false,
        "responseToSource": false
      },
      "strategy": {
        "maxRequests": 100,
        "windowSeconds": 60
      }
    }
  }'

Escalating to Human Review

Any detection policy (regex, Presidio, Comprehend) can escalate to human review by setting its action to HUMAN_REVIEW_REQUIRED. There is no separate “HITL policy type” — human-in-the-loop is an action you apply to your existing detection policies. For example, to require human approval when SSNs are detected:

curl -X POST https://api.swarmd.ai/relay/v1/policies \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SWARMD_TOKEN" \
  -d '{
    "name": "Review Messages with SSNs",
    "config": {
      "type": "PRESIDIO_DETECTION",
      "enabledLegs": {
        "requestFromSource": true,
        "requestToSink": true,
        "responseFromSink": true,
        "responseToSource": true
      },
      "entity": {
        "type": "US_SSN",
        "scoreThreshold": 0.7,
        "action": "HUMAN_REVIEW_REQUIRED"
      }
    }
  }'

See the Human-in-the-Loop tutorial for the complete approval workflow.

Policy Actions

Every detection policy requires an action that determines what happens when a match is found:

Action	Behaviour
`LOG`	Record the detection in the audit log. Message continues normally.
`WARN`	Log an advisory warning. Message continues normally.
`MASK`	Redact the matched content before forwarding the message.
`BLOCK`	Reject the message entirely. The sender receives an error.
`HUMAN_REVIEW_REQUIRED`	Pause the message and create a HITL approval request.

Policy Groups

Groups let you bundle related policies together. A group is what you actually bind to a tenant, agent, or subscription — not individual policies.

Create a group:

curl -X POST https://api.swarmd.ai/relay/v1/policy-groups \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SWARMD_TOKEN" \
  -d '{
    "name": "PII Protection Suite",
    "description": "Detect and mask common PII types"
  }'

Save the returned groupId.Add policies to the group:

curl -X POST https://api.swarmd.ai/relay/v1/policy-groups/GROUP_ID/members \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SWARMD_TOKEN" \
  -d '{
    "policyId": "POLICY_ID",
    "orderIndex": 0
  }'

The orderIndex determines the evaluation order within the group. Lower values are evaluated first.

Policy Bindings

Bindings attach a policy group to a scope. You can bind at three levels:

Level	Scope	Use case
`TENANT`	All agents in your tenant	Organisation-wide compliance rules
`AGENT`	A specific agent	Rules for a particular agent regardless of who calls it
`SUBSCRIPTION`	A specific source → sink pair	Fine-grained control over a single communication path

When multiple bindings apply to a message, they are evaluated in priority order (lower number = higher priority). All matching policies are applied.

Tenant-Level Binding

Apply a policy group to all agents in your tenant:

curl -X POST https://api.swarmd.ai/relay/v1/policy-bindings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SWARMD_TOKEN" \
  -d '{
    "groupId": "GROUP_ID",
    "bindingLevel": "TENANT",
    "priority": 0
  }'

Agent-Level Binding

Apply to a specific agent:

curl -X POST https://api.swarmd.ai/relay/v1/policy-bindings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SWARMD_TOKEN" \
  -d '{
    "groupId": "GROUP_ID",
    "bindingLevel": "AGENT",
    "agentId": "AGENT_ID",
    "priority": 10
  }'

Subscription-Level Binding

Apply to a specific agent-to-agent communication path:

curl -X POST https://api.swarmd.ai/relay/v1/policy-bindings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SWARMD_TOKEN" \
  -d '{
    "groupId": "GROUP_ID",
    "bindingLevel": "SUBSCRIPTION",
    "sourceAgentId": "SOURCE_AGENT_ID",
    "sinkAgentId": "SINK_AGENT_ID",
    "priority": 20
  }'

Managing Policies

List Active Policies

curl https://api.swarmd.ai/relay/v1/policies \
  -H "Authorization: Bearer $SWARMD_TOKEN"

List Active Bindings

curl https://api.swarmd.ai/relay/v1/policy-bindings \
  -H "Authorization: Bearer $SWARMD_TOKEN"

Disable a Policy

Disabling a policy removes it from evaluation. This does not delete it.

curl -X DELETE "https://api.swarmd.ai/relay/v1/policies/POLICY_ID?reason=No+longer+needed" \
  -H "Authorization: Bearer $SWARMD_TOKEN"

Disable a Binding

curl -X DELETE "https://api.swarmd.ai/relay/v1/policy-bindings/BINDING_ID?reason=Updating+scope" \
  -H "Authorization: Bearer $SWARMD_TOKEN"

Example: Full Policy Setup

Here’s a complete flow — create a PII detection policy, group it, and bind it to your tenant:

# 1. Create the policy
POLICY_ID=$(curl -s -X POST https://api.swarmd.ai/relay/v1/policies \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SWARMD_TOKEN" \
  -d '{
    "name": "Mask Email Addresses",
    "config": {
      "type": "PRESIDIO_DETECTION",
      "enabledLegs": {
        "requestFromSource": true,
        "requestToSink": true,
        "responseFromSink": true,
        "responseToSource": true
      },
      "entity": {
        "type": "EMAIL_ADDRESS",
        "scoreThreshold": 0.7,
        "action": "MASK"
      }
    }
  }' | jq -r '.policyId')

# 2. Create a policy group
GROUP_ID=$(curl -s -X POST https://api.swarmd.ai/relay/v1/policy-groups \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SWARMD_TOKEN" \
  -d '{
    "name": "Email Protection"
  }' | jq -r '.groupId')

# 3. Add the policy to the group
curl -X POST https://api.swarmd.ai/relay/v1/policy-groups/$GROUP_ID/members \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SWARMD_TOKEN" \
  -d "{
    \"policyId\": \"$POLICY_ID\",
    \"orderIndex\": 0
  }"

# 4. Bind the group to your tenant
curl -X POST https://api.swarmd.ai/relay/v1/policy-bindings \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SWARMD_TOKEN" \
  -d "{
    \"groupId\": \"$GROUP_ID\",
    \"bindingLevel\": \"TENANT\",
    \"priority\": 0
  }"

Getting Started

Platform Management

Policy Configuration

Policy Configuration

How Policies Work

Policy Types

Regex Detection

PII Detection (Presidio)

PII Detection (AWS Comprehend)

Skill Restriction

Rate Limiting

Escalating to Human Review

Policy Actions

Policy Groups

Policy Bindings

Tenant-Level Binding

Agent-Level Binding

Subscription-Level Binding

Managing Policies

List Active Policies

List Active Bindings

Disable a Policy

Disable a Binding

Example: Full Policy Setup

Next Steps

Human-in-the-Loop

User Management

Getting Started

Platform Management

​Policy Configuration

​How Policies Work

​Policy Types

​Regex Detection

​PII Detection (Presidio)

​PII Detection (AWS Comprehend)

​Skill Restriction

​Rate Limiting

​Escalating to Human Review

​Policy Actions

​Policy Groups

​Policy Bindings

​Tenant-Level Binding

​Agent-Level Binding

​Subscription-Level Binding

​Managing Policies

​List Active Policies

​List Active Bindings

​Disable a Policy

​Disable a Binding

​Example: Full Policy Setup

​Next Steps

Human-in-the-Loop

User Management

Policy Configuration

How Policies Work

Policy Types

Regex Detection

PII Detection (Presidio)

PII Detection (AWS Comprehend)

Skill Restriction

Rate Limiting

Escalating to Human Review

Policy Actions

Policy Groups

Policy Bindings

Tenant-Level Binding

Agent-Level Binding

Subscription-Level Binding

Managing Policies

List Active Policies

List Active Bindings

Disable a Policy

Disable a Binding

Example: Full Policy Setup

Next Steps