Core Concepts

This page explains the concepts you need to understand to build effectively with Formael. All platform behavior flows from these ideas.

The Intent Execution Cycle (IEC)

The Intent Execution Cycle is the atomic unit of everything in Formael. Every operation - every external action your agent takes - is one IEC.

IEC = Receive(Intent) → Validate → Evaluate Policy → Execute → Record → Return Result

The IEC is:

• The billing unit - every cost is metered per IEC
• The audit unit - every compliance record is one IEC
• The governance unit - policy is evaluated once per IEC
• The observability unit - every metric derives from IEC aggregation

IEC Outcomes

Every IEC terminates with exactly one of these outcomes:

IEC States

An IEC moves through states as it progresses through the pipeline. Each state transition is recorded immutably:

RECEIVED → RESOLVED → POLICY_EVALUATED
                          ├── APPROVED → EXECUTING → SUCCEEDED
                          │                       → FAILED
                          ├── DENIED → CLOSED
                          └── PENDING_APPROVAL → APPROVED → EXECUTING → ...
                                              → DENIED → CLOSED

Capabilities

A Capability is Formael's vocabulary for expressing what an agent wants to do. Agents never reference vendor names or API endpoints directly - they target capabilities.

Every capability is identified by a three-part tuple:

(domain, action, entity)

Examples:

Why capabilities matter

The capability abstraction creates a clean separation between what the agent wants and how it gets done. Your agent sends document-signing.create.contract - Formael handles whether that executes against DocuSign, PandaDoc, or HelloSign based on your organization's configuration.

Switching providers is a configuration change. Your agents, your policies, and your audit trail are completely unaffected.

Capability risk profiles

Every capability carries a risk profile that encodes:

• Reversibility - how difficult it is to undo (0.0 = fully reversible, 1.0 = irreversible)
• Visibility - whether the action affects external parties
• Sensitivity flags - whether the capability involves monetary amounts or PII
• Human-approval default - some high-stakes capabilities (e.g., contracting.sign, identity.deprovision.account) are configured to always require human approval, regardless of your risk threshold

Risk profiles are installed from the pack and represent the baseline values Formael recommends. Your organization can adjust any of these values to reflect your own risk assessment - for example, setting a more conservative reversibility score for a financial action, or disabling the human-approval default for a capability your team has fully automated. See Capability Catalog & Definition Packs for more on customization.

Domains

A Domain represents a business area in which your agents operate. Every capability belongs to a domain.

Domains are part of your organization's installed configuration - they come with the Definition Packs you install. A two-person startup that installs the Messaging and Sales packs operates in exactly those two domains, not all ten in the catalog.

In the management console, the Domains section shows a health score for each of your installed domains (0–100) reflecting how well it is configured: connectors set up, policies applied, and approval routing assigned.

Platform Catalog & Definition Packs

Capabilities don't appear in your organization automatically. They are installed from Formael's Platform Catalog as Definition Packs - curated bundles covering a domain or a business profile.

Installing a pack gives your organization its own copy of every capability in that pack: your risk profiles, your schemas, your governance rules. One organization's customizations never affect another's.

This means the capabilities available to your agents, and the exact parameters and risk settings they carry, are specific to your organization.

See the full Capability Catalog & Definition Packs guide for how to install packs, customize capabilities, and manage upgrades.

Capability Slots

Capabilities don't just declare a parameter shape - they also declare semantic slots: typed roles that fields play in governance. Slots are the contract policies are written against. Because the same slot exists across many capabilities, one rule applies portably wherever the slot is declared.

A rule like "require approval when monetary value exceeds $10,000" applies identically to finance.create.invoice, support.issue.refund, and contracting.create.contract - without rewriting field paths per capability.

The Policy Engine

The Policy Engine is the governance kernel of Formael. Every intent must pass policy evaluation before any execution occurs - no exceptions, no bypass paths.

The policy engine evaluates on four orthogonal axes. All four must pass for execution to proceed; no axis can compensate for another. The verdict is the conjunction.

Axis 1 - Identity

Who, in what context, may invoke this? Per-agent capability grants are configured on Agent Scope, not in policies. The Identity axis owns the rules that apply across agents or change with runtime context: time-of-day windows, environment fencing, cool-downs between calls, agent-group restrictions, and credential context requirements.

Axis 2 - Semantic

What does this intent mean - and is that allowed? Semantic rules read the capability's slots, not raw parameter paths: value above a threshold, counterparty not in an allowlist, content matches a forbidden pattern, classification is sensitive, volume too large.

Axis 3 - Fiscal

Can the organization (and this agent) afford this? Fiscal is two ledgers under one axis: platform spend (USD, what Formael bills your org) and action value (multi-currency, what your agents move externally). They are separate budgets, owned by different people, configured separately.

Axis 4 - Risk

What is the blast radius if this action goes wrong? Composite score from reversibility (40%), visibility (35%), and precedent (25%), evaluated against your org's thresholds. A per-capability HITL pin overrides the score for capabilities you always want a human to review.

The agent's reasoning is evidence, not policy input

IntentEnvelope.context.reasoning is captured for audit and AI suggestion drafting. It is never gating - the policy engine does not consider the natural-language reasoning when computing a verdict.

Policy verdicts

Policy versioning

Every change to a policy rule creates an immutable snapshot before taking effect. Every verdict in your audit trail references the exact rule version that produced it - enabling full point-in-time policy auditability.

Risk Posture

During onboarding, your organization picks one Risk Posture - Conservative, Balanced, or Permissive. The posture applies a curated set of templates and threshold defaults so a new org has working governance from day one. Posture choices are starting points, not lock-ins.

Policy templates

Formael ships pre-built rule sets named in compliance English (e.g. "AP outflow capped at €100k/day", "contracts always reviewed", "no after-hours privileged actions"). Because templates target slots, they apply portably to every capability that emits the relevant slot. Available on Business and above.

Policy simulation

Before activating a rule, simulate it against your organization's last 30 days of IEC history. Simulation deterministically replays the full four-axis evaluation, reports counterfactual verdicts and false-positive estimates, and writes no audit record. See Policy & Governance for details.

Human-in-the-Loop (HITL)

When the risk axis (or a semantic rule) triggers an approval requirement, Formael does not block your agent - it defers the IEC.

The flow:

1. The intent, policy snapshot, and proposed action are persisted durably
2. Your agent receives a Deferred Execution Receipt immediately - sub-second response
3. The Approval Group assigned to the domain is notified in the dashboard
4. The approver reviews the full context - agent reasoning, policy risk assessment, proposed parameters
5. On approval, execution resumes; on denial, the IEC closes with a denied outcome

Your agent polls GET /agent/v1/intents/:iecId to check for resolution.

Approval Groups

An Approval Group is a named team of people responsible for reviewing HITL requests in a specific domain. Every domain can have an assigned approval group - when an intent from that domain is deferred, only that group is notified, keeping the approval inbox focused and reducing noise.

Approval groups are managed in Settings → Approval Groups. Domain assignments are configured in the Domains section of the console.

Sessions

A session groups related IECs from the same agent run. Include a sessionId in your intent's context field to associate the IEC with a session:

"context": {
  "sessionId": "session_vendor_onboarding_jan15"
}

The dashboard's session view shows all IECs in a session in sequence - useful for understanding multi-step agent plans, their outcomes, and where they stopped.

Connectors

A Connector implements a capability for a specific external provider. Connectors handle all provider-specific details: authentication, API endpoints, payload mapping, response normalization, and error handling.

Your organization configures which connector handles each capability via Provider Bindings in the management console. The agent is never aware of which connector executes its intent.

Idempotency

Formael automatically deduplicates intents within a configurable time window. If an identical intent was successfully executed within the window, the cached result is returned - no duplicate execution occurs.

You can also supply a clientRequestId in the intent's idempotency field. This lets you look up the IEC later by your own correlation key using GET /agent/v1/intents?clientRequestId=xxx.

Organizations and Tiers

Every Formael account belongs to an Organization. Organizations are the unit of policy configuration, budget management, credential management, and audit records.

Multiple organizations

A single user can be a member of more than one organization - for example, a consultant working with multiple clients, or an employee with access to a staging and a production account. When you log in and belong to multiple organizations, you'll be prompted to select which one you want to work in. Your session is then scoped to that organization. To switch, log out and log back in.