Agent Messaging¶

SafeAI enforces security policies on agent-to-agent communication. When one agent sends a message to another, intercept_agent_message scans the content for secrets and PII, evaluates policies, and can block, redact, or route the message through an approval workflow. This prevents sensitive data from leaking across agent boundaries.

Quick Example¶

from safeai import SafeAI

ai = SafeAI.from_config("safeai.yaml")

result = ai.intercept_agent_message(
    message="Customer email is alice@example.com",
    source_agent_id="support-bot",
    destination_agent_id="analytics-bot",
)
print(result.action)     # "redact"
print(result.safe_text)  # "Customer email is [EMAIL REDACTED]"

Full Example¶

safeai.yaml

policies:
  - name: block-secrets-between-agents
    boundary: agent_message
    priority: 200
    condition:
      data_tags: [secret]
    action: block
    reason: "Secrets must not pass between agents"

  - name: redact-pii-between-agents
    boundary: agent_message
    priority: 100
    condition:
      data_tags: [personal.pii]
    action: redact
    reason: "PII must be redacted in inter-agent messages"

  - name: approve-financial-between-agents
    boundary: agent_message
    priority: 50
    condition:
      data_tags: [personal.financial]
    action: require_approval
    reason: "Financial data transfer requires approval"

from safeai import SafeAI

ai = SafeAI.from_config("safeai.yaml")

# Message with PII — gets redacted
r1 = ai.intercept_agent_message(
    message="User phone: (555) 867-5309, email: alice@example.com",
    source_agent_id="support-bot",
    destination_agent_id="analytics-bot",
)
assert r1.action == "redact"
print(r1.safe_text)
# "User phone: [PHONE REDACTED], email: [EMAIL REDACTED]"

# Message with a secret — blocked entirely
r2 = ai.intercept_agent_message(
    message="Use this key: sk-ABCDEF1234567890",
    source_agent_id="deploy-bot",
    destination_agent_id="monitor-bot",
)
assert r2.action == "block"
print(r2.reason)
# "Secrets must not pass between agents"

# Message with financial data — routed to approval
r3 = ai.intercept_agent_message(
    message="Transfer $50,000 from account 1234 to 5678",
    source_agent_id="finance-bot",
    destination_agent_id="executor-bot",
)
assert r3.action == "require_approval"
print(r3.request_id)  # "apr-c4e2..."

Messages are scanned like any other boundary

Agent messages go through the same secret detection, PII detection, and policy evaluation as scan_input and guard_output. The agent_message boundary lets you write policies specific to inter-agent traffic.

How It Works¶

Source Agent ──► intercept_agent_message() ──► Policy Engine ──► Destination Agent
                        │                          │
                    Scan for                   Evaluate rules
                  secrets & PII              (block/redact/approve)

The source agent calls intercept_agent_message with the message and both agent IDs.
SafeAI scans the message for secrets and PII, producing data tags.
The policy engine evaluates rules with boundary: agent_message.
Based on the matched policy, the message is allowed, redacted, blocked, or queued for approval.

Approval Workflows for Messages¶

When a policy returns require_approval, the message is held until a human approves it:

result = ai.intercept_agent_message(
    message="Account balance: $52,340.00",
    source_agent_id="finance-bot",
    destination_agent_id="report-bot",
)

if result.action == "require_approval":
    # Message is queued — notify approver
    print(f"Approval needed: {result.request_id}")

    # Approver reviews and approves
    ai.approve_request(result.request_id, approver="ops-lead")

See the Approval Workflows guide for full details.

Configuration¶