superagent_

// use cases

Protect Pi agents from PII and PHI leaks

[ view markdown ]

Enforce a deterministic sensitive-data rule where Pi runs and send blocked actions to your monitoring workflow.

Stop a Pi agent before it runs a command whose arguments contain PII or PHI. Runtime Guardrails evaluate the rule on the machine where Pi runs. Findings, enforcement decisions, and client health reach Superagent while the normalized event stream stays on the endpoint.

Prerequisites

  • A Superagent organization owner
  • Pi installed on a local workstation or cloud agent host
  • An HTTPS endpoint for security alerts

1. Create a Pi Agent

  1. Open Agents → Connected.
  2. Select Add new.
  3. Enter a name and choose Coding Agent.
  4. Create the Agent.

A Coding Agent includes a Runtime Guardrails client. Open its detail page to configure the rule group and generate a one-time pairing command.

2. Create the rule and group

Open Agents → Groups, create a group named Sensitive data, and return to Agents → Rules. Select New rule, paste this rule, and assign it to the group:

id: prevention.pii_phi_in_tool_arguments
version: "1.0"
enabled: true
title: PII or PHI in tool arguments
description: |-
  A tool or command argument contains identifiable personal or protected health
  information, including labeled social-security, medical-record, patient,
  diagnosis, payment-card, or similar values, or an email address. The request
  is blocked to prevent sensitive data from being passed to an agent tool.
severity: high
tags:
  - pii
  - phi
  - privacy
  - data-protection
  - prevention
expr: >-
  event.event_type == "command.exec" &&

  (
    event.command.matches("(?i)(ssn|social security number|medical record number|mrn|patient id|date of birth|dob)\\s*[:=]\\s*[A-Za-z0-9./-]{4,}") ||
    event.command.matches("(?i)(diagnosis|medical condition|health condition|prescription|medication|treatment|patient)\\s*[:=]\\s*[^\\s,;]{2,}") ||
    event.command.matches("(?i)(card number|credit card|payment card|pan)\\s*[:=]\\s*[0-9][0-9 -]{11,23}") ||
    event.command.matches("\\b[0-9]{3}-[0-9]{2}-[0-9]{4}\\b") ||
    event.command.matches("\\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}\\b")
  )
enforce: true
deny_message: Tool arguments containing PII or PHI are blocked.

Superagent validates and compiles the rule before saving it. The rule matches labeled personal and health fields, payment card values, Social Security numbers, and email addresses in command arguments.

Open the Pi Agent, enable Runtime guardrails, and select the Sensitive data group. The client receives the union of default rules and this custom rule.

3. Pair Pi locally or in the cloud

In the Agent's Runtime guardrails configuration, select Pi. Copy the generated command and run it as the same operating-system user that runs Pi:

curl -fsSL https://superagent.sh/install.sh | sh -s -- connect \
  --client-id CLIENT_ID \
  --pairing-token ONE_TIME_TOKEN \
  --api-url https://www.superagent.sh \
  --agent pi

Run the command on the developer workstation for local Pi sessions or on the agent host for cloud sessions. The token expires after 15 minutes and is consumed by the first successful pairing.

The command installs the checksum-verified Superagent CLI, syncs the effective rule catalog, installs Pi monitoring, and starts the background shipper. Check the connection:

superagent monitor status --agent pi
superagent sync

Use a synthetic command to verify enforcement:

echo "medical record number=TEST-0001"

Pi should receive the rule's deny message instead of executing the command. The blocked action then appears under Agents → Findings.

4. Send Runtime Guardrails events to your monitoring workflow

Open Webhooks and create a target:

  1. Enter the HTTPS endpoint for the monitoring or incident-response system.
  2. Subscribe to agent.finding_created and agent.action_blocked.
  3. Open Sources, expand Agents, and select the Pi Agent.
  4. Save the webhook and copy its signing secret.
  5. Send a test event and verify the signature at the receiver.

The exact Agent source keeps unrelated client activity out of this monitoring workflow. Enforced matches emit agent.action_blocked; monitor-only matches emit agent.finding_created. Filter on prevention.pii_phi_in_tool_arguments at the receiver when the destination should process only this rule.

Next steps