Observability & Audit

Formael produces a complete, permanent record of every intent your agents submit and every action the platform takes. This page explains the dual-trace model and how to use the Management Plane API to query your audit history.

The dual-trace model

For every IEC, Formael records two complementary traces that together answer the complete audit question: "why did the agent want this, and what exactly did the platform do about it?"

Reasoning trace — Why

The causal chain from the agent's goal to the submitted intent. This comes from the context field of your intent submission and contains:

The agent's task context and current goal
The reasoning that led to this specific action
Alternatives the agent considered and rejected
The agent's confidence in the intent

This trace is provided by your agent and stored as-is. It is queryable and visible to human approvers during HITL review.

Execution trace — What

The mechanical record of what the platform did, generated automatically at each pipeline stage:

A timestamped timeline of every IEC state transition
The policy verdict with per-axis reasoning and scores
Which connector executed the action and the raw + normalized result
Latency at each stage
Cost breakdown

The joint trace

Both traces are linked by iecId. A single query assembles the complete picture — the full story from "why the agent wanted this" to "exactly what happened when the platform acted on it."

iecId: 01HX4K2M9V3T7P8Q5N6R0J1W2Y
  │
  ├── Reasoning trace
  │     goal: "Initiate NDA for new vendor partnership"
  │     reasoning: "Contract required before sharing specifications"
  │     confidence: 0.95
  │
  └── Execution trace
        RECEIVED at 12:00:00.000
        RESOLVED at 12:00:00.012  (schema validated)
        POLICY_EVALUATED at 12:00:00.031
          identity: APPROVED
          semantic: APPROVED
          fiscal: APPROVED (cost: $0.85, remaining: $499.15)
          risk: APPROVED (score: 0.38)
        APPROVED at 12:00:00.031
        EXECUTING at 12:00:00.032
          connector: docusign-v2
          provider_correlation: env_2XmZ9kPq
        SUCCEEDED at 12:00:00.843
          latency: 811ms

Management Plane API

The Management Plane is the human-facing API for querying audit data, managing configurations, and reviewing agent activity. It uses Keycloak JWT authentication (your dashboard login) rather than agent API keys.

List IEC history

GET /manage/v1/iec
Authorization: Bearer YOUR_JWT_TOKEN

Query parameters:

Parameter	Type	Description
`agentId`	string	Filter by specific agent
`domain`	string	Filter by capability domain
`outcome`	string	Filter by outcome: `executed`, `denied`, `deferred`, `failed_retryable`, `failed_terminal`, `deduplicated`
`state`	string	Filter by current IEC state
`from`	ISO 8601	Start of date range
`to`	ISO 8601	End of date range
`limit`	integer	Results per page (max 100, default 25)
`cursor`	string	Pagination cursor from previous response

Response:

{
  "items": [
    {
      "iecId": "01HX4K2M9V3T7P8Q5N6R0J1W2Y",
      "agentId": "agent_contract_bot",
      "domain": "document-signing",
      "action": "create",
      "entity": "contract",
      "outcome": "executed",
      "state": "SUCCEEDED",
      "submittedAt": "2024-01-15T12:00:00Z",
      "executedAt": "2024-01-15T12:00:00.843Z",
      "latencyMs": 843,
      "cost": {
        "total": 0.85,
        "currency": "USD"
      }
    }
  ],
  "nextCursor": "eyJpZCI6IjAxSFg0SzJ...",
  "total": 1842
}

Get a single IEC with full joint trace

GET /manage/v1/iec/{iecId}
Authorization: Bearer YOUR_JWT_TOKEN

Returns the complete record including both reasoning trace and execution trace:

{
  "iecId": "01HX4K2M9V3T7P8Q5N6R0J1W2Y",
  "agentId": "agent_contract_bot",
  "domain": "document-signing",
  "action": "create",
  "entity": "contract",
  "parameters": { ... },
  "context": {
    "agentGoal": "Initiate NDA for new vendor partnership",
    "reasoning": "Contract required before sharing specifications",
    "confidence": 0.95
  },
  "outcome": "executed",
  "state": "SUCCEEDED",
  "submittedAt": "2024-01-15T12:00:00Z",
  "policyVerdict": {
    "decision": "APPROVED",
    "evaluatedAt": "2024-01-15T12:00:00.031Z",
    "evaluationTimeMs": 19,
    "axisResults": {
      "identity": { "verdict": "APPROVED" },
      "semantic": { "verdict": "APPROVED" },
      "fiscal": {
        "verdict": "APPROVED",
        "projectedCost": 0.85,
        "remainingBudget": 499.15
      },
      "risk": {
        "verdict": "APPROVED",
        "score": 0.38,
        "breakdown": {
          "reversibility": 0.4,
          "visibility": 0.35,
          "precedent": 0.38
        }
      }
    }
  },
  "execution": {
    "outcome": "SUCCEEDED",
    "connector": "docusign-v2",
    "providerCorrelation": "env_2XmZ9kPq",
    "latencyMs": 811,
    "executedAt": "2024-01-15T12:00:00.843Z",
    "result": {
      "contractId": "env_2XmZ9kPq",
      "status": "sent"
    }
  },
  "stateTransitions": [
    { "state": "RECEIVED", "at": "2024-01-15T12:00:00.000Z" },
    { "state": "RESOLVED", "at": "2024-01-15T12:00:00.012Z" },
    { "state": "POLICY_EVALUATED", "at": "2024-01-15T12:00:00.031Z" },
    { "state": "APPROVED", "at": "2024-01-15T12:00:00.031Z" },
    { "state": "EXECUTING", "at": "2024-01-15T12:00:00.032Z" },
    { "state": "SUCCEEDED", "at": "2024-01-15T12:00:00.843Z" }
  ]
}

Aggregate statistics

GET /manage/v1/iec/stats
Authorization: Bearer YOUR_JWT_TOKEN

Query parameters: from, to, agentId, domain

Response:

{
  "period": {
    "from": "2024-01-01T00:00:00Z",
    "to": "2024-01-15T23:59:59Z"
  },
  "totals": {
    "submitted": 4821,
    "executed": 4203,
    "denied": 312,
    "deferred": 189,
    "failed": 117
  },
  "successRate": 0.871,
  "averageLatencyMs": 743,
  "totalCost": {
    "amount": 4103.45,
    "currency": "USD"
  },
  "byDomain": {
    "document-signing": { "submitted": 1240, "executed": 1187 },
    "project-management": { "submitted": 2109, "executed": 2089 },
    "messaging": { "submitted": 1472, "executed": 927 }
  }
}

Policy effectiveness report

Understand which policy rules are firing and whether your thresholds are well-calibrated:

GET /manage/v1/iec/stats/policy
Authorization: Bearer YOUR_JWT_TOKEN

Response:

{
  "denialsByAxis": {
    "identity": 12,
    "semantic": 89,
    "fiscal": 184,
    "risk": 27
  },
  "topDenialReasons": [
    {
      "ruleId": "rule_8Xk2P",
      "description": "Daily agent budget exceeded",
      "count": 142,
      "axis": "fiscal"
    }
  ],
  "approvalRequestStats": {
    "total": 189,
    "approved": 156,
    "denied": 18,
    "expired": 15,
    "averageResolutionMinutes": 23
  },
  "riskScoreDistribution": {
    "0.0-0.3": 2891,
    "0.3-0.6": 1203,
    "0.6-0.8": 512,
    "0.8-1.0": 215
  }
}

Audit trail guarantees

The Formael audit trail provides the following guarantees:

Immutability. Every IEC record, policy verdict, and execution result is written once and cannot be modified or deleted. The audit trail cannot be tampered with — by anyone, including Formael.

Completeness. Every intent that enters the platform is recorded, regardless of outcome. Denied intents, failed executions, and deduplicated results are all in the audit trail.

Traceability. Every external action can be traced from the original agent intent, through the policy decision, to the connector execution and provider response. No gap exists in the chain.

Reasoning visibility. The agent's context (the context field on intent submission) is stored alongside every record. Compliance teams can see not just what the agent did, but why.

These guarantees are enforced at the data layer. They hold regardless of any application-level configuration.

Compliance use cases

Requirement	How Formael addresses it
"What did agent X do on date Y?"	Query `GET /manage/v1/iec` filtered by `agentId` and date range
"Why was this external action taken?"	Fetch the joint trace for the IEC — reasoning + execution combined
"Was this action authorized?"	Policy verdict in the joint trace includes per-axis reasoning and the specific rule that triggered
"What did this cost?"	Per-IEC cost breakdown in the execution record; aggregate in stats endpoint
"Who approved this action?"	Approval request record includes approver identity and timestamp
"Can I prove this record hasn't been altered?"	Records are append-only at the infrastructure level — immutability is structural, not policy-based

←

Policy & Governance

Connectors & Integrations

→