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. Sourced from the context field of your intent submission:

• The agent's task context and current goal
• The decision chain leading to this specific action
• Alternatives the agent considered and rejected
• The agent's confidence in the intent
• Session ID (if provided)

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

Execution trace - What

The mechanical record of what the platform did, generated automatically:

• A timestamped timeline of every IEC state transition
• The policy verdict with per-axis reasoning, per-rule firing detail, and the exact policy rule versions that evaluated the intent
• Which connector executed the action and the normalized result
• Latency at each stage and total cost

The joint trace

Both traces are linked by iecId. The joint trace endpoint assembles the complete picture:

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

Management Plane API

The Management Plane is the human-facing API for querying audit data and reviewing agent activity. It uses your dashboard JWT rather than agent API keys.

List IEC history

GET /manage/v1/iec
Authorization: Bearer YOUR_JWT_TOKEN

Query parameters:

Get a single IEC with full joint trace

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

Returns the complete record with both traces, including per-axis policy results with exact rule versions and the full state transition timeline.

Export joint trace

GET /manage/v1/iec/{iecId}/trace/export?format=json
Authorization: Bearer YOUR_JWT_TOKEN

Returns the joint trace as a self-contained JSON document suitable for compliance submissions or offline analysis.

Get all IECs in a session

GET /manage/v1/iec/session/{sessionId}
Authorization: Bearer YOUR_JWT_TOKEN

Returns all IECs that share the same sessionId, in chronological order. Use this to reconstruct multi-step agent plans and see where they succeeded, deferred, or failed.

Analytics

Aggregate statistics

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

Query parameters: from, to, agentId, domain

Returns: total submitted/executed/denied/deferred/failed counts, success rate, latency p50/p95, total cost, HITL rate, and per-domain breakdown.

Policy effectiveness

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

Returns: denial counts by axis, top firing rules with counts, approval request metrics (total/approved/denied/expired, average resolution time), and risk score distribution.

Per-domain breakdown

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

Returns per-domain IEC volume, approval rates, error rates, and domain health scores.

Dashboard

The Formael dashboard home screen shows a live summary of your organization's activity:

• Recent IEC volume (chart over the selected time window)
• Success rate, HITL rate, and denial rate by axis
• Per-domain IEC breakdown
• HITL backlog (pending approvals waiting for review)

The IEC History page provides the full list view with all filters. The IEC Detail page shows the three-panel joint trace: reasoning on the left, execution timeline in the center, and the policy verdict with per-rule detail on the right.

Domain health

Each domain in the Domains section shows a health score (0–100) reflecting its governance configuration:

A domain with no connector configured scores 0 on connector coverage. A domain with no policy rules applied scores 0 on policy coverage. The recommendations shown alongside the score tell you exactly what to address.

Audit trail guarantees

Immutability. Every IEC record, policy verdict, and execution result is written once and cannot be modified or deleted - 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 trail.

Traceability. Every external action traces from the original agent intent, through the policy decision (with exact rule versions), to the connector execution and provider response. No gap exists in the chain.

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

Compliance use cases