Agent Specification

AI Agent & Reasoning Plane Spec

Deterministic protocol specification, JSON schemas, Model Context Protocol (MCP) tool catalogs, and Risk Tier classification taxonomy for autonomous agents.

Rule of Decoupled Intelligence for Autonomous Agents

AI agents MUST NOT generate raw SQL, execute bash commands, or directly invoke infrastructure endpoints. Agents ONLY emit schema-validated ActionIntent payloads. The Action Gateway independently evaluates identity, tenant boundary, blast radius, and risk tier before any execution occurs.

Interactive Action Gateway Simulator

Experience the strict Decoupled Intelligence boundary: AI proposes an ActionIntent, the Action Gateway enforces deterministic risk tiers, cryptographic HMAC signing, and fails closed.

1. Reasoning PlaneAI Agent

Autonomous agent assesses system state and formulates a strict, declarative ActionIntent.

Intent ID: int_9f81a702-8b4e-4e3a
Actor: agent_edge_optimizer_v4
Verb: purge_cache
Resource: zones/vaulthost.dev/cache
"Observed 404 rate increase on /v2/api after deployment #912. Evicting edge L2 cache to force origin refetch."
2. Action GatewayDeterministic Guard

Evaluates blast radius, computes HMAC tamper seal, and maps action to policy safeguards.

Classified Risk:Tier 0
HMAC Signature:sha256:7f9a12c8purge93019ab921b74f0148c2b7405e6b12a
Policy Rule: Autonomous Auto-Approval
3. Execution PlaneInfrastructure

Executes only with valid cryptographic token; records tamper-proof ledger entry.

Ready for dispatch.

Risk Classification Matrix

The Action Gateway deterministically maps every ActionIntent into one of four Risk Tiers based on verb semantics, environment, and blast radius.

TierClassificationAllowed VerbsGatekeeper RequirementAgent Behavior
Tier 0Read-only / Observabilityget, list, read, query, logs, metrics, statusImmediate execution + signed audit logSynchronous result returned immediately
Tier 1Low-Mutation / Safe Additioncreate, add_dns_record, set, upload, stage, previewDiff preview + confirmationToken verificationInspect diff, present to user, re-submit token
Tier 2High-Mutation / Service Deploydeploy_worker, scale, restart, switch_traffic, update_dns_zoneStep-up 2FA / TOTP authentication challengePrompt human operator for 2FA verification token
Tier 3Destructive / Irreversibledrop_table, delete_database, purge_all_dns, delete_bucketDual-Authorization Human Staff Approval QueueHeld in queue. Agent monitors status via requestId

Canonical ActionIntent JSON Schema

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "ActionIntent",
  "type": "object",
  "required": [
    "intentId",
    "actor",
    "targetService",
    "actionVerb",
    "resourceUri",
    "parameters",
    "idempotencyKey",
    "createdAt"
  ],
  "properties": {
    "intentId": { "type": "string", "format": "uuid" },
    "actor": {
      "type": "object",
      "required": ["id", "type", "tenantId", "roles"],
      "properties": {
        "id": { "type": "string" },
        "type": { "type": "string", "enum": ["ai_agent", "user", "system"] },
        "tenantId": { "type": "string" },
        "email": { "type": "string", "format": "email" },
        "roles": { "type": "array", "items": { "type": "string" } },
        "delegationToken": { "type": "string" },
        "clientIp": { "type": "string" }
      }
    },
    "targetService": {
      "type": "string",
      "enum": ["compute", "storage", "database", "dns", "ai_gateway", "network", "billing", "iam"]
    },
    "actionVerb": { "type": "string" },
    "resourceUri": { "type": "string" },
    "parameters": { "type": "object" },
    "idempotencyKey": { "type": "string", "minLength": 8 },
    "reasoningTrace": { "type": "string" },
    "confidenceScore": { "type": "number", "minimum": 0, "maximum": 1 },
    "createdAt": { "type": "string", "format": "date-time" }
  }
}

Model Context Protocol (MCP) JSON-RPC 2.0

All tools exposed by VaultHost conform to the standard MCP specification. External LLM orchestrators can invoke tools directly against /api/action-gateway/mcp.

{
  "jsonrpc": "2.0",
  "id": "req-001",
  "method": "tools/call",
  "params": {
    "name": "vaulthost_workers_deploy",
    "arguments": {
      "workerName": "edge-auth-router",
      "action": "deploy",
      "environment": "production",
      "scriptCode": "export default { async fetch(req) { return new Response('OK'); } }"
    }
  }
}
1