> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Orchestration

> Multi-agent workflow execution with cost tracking, safety guardrails, and cryptographic audit trails.

# AI Orchestration

Truthlocks AI Orchestration enables you to define, execute, and monitor multi-agent workflows with built-in cost attribution, safety guardrails, and complete audit trails.

## Overview

```
┌─────────────────────────────────────────────────────────────┐
│                    Orchestration Engine                       │
│                                                               │
│  Workflow Definition → Step Execution → Result Aggregation   │
│         │                    │                    │           │
│         ▼                    ▼                    ▼           │
│   ┌──────────┐     ┌──────────────┐     ┌──────────────┐    │
│   │ Guardrail│     │  Agent Pool  │     │  Cost Tracker │    │
│   │  Engine  │     │              │     │              │    │
│   └──────────┘     │ Agent A      │     │ $0.12 total  │    │
│                    │ Agent B      │     │ 847 tokens   │    │
│                    │ Agent C      │     └──────────────┘    │
│                    └──────────────┘                          │
└─────────────────────────────────────────────────────────────┘
```

<Tip>
  All orchestration and workflow endpoints have an interactive API playground. Open any endpoint in the [Orchestrations & Workflows](/api-reference/machine-identity/orchestrations/execute) API reference and click **Send** to try it against the Sandbox.
</Tip>

## Quick start

### Execute an orchestration

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/orchestrate/execute \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "name": "quarterly-compliance-review",
    "agents": ["maip-agent:01JAAAA", "maip-agent:01JBBBB"],
    "steps": [
      {
        "name": "gather-evidence",
        "agent_id": "maip-agent:01JAAAA",
        "action": "compliance.gather",
        "input": { "scope": "soc2", "period": "Q1-2026" }
      },
      {
        "name": "evaluate-controls",
        "agent_id": "maip-agent:01JBBBB",
        "action": "compliance.evaluate",
        "depends_on": ["gather-evidence"],
        "input": { "framework": "soc2-type2" }
      }
    ],
    "guardrails": {
      "max_cost_usd": 5.00,
      "max_duration_seconds": 300,
      "require_trust_score_above": 70
    }
  }'
```

**Response:**

```json theme={null}
{
  "id": "maip-orch:01JOOOO",
  "status": "running",
  "steps": [
    { "name": "gather-evidence", "status": "running" },
    { "name": "evaluate-controls", "status": "pending" }
  ],
  "started_at": "2026-04-06T14:00:00Z"
}
```

### Check Orchestration Status

```bash theme={null}
curl https://api.truthlocks.com/v1/orchestrate/executions/maip-orch:01JOOOO \
  -H "X-API-Key: $API_KEY"
```

```json theme={null}
{
  "id": "maip-orch:01JOOOO",
  "status": "completed",
  "steps": [
    { "name": "gather-evidence", "status": "completed", "duration_ms": 12400 },
    { "name": "evaluate-controls", "status": "completed", "duration_ms": 8200 }
  ],
  "cost": {
    "total_usd": 1.24,
    "breakdown": [
      { "step": "gather-evidence", "usd": 0.87, "tokens": 12400 },
      { "step": "evaluate-controls", "usd": 0.37, "tokens": 5200 }
    ]
  },
  "completed_at": "2026-04-06T14:00:21Z"
}
```

## LLM Inference Logging

Track every LLM call made during orchestration:

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/orchestrate/llm/inference \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "model": "claude-sonnet-4-6-20250514",
    "provider": "anthropic",
    "input_tokens": 1200,
    "output_tokens": 450,
    "latency_ms": 2400,
    "cost_usd": 0.012,
    "step_name": "evaluate-controls"
  }'
```

## Workflows

For recurring orchestration patterns, define reusable workflows:

### Create a Workflow

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/orchestrate/workflows \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "name": "weekly-risk-assessment",
    "description": "Automated weekly risk assessment across all vendors",
    "steps": [
      {
        "name": "scan-vendors",
        "action": "risk.scan",
        "input_template": { "vendor_list": "{{vendors}}" }
      },
      {
        "name": "score-risks",
        "action": "risk.score",
        "depends_on": ["scan-vendors"]
      },
      {
        "name": "generate-report",
        "action": "report.generate",
        "depends_on": ["score-risks"],
        "input_template": { "format": "pdf", "recipients": "{{team_email}}" }
      }
    ],
    "schedule": "0 9 * * MON",
    "guardrails": {
      "max_cost_usd": 10.00,
      "max_duration_seconds": 600
    }
  }'
```

### Execute a Workflow

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/orchestrate/workflows/maip-workflow:01JWWWW/execute \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "variables": {
      "vendors": ["vendor_a", "vendor_b", "vendor_c"],
      "team_email": "risk-team@corp.com"
    }
  }'
```

## Guardrails

| Guardrail                   | Description                                         |
| --------------------------- | --------------------------------------------------- |
| `max_cost_usd`              | Hard cost ceiling — orchestration halts if exceeded |
| `max_duration_seconds`      | Maximum wall-clock time                             |
| `max_tokens`                | Total token budget across all LLM calls             |
| `require_trust_score_above` | Minimum agent trust score to participate            |
| `require_human_approval`    | Steps that need human sign-off before proceeding    |
| `allowed_models`            | Whitelist of permitted LLM models                   |
| `blocked_actions`           | Actions that are explicitly forbidden               |

### Guardrail Check

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/guardrails/check \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "agent_id": "maip-agent:01JAAAA",
    "action": "orchestrations:execute",
    "context": {
      "estimated_cost_usd": 3.50,
      "models": ["claude-sonnet-4-6-20250514"],
      "duration_estimate_seconds": 120
    }
  }'
```

```json theme={null}
{
  "allowed": true,
  "checks": [
    { "rule": "max_cost_usd", "status": "pass", "limit": 5.00, "actual": 3.50 },
    { "rule": "allowed_models", "status": "pass" },
    { "rule": "trust_score", "status": "pass", "score": 87, "minimum": 70 }
  ]
}
```

## Cost Attribution

All costs are attributed at multiple levels:

* **Per-step**: Each step tracks its own token usage and cost
* **Per-agent**: Aggregate cost across all steps an agent participated in
* **Per-orchestration**: Total cost for the entire workflow execution
* **Per-tenant**: Monthly rollup for billing purposes

Cost data feeds into the billing system and is visible in the console dashboard.

## Billing & Quotas

| Metric                | Developer | Business | Enterprise |
| --------------------- | --------- | -------- | ---------- |
| Orchestrations/mo     | 10        | 1,000    | Unlimited  |
| Workflow definitions  | 2         | 50       | Unlimited  |
| LLM inference logs/mo | 100       | 10,000   | Unlimited  |

## Next steps

<CardGroup cols={2}>
  <Card title="Machine identity" href="/guides/machine-identity" icon="fingerprint">
    Full MAIP protocol overview and quick start.
  </Card>

  <Card title="Trust scores" href="/guides/trust-scores" icon="chart-line">
    Continuous behavioral trust evaluation for agents.
  </Card>

  <Card title="Event streaming" href="/guides/maip-integrations#event-streaming" icon="bolt">
    Generate receipts for messages flowing through Kafka, EventBridge, Kinesis, NATS, and Redis Streams.
  </Card>

  <Card title="AI model connectors" href="/guides/maip-integrations#ai-model-connectors" icon="microchip">
    Automatic receipts for LangChain, LlamaIndex, CrewAI, and other AI framework calls.
  </Card>
</CardGroup>