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 what 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 schemas

Every capability has a defined parameter schema that specifies exactly what data the agent must provide. When you submit an intent, Formael validates your parameters against the capability schema before any policy evaluation happens.

Capability schemas are accessible via the Capability Discovery API.

The Policy Engine

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

The policy engine evaluates on four simultaneous axes. An intent must pass all four to proceed. A single axis failure blocks execution.

Axis 1 — Identity

Is this agent authorized to perform this capability?

Identity axis rules check:

• Whether the agent has been granted permission to invoke this specific capability
• Whether the request falls within allowed time windows or organizational constraints

Axis 2 — Semantic

What does this action mean, and does it comply with your organizational rules?

Semantic axis rules allow you to block or flag actions based on the content of the intent parameters. Examples: blocking contracts above a certain value, flagging messages containing specific keywords, requiring review for actions involving customers above a certain tier.

Axis 3 — Fiscal

What does this action cost, and can your organization or this agent afford it?

The fiscal axis checks the projected cost of the action (API call cost plus platform fee) against the available budget for your organization or the specific agent. Budget is enforced before execution — not after.

Axis 4 — Risk

What is the blast radius if this action goes wrong?

The risk axis calculates a composite score based on:

Risk scores above your organization's requireApprovalAbove threshold trigger human-in-the-loop review. Scores above denyAbove are denied outright.

Policy verdicts

The policy engine produces one of three verdicts:

When an intent is denied, the response includes the per-axis reasoning so your agent can understand why and adjust.

Human-in-the-Loop (HITL)

When the risk axis 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 — no blocking, sub-second response
3. A human approver is notified via dashboard, Slack, or email
4. The approver reviews the full context — agent reasoning, policy assessment, proposed action 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. You can also configure webhooks for push notifications.

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.

Capability: document-signing.create.contract
    ├── Connector: DocuSign
    ├── Connector: PandaDoc
    └── Connector: HelloSign

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.

At launch, Formael ships with 30–50 connectors across 10 domains. See Connectors for the full catalog.

Organizations and Tiers

Every Formael account belongs to an Organization. Organizations are the unit of:

• Policy configuration (rules are per-organization)
• Budget management (budgets are per-organization or per-agent within the org)
• Credential management (provider credentials are scoped to the organization)
• Audit records (all IECs are associated with an organization)

Tier defaults

Enterprise organizations can configure fully custom policy rules across all four axes, replacing or supplementing the tier defaults.

Idempotency

Formael guarantees that identical intents are never executed twice within a configurable deduplication window. This is particularly important for AI agents, which may retry for semantic reasons — re-evaluating a plan and arriving at the same intent — unaware that a duplicate would cause a real-world side effect.

Idempotency is handled automatically by the platform. The agent does not need to manage idempotency keys. If an intent matches a recent execution, the cached result is returned and the deduplication is recorded in the audit trail — nothing is silent.