Quick Start

This guide gets you from zero to a successfully executed intent in minutes.

Prerequisites

You need a Formael account with at least one agent created and an API key issued. Sign up at app.formael.com if you haven't already.

Your organization must also have at least one Definition Pack installed - capabilities come from the packs your organization has chosen to enable. If you haven't installed any packs yet, see Capability Catalog & Definition Packs.

Step 1: Get your API key

In the Formael dashboard, navigate to Agents and create a new agent. After creation, issue an API key for that agent. Copy the key - it is only shown once.

Your API key looks like:

fml_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Include it on every request to the Agent Plane API as a Bearer token:

Authorization: Bearer fml_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Step 2: Discover available capabilities

Before submitting an intent, check which capabilities are available in your organization's configuration:

curl https://api.formael.com/agent/v1/capabilities \
  -H "Authorization: Bearer YOUR_API_KEY"

The response lists capabilities grouped by domain:

[
  {
    "domain": "document-signing",
    "capabilities": [
      {
        "domain": "document-signing",
        "action": "create",
        "entity": "contract",
        "description": "Create a new contract and send it for signing",
        "version": "1.0.0"
      }
    ]
  }
]

Step 3: Submit your first intent

Submit an intent using the IntentEnvelope v1 format:

curl -X POST https://api.formael.com/v1/intents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schemaVersion": "1.0",
    "domain": "document-signing",
    "action": "create",
    "entity": "contract",
    "parameters": {
      "signerName": "Jane Smith",
      "signerEmail": "[email protected]",
      "templateId": "tmpl_mutual_nda",
      "subject": "Mutual NDA - Acme Corp"
    },
    "idempotency": {
      "clientRequestId": "req_abc123",
      "strategy": "strict"
    },
    "context": {
      "agentGoal": "Initiate NDA for new vendor partnership with Acme Corp",
      "decisionChain": ["Partnership requires NDA before sharing specs"],
      "confidence": 0.95,
      "sessionId": "session_xyz789"
    }
  }'

The context field is optional but recommended - it becomes part of the permanent audit record and makes your agent's reasoning visible to approvers and compliance teams. clientRequestId lets you look up this IEC later using your own correlation key. sessionId groups related IECs from the same agent session.

Step 4: Understand the response

Immediate execution (approved)

If the intent passes policy evaluation, execution happens synchronously:

{
  "iecId": "01HX4K2M9V3T7P8Q5N6R0J1W2Y",
  "outcome": "executed",
  "state": "SUCCEEDED",
  "result": {
    "contractId": "env_2XmZ9kPq...",
    "signingUrl": "https://app.docusign.com/sign/...",
    "status": "sent"
  }
}

Deferred execution (pending human approval)

If the intent triggers a human approval requirement, you receive a receipt immediately - the action is not blocked:

{
  "iecId": "01HX4K2M9V3T7P8Q5N6R0J1W2Y",
  "outcome": "deferred",
  "state": "PENDING_APPROVAL",
  "estimatedResolution": "2024-01-15T14:30:00Z"
}

Poll for resolution using the iecId:

curl https://api.formael.com/v1/intents/01HX4K2M9V3T7P8Q5N6R0J1W2Y \
  -H "Authorization: Bearer YOUR_API_KEY"

Denied

If the intent is denied by policy, the response includes per-axis reasoning:

{
  "iecId": "01HX4K2M9V3T7P8Q5N6R0J1W2Y",
  "outcome": "denied",
  "state": "CLOSED",
  "denial": {
    "axisResults": {
      "fiscal": {
        "verdict": "DENIED",
        "reason": "Projected cost of $45.00 exceeds the daily agent budget of $10.00",
        "remainingBudget": "$2.13"
      }
    }
  }
}

Next steps

Read the full Submitting Intents reference for all request fields and error handling
Using an AI agent framework? Connect via MCP - capabilities are exposed as self-describing tools that any MCP-compatible agent can discover and call without hardcoded schemas
Learn how Agent Authentication works - including federated identity from enterprise IdPs for fleet deployments
Learn how Policy & Governance works to configure your rules and apply templates
Explore Capability Discovery to understand all available integrations
Set up Observability & Audit to query your intent history

←

Capability Catalog & Definition Packs

Agent Authentication

→