Skip to Content
AgentFlow
AI agents

AI agents

Integrate an AI agent with AgentFlow — submit approval requests, track human decisions, and verify signed receipts.

AgentFlow puts a verified human decision between an AI agent's intent and the action it wants to take. The agent submits an approval request, a human reviewer decides it in the TrustLoop app, and the agent receives a signed receipt that proves the outcome.

An AI agent submits a request to the AgentFlow API with an x-ai-agent-key. The request is routed to a human reviewer in the TrustLoop app, whose verified decision produces a signed receipt returned to the agent by webhook or polling.x-ai-agent-keysubmitRequestassignedverifiedAI agentyour serviceAgentFlow APIPOST /ai-agent/*Approval queuerouted by routingHuman reviewerTrustLoop appFinal decisionEd25519 receiptwebhook: approval.completed · polling: getStatus + getProof

The integration model

  1. Connect. An operator creates an AI agent connection in the console and gives you an access key. See Connections.
  2. Submit. POST /api/v1/ai-agent/submitRequest creates a request in pending state and routes it to a reviewer. Creating a request does not authorize the protected action. See Requests.
  3. Wait for a human. Poll getStatus, or receive the approval.completed webhook event.
  4. Verify the receipt. On a final approved outcome, fetch the Ed25519-signed proof with getProof and verify it before performing the protected action. See Receipts.

pending is not permission. Do not perform the protected action on request creation, assignment, or any non-final status. Authorization requires a final approved status and its signed receipt.

Delivery modes

Each agent connection has a delivery configuration that controls how results reach the agent. All modes report the same canonical API state; polling is always available as the baseline.

ModeHow it worksEnabled by
pollingAgent calls getStatus, honoring nextPollAfterMsAlways on
webhookSigned approval.completed event POSTed to the connection's callback URLWebhook delivery plus an HTTPS callback configured on the connection. See Webhooks

API shape

All agent calls are HTTP POSTs against the same base:

POST /api/v1/ai-agent/<procedure>
x-ai-agent-key: <agent access key>
Content-Type: application/json

{"json": { ... }}

Responses are {"json": { ... }} on success and a structured error object on failure. On the hosted platform the API is https://af-api.ivalt.com.

In this section

  • Connections — agent connections, the x-ai-agent-key header, getIdentity.
  • Requests — submitRequest, getStatus, getRequest.
  • Webhooks — delivery config, approval.completed events, signature verification, retries, delivery error codes.
  • Receipts — getProof, the signed receipt shape, Ed25519 verification.
  • API reference — generated schemas for every ai-agent procedure.

Errors

The error vocabulary returned by the agent API — codes, data payloads, idempotency rules, and retry guidance.

Connections

AI agent connections — how operators issue agent keys, authenticating with x-ai-agent-key, and reading the connection identity and delivery config.

On this page

The integration modelDelivery modesAPI shapeIn this section