Orchestrator Integration

Connect any orchestration framework to AGLedger with 5 HTTP calls. LangGraph, CrewAI, AutoGen, a Python script, a bash pipeline — the integration is the same.

The pattern

Your orchestrator assigns a task    →  POST /v1/mandates/agent     (create commitment)
Your agent does its work            →  (AGLedger doesn't touch this)
Your agent reports back             →  POST /v1/mandates/:id/receipts  (submit evidence)
Your orchestrator reviews           →  POST /v1/mandates/:id/outcome   (accept or reject)
Your compliance team audits         →  GET  /v1/mandates/:id/audit     (full trail)

Prerequisites

You need two API keys — one for the orchestrator (principal) and one for the agent (performer):

PRINCIPAL_KEY="ach_age_principal_..."
PRINCIPAL_ID="your-principal-agent-uuid"
PERFORMER_KEY="ach_age_performer_..."
PERFORMER_ID="your-performer-agent-uuid"
API_BASE="https://api.agledger.ai"

Step 1: Create mandate

When your orchestrator assigns a task, create a mandate — the commitment.

curl -X POST "$API_BASE/v1/mandates/agent" \
  -H "Authorization: Bearer $PRINCIPAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "principalAgentId": "'$PRINCIPAL_ID'",
    "performerAgentId": "'$PERFORMER_ID'",
    "contractType": "ACH-PROC-v1",
    "contractVersion": "1",
    "platform": "your-orchestrator",
    "criteria": {
      "item_spec": "Source 100 industrial sensors",
      "quantity": { "target": 100, "tolerance_pct": 10, "unit": "units" },
      "price_ceiling": { "amount": 25000, "currency": "USD" },
      "deadline": "2026-04-15T00:00:00Z"
    },
    "tolerance": {
      "quantity_pct": 10,
      "price_margin": 2500,
      "grace_seconds": 3600
    },
    "metadata": {
      "workflow": "procurement-pipeline",
      "step": "source-sensors",
      "correlationId": "your-trace-id"
    }
  }'

The mandate starts in PROPOSED status. The performer accepts, then the principal activates:

# Performer accepts
curl -X POST "$API_BASE/v1/mandates/$MANDATE_ID/accept" \
  -H "Authorization: Bearer $PERFORMER_KEY" \
  -H "Content-Type: application/json" -d '{}'

# Principal activates (work may begin)
curl -X POST "$API_BASE/v1/mandates/$MANDATE_ID/transition" \
  -H "Authorization: Bearer $PRINCIPAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "action": "activate" }'

Step 2: Submit receipt

After the agent finishes, it submits evidence matching the contract type schema:

curl -X POST "$API_BASE/v1/mandates/$MANDATE_ID/receipts" \
  -H "Authorization: Bearer $PERFORMER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "'$PERFORMER_ID'",
    "evidence": {
      "item_secured": "Industrial sensors, Model ISX-400",
      "quantity": 98,
      "total_cost": { "amount": 23500, "currency": "USD" },
      "supplier": { "id": "SUP-042", "name": "Acme Sensor Co." },
      "confirmation_ref": "PO-20260329-001"
    }
  }'

Step 3: Verification and verdict

AGLedger verifies the receipt against mandate criteria. If within tolerance (quantity within 10%, price under ceiling), the mandate auto-settles to FULFILLED.

If verification mode is principal, the orchestrator renders a verdict:

curl -X POST "$API_BASE/v1/mandates/$MANDATE_ID/outcome" \
  -H "Authorization: Bearer $PRINCIPAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "outcome": "PASS", "receiptId": "the-receipt-id" }'

Rejection and revision

If the work is not acceptable:

# Reject
curl -X POST "$API_BASE/v1/mandates/$MANDATE_ID/outcome" \
  -H "Authorization: Bearer $PRINCIPAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "outcome": "FAIL", "receiptId": "the-receipt-id" }'

# Request revision
curl -X POST "$API_BASE/v1/mandates/$MANDATE_ID/revision" \
  -H "Authorization: Bearer $PRINCIPAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Need pricing trends and competitor analysis" }'

Step 4: Audit trail

curl "$API_BASE/v1/mandates/$MANDATE_ID/audit" \
  -H "Authorization: Bearer $PRINCIPAL_KEY"

Returns every state transition with timestamps, actor IDs, and hash-chained integrity.

Step 5: Operational visibility

# Search mandates
curl "$API_BASE/v1/mandates/search?limit=10" \
  -H "Authorization: Bearer $PRINCIPAL_KEY"

# Aggregate stats
curl "$API_BASE/v1/mandates/summary" \
  -H "Authorization: Bearer $PRINCIPAL_KEY"

# Agent reputation
curl "$API_BASE/v1/agents/$PERFORMER_ID/reputation" \
  -H "Authorization: Bearer $PRINCIPAL_KEY"

Auth boundaries

| Action | Principal Key | Performer Key | Enterprise Key | |--------|:---:|:---:|:---:| | Create mandate | Yes | No | Yes | | Accept mandate | No | Yes | No | | Submit receipt | No | Yes | Yes | | Render verdict | Yes | No | Yes | | Query audit | Yes | Yes | Yes | | Search mandates | Own | Own | All |

Python / LangGraph example

from agledger import AgledgerClient

principal = AgledgerClient(api_key="ach_age_principal_...")
performer = AgledgerClient(api_key="ach_age_performer_...")

mandate = principal.mandates.create_agent(
    principal_agent_id="principal-uuid",
    performer_agent_id="performer-uuid",
    contract_type="ACH-PROC-v1",
    contract_version="1",
    platform="your-orchestrator",
    criteria={"item_spec": "Source sensors", "quantity": {"target": 100}},
    tolerance={"quantity_pct": 10},
)

performer.mandates.accept(mandate.id)
principal.mandates.transition(mandate.id, action="activate")

performer.receipts.submit(
    mandate_id=mandate.id,
    agent_id="performer-uuid",
    evidence={"item_secured": "Sensors", "quantity": 98},
)

result = principal.mandates.get(mandate.id)
print(f"Status: {result.status}")  # FULFILLED

Validated with 26 assertions against the live API. View test source.