Best Practices

Define your governance goals before writing policies. Understand what risks you're mitigating and what behaviors you want to enforce.

• Document the specific risks each policy addresses
• Involve legal, compliance, and security teams in policy design
• Start with broad categories (PII, financial, external comms) then refine
• Review policies quarterly to ensure they remain relevant

# Good: Clear, specific policy with documented purpose
policies:
  - name: block-financial-advice
    description: |
      Prevent agents from providing specific financial advice
      that could create liability. Allows general information.
      Risk: Legal liability, regulatory compliance
      Owner: legal@company.com
    trigger: output
    action: BLOCK
    conditions:
      - type: content_match
        patterns:
          - "you should (buy|sell|invest)"
          - "guaranteed returns"
          - "financial advice"

Use multiple overlapping controls rather than relying on a single policy. Different layers catch different types of issues.

• Combine input validation, output filtering, and action controls
• Use both pattern matching and semantic analysis
• Implement circuit breakers as a safety net
• Add human approval for high-risk actions

# Layered approach for sensitive operations
policies:
  # Layer 1: Input validation
  - name: validate-input-pii
    trigger: input
    action: REDACT
    conditions:
      - type: pii_detected

  # Layer 2: Action control
  - name: require-approval-external
    trigger: action
    action: APPROVAL
    conditions:
      - type: action_type
        value: "send_external_message"

  # Layer 3: Output filtering
  - name: filter-output-pii
    trigger: output
    action: BLOCK
    conditions:
      - type: pii_detected

  # Layer 4: Circuit breaker (safety net)
  - name: external-comms-breaker
    type: circuit_breaker
    error_threshold: 5
    cooldown_minutes: 30

Set up comprehensive monitoring to detect issues early and understand how your agents are behaving in production.

• Configure alerts for policy violations and anomalies
• Track trends in blocked actions over time
• Set up dashboards for key governance metrics
• Review audit logs regularly for unexpected patterns

import os
import requests

# There is no Python cloud SDK — these are REST calls with your API key.
BASE = "https://tork.network/api/v1"
headers = {"Authorization": f"Bearer {os.environ['TORK_API_KEY']}"}

# Alert rule: fire when /govern denies. Channels are "dashboard" and "email";
# Slack and Discord are configured separately under /integrations.
requests.post(
    f"{BASE}/governance-alerts/rules",
    headers=headers,
    json={
        "name": "deny-spike",
        "event_type": "deny",   # deny | high_pii | rate_limit_hit | canary_silence | overage | score_drop
        "threshold": 10,
        "channels": ["dashboard", "email"],
        "recipients": ["security@company.com"],
    },
    timeout=10,
)

# Read the 7-day analytics summary
summary = requests.get(f"{BASE}/analytics", headers=headers, params={"range": "7d"}, timeout=10).json()
print(summary)

# Unacknowledged alerts
alerts = requests.get(f"{BASE}/governance-alerts", headers=headers, params={"acknowledged": "false"}, timeout=10).json()
for event in alerts["events"]:
    print(event)

Validate policies in a staging environment before deploying to production. Use WARN mode to understand impact without blocking.

• Start new policies in WARN mode to measure impact
• Create test cases for expected allow and block scenarios
• Test edge cases and adversarial inputs
• Gradually roll out policies to production

# Test policy before production deployment
def test_pii_policy():
    test_cases = [
        # Should block
        ("My SSN is 123-45-6789", True),
        ("Call me at 555-123-4567", True),
        # Should allow
        ("The weather is nice", False),
        ("Meeting at 3pm", False),
    ]

    for content, should_block in test_cases:
        result = requests.post(
            f"{BASE}/govern",
            headers=headers,
            json={"content": content, "options": {"mode": "deny"}, "agent_id": "test-agent"},
            timeout=10,
        ).json()
        # Every /govern call writes a receipt; use a separate staging API key for tests.
        assert (result["action"] == "deny") == should_block

# Create the policy inactive first, review its receipts, then flip is_active
requests.post(
    f"{BASE}/policies",
    headers=headers,
    json={"name": "new-pii-policy", "yaml_content": policy_yaml, "is_active": False},
    timeout=10,
)

Use human approval for high-impact decisions while keeping low-risk operations automated.

• Reserve approvals for truly high-risk actions
• Set reasonable timeout periods for approvals
• Provide approvers with full context for decisions
• Track approval turnaround times and optimize

Design governance checks to minimize latency impact on your AI applications.

• Use caching for repeated policy checks
• Order policies by likelihood of match (most common first)
• Use async webhooks instead of polling for approvals
• Batch similar checks when possible

# There is no batch endpoint: /govern takes one content string per call.
# Run independent checks concurrently instead.
from concurrent.futures import ThreadPoolExecutor

def govern(content: str, agent_id: str) -> dict:
    return requests.post(
        f"{BASE}/govern",
        headers=headers,
        json={"content": content, "agent_id": agent_id},
        timeout=10,
    ).json()

with ThreadPoolExecutor(max_workers=4) as pool:
    results = list(pool.map(lambda c: govern(*c), [
        (content1, "agent-1"), (content2, "agent-2"), (content3, "agent-3"),
    ]))

# Cache decisions for repeated content (each cached hit skips a /govern call
# and therefore skips its receipt — cache only where that is acceptable)
from functools import lru_cache

@lru_cache(maxsize=1000)
def cached_govern(content_hash: str, agent_id: str) -> dict:
    return govern(content_from_hash(content_hash), agent_id)