Getting Started — AI Runtime Governor

Real-time governance, compliance, and observability for autonomous AI agents.
Evaluate every tool call before execution. Enforce custom policies. Detect multi-step threats. Stay audit-ready.

curl https://api.airg.nov-tia.com/healthz
# → {"status":"ok"}

curl -s -X POST https://api.airg.nov-tia.com/actions/evaluate \
  -H "X-API-Key: airg_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "shell",
    "args": {"command": "rm -rf /"},
    "context": {"agent_id": "my-agent"}
  }' | jq .

{
  "decision": "block",
  "risk_score": 95,
  "explanation": "Destructive filesystem operation",
  "policy_ids": ["shell-dangerous"],
  "execution_trace": [...]
}

# Python
pip install airg-client

# TypeScript / JavaScript
npm install @airg/governor-client

# Java (Maven)
<dependency>
  <groupId>dev.airg</groupId>
  <artifactId>governor-client</artifactId>
  <version>0.3.0</version>
</dependency>

Chain analysis runs automatically on every evaluation. No configuration required. Detected patterns appear in the Chain Analysis dashboard tab.

# Login → JWT token
TOKEN=$(curl -s -X POST https://api.airg.nov-tia.com/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"your-password"}' | jq -r .access_token)

echo $TOKEN

# Rotate your own API key (self-service)
curl -s -X POST https://api.airg.nov-tia.com/auth/me/rotate-key \
  -H "Authorization: Bearer $TOKEN" | jq .

# Returns: {"api_key": "airg_abc123..."}

# As admin, create an operator account
curl -s -X POST https://api.airg.nov-tia.com/auth/users \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"username":"agent-ops","password":"secure-password","role":"operator"}' | jq .

Tip: After your first login, navigate to the API Keys tab in the dashboard to generate an API key for programmatic access. API keys (airg_… prefix) are the recommended authentication method for agent integrations.

import governor_client
from governor_client import evaluate_action, GovernorBlockedError

governor_client.GOVERNOR_URL = "https://api.airg.nov-tia.com"
governor_client.GOVERNOR_API_KEY = "airg_your_key_here"

try:
    decision = evaluate_action("shell", {"command": "ls -la"}, context={
        "agent_id": "my-agent",
        "session_id": "session-123",
        "allowed_tools": ["shell", "http_request", "file_read"],
    })
    print(f"{decision['decision']} — risk {decision['risk_score']}")
except GovernorBlockedError as e:
    print(f"Blocked: {e}")
    # Do NOT execute the tool

import { GovernorClient, GovernorBlockedError } from "@airg/governor-client";

const gov = new GovernorClient({
  baseUrl: "https://api.airg.nov-tia.com",
  apiKey: "airg_your_key_here",
});

try {
  const d = await gov.evaluate("shell", { command: "ls -la" }, {
    agent_id: "my-agent",
    allowed_tools: ["shell", "http_request"],
  });
  console.log(`${d.decision} — risk ${d.risk_score}`);
} catch (err) {
  if (err instanceof GovernorBlockedError) {
    console.error("Blocked:", err.message);
  }
}

GovernorClient gov = new GovernorClient.Builder()
    .baseUrl("https://api.airg.nov-tia.com")
    .apiKey("airg_your_key_here")
    .build();

try {
    GovernorDecision d = gov.evaluate("shell", Map.of("command", "ls -la"));
    System.out.println(d.getDecision() + " — risk " + d.getRiskScore());
} catch (GovernorBlockedError e) {
    System.err.println("Blocked: " + e.getMessage());
}

export GOVERNOR_URL=https://api.airg.nov-tia.com
export GOVERNOR_API_KEY=airg_your_key_here

from governor_client import (
    evaluate_action,
    GovernorBlockedError,
    GovernorReviewRejectedError,
    GovernorReviewExpiredError,
)

try:
    decision = evaluate_action(
        "deploy_contract",
        {"contract": "TokenSwap.sol"},
        context={"agent_id": "defi-agent"},
        review_mode="hold",       # wait for human decision
        hold_timeout=120,          # max 120s
    )
    # If we reach here, the action was approved
    print(f"Approved by {decision.get('review_resolved_by')}")
except GovernorBlockedError:
    print("Blocked by policy")
except GovernorReviewRejectedError as e:
    print(f"Human rejected: {e}")
except GovernorReviewExpiredError as e:
    print(f"Review timed out: {e}")

curl -s -X POST https://api.airg.nov-tia.com/actions/evaluate \
  -H "X-API-Key: airg_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "http_request",
    "args": {
      "method": "POST",
      "url": "https://api.example.com/data",
      "body": {"query": "SELECT * FROM users"}
    },
    "context": {
      "agent_id": "data-pipeline-agent",
      "session_id": "run-456",
      "allowed_tools": ["http_request", "file_read"]
    }
  }' | jq .

# Full lifecycle example (Python)
import governor_client as gc

gc.GOVERNOR_URL = "https://api.airg.nov-tia.com"  # production endpoint
gc.GOVERNOR_API_KEY = "airg_..."  # your API key from the dashboard

# Step 1: Pre-execution governance
decision = gc.evaluate_action("file_write", {
    "path": "/app/config.py",
    "content": "DEBUG = True"
}, context={"agent_id": "my-agent"})

if decision["decision"] == "block":
    print("Blocked — skipping execution")
elif decision["decision"] == "allow":
    # Step 2: Execute the tool
    result = actually_write_file("/app/config.py", "DEBUG = True")

    # Step 3: Post-execution verification (optional but recommended)
    import httpx
    verify_resp = httpx.post(f"{gc.GOVERNOR_URL}/actions/verify", json={
        "action_id": decision["action_id"],
        "tool": "file_write",
        "result": {"status": "success", "output": "Wrote 1 line"},
        "context": {"agent_id": "my-agent"}
    }, headers={"X-API-Key": gc.GOVERNOR_API_KEY})
    print(verify_resp.json()["verdict"])  # "compliant" or "violation"

curl -s -X POST https://api.airg.nov-tia.com/actions/verify \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action_id": 42,
    "tool": "file_write",
    "result": {
      "status": "success",
      "output": "Wrote 150 lines to /etc/passwd",
      "diff": "- root:x:0:0\n+ root:x:0:0:hacked"
    },
    "context": {
      "agent_id": "my-agent",
      "trace_id": "trace-abc"
    }
  }' | jq .

curl -s -H "Authorization: Bearer $TOKEN" \
  "https://api.airg.nov-tia.com/actions/verifications?verdict=violation" | jq .

decision = evaluate_action("shell", {"command": "ls"}, context={
    "agent_id": "my-agent",
    "conversation_id": "conv-abc-123",
    "turn_id": 1,
    "prompt": "User asked me to list directory contents"
})

curl -s -X POST https://api.airg.nov-tia.com/conversations/turns/batch \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "conversation_id": "conv-abc-123",
      "turn_number": 1,
      "role": "user",
      "content": "List the files in /tmp"
    },
    {
      "conversation_id": "conv-abc-123",
      "turn_number": 2,
      "role": "assistant",
      "content": "I will use the shell tool to list the files."
    }
  ]' | jq .

# List all conversations
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://api.airg.nov-tia.com/conversations" | jq .

# Get unified timeline (turns + governance actions interleaved)
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://api.airg.nov-tia.com/conversations/conv-abc-123/timeline" | jq .

curl -s -X POST https://api.airg.nov-tia.com/traces/ingest \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "spans": [
      {
        "trace_id": "trace-task-001",
        "span_id": "root-span",
        "name": "Research Market Data",
        "kind": "agent",
        "start_time": "2026-02-28T12:00:00Z",
        "end_time": "2026-02-28T12:00:05Z"
      },
      {
        "trace_id": "trace-task-001",
        "span_id": "llm-call-1",
        "parent_span_id": "root-span",
        "name": "GPT-4 reasoning",
        "kind": "llm",
        "start_time": "2026-02-28T12:00:01Z",
        "end_time": "2026-02-28T12:00:03Z"
      }
    ]
  }' | jq .

decision = evaluate_action("shell", {"command": "ls"}, context={
    "agent_id": "my-agent",
    "trace_id": "trace-task-001",
    "span_id": "llm-call-1",
})
# → A governance span is auto-created as a child of llm-call-1

# List all traces
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://api.airg.nov-tia.com/traces" | jq .

# Full trace with span tree
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://api.airg.nov-tia.com/traces/trace-task-001" | jq .

# Terminal
curl -N -H "Authorization: Bearer $TOKEN" \
  https://api.airg.nov-tia.com/actions/stream

# Or with API key
curl -N -H "X-API-Key: airg_your_key" \
  https://api.airg.nov-tia.com/actions/stream

const es = new EventSource(
  "https://api.airg.nov-tia.com/actions/stream?token=" + jwt
);
es.addEventListener("action_evaluated", (e) => {
  const { tool, decision, risk_score } = JSON.parse(e.data);
  console.log(`${tool}: ${decision} (risk ${risk_score})`);
});

curl https://api.airg.nov-tia.com/actions/stream/status
# → {"active_subscribers": 2, "heartbeat_interval_seconds": 15}

- policy_id: shell-dangerous
  description: "Block destructive shell commands"
  tool: "shell"
  severity: critical
  action: block
  args_regex: "(rm\\s+-rf|mkfs|dd\\s+if=|shutdown|reboot)"

# Create a policy
curl -s -X POST https://api.airg.nov-tia.com/policies \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "policy_id": "block-external-uploads",
    "description": "Block HTTP uploads to external domains",
    "tool": "http_request",
    "severity": "high",
    "action": "block",
    "url_regex": "^https?://(?!internal\\.company\\.com)"
  }' | jq .

# Toggle a policy on/off
curl -s -X PATCH https://api.airg.nov-tia.com/policies/block-external-uploads/toggle \
  -H "Authorization: Bearer $TOKEN" | jq .

# Partial update (only change description and severity)
curl -s -X PATCH https://api.airg.nov-tia.com/policies/block-external-uploads \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"description": "Updated description", "severity": "critical"}' | jq .

# List versions
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://api.airg.nov-tia.com/policies/block-external-uploads/versions" | jq .

# Restore a version
curl -s -X POST \
  "https://api.airg.nov-tia.com/policies/block-external-uploads/versions/2/restore" \
  -H "Authorization: Bearer $TOKEN" | jq .

# Check SURGE v2 status
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://api.airg.nov-tia.com/surge/v2/status" | jq .

# List receipts
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://api.airg.nov-tia.com/surge/v2/receipts" | jq .

# Verify chain integrity
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://api.airg.nov-tia.com/surge/v2/verify" | jq .

# Export compliance bundle
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://api.airg.nov-tia.com/surge/v2/export?period_start=2026-01-01&period_end=2026-03-31" | jq .

# Create a Slack channel
curl -s -X POST https://api.airg.nov-tia.com/notifications/channels \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "security-alerts",
    "channel_type": "slack",
    "config_json": {
      "webhook_url": "https://hooks.slack.com/services/T.../B.../..."
    },
    "is_active": true
  }' | jq .

curl -s -H "Authorization: Bearer $TOKEN" \
  "https://api.airg.nov-tia.com/escalation/events?status=pending" | jq .

# Approve an event
curl -s -X PUT https://api.airg.nov-tia.com/escalation/events/42/approve \
  -H "Authorization: Bearer $TOKEN" | jq .

# List all fingerprinted agents
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://api.airg.nov-tia.com/fingerprint/agents" | jq .

# Assess a specific action
curl -s -X POST https://api.airg.nov-tia.com/impact/assess \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tool": "deploy_contract", "args": {}, "context": {"agent_id": "my-agent"}}' | jq .

# Get impact assessment for an agent
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://api.airg.nov-tia.com/impact/assess/agent/my-agent" | jq .

# List all assessed agents
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://api.airg.nov-tia.com/impact/agents" | jq .

# List all clauses
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://api.airg.nov-tia.com/compliance/clauses" | jq .

# Filter by framework
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://api.airg.nov-tia.com/compliance/clauses/eu_ai_act" | jq .

# Seed clauses (first time)
curl -s -X POST https://api.airg.nov-tia.com/compliance/clauses/seed \
  -H "Authorization: Bearer $TOKEN" | jq .