Human-in-the-Loop Approvals

Request human review directly from your Python agent workflows with automatic trace linkage.

The Infralo Python SDK provides built-in support for initiating Human-in-the-Loop Approvals. Approvals pause sensitive agent operations until an authorized human reviewer acts on the request in the Infralo dashboard.

Overview

When an agent needs human authorization (e.g. before sending a message, placing a order, or deleting a record), it calls the SDK approval function:

infralo.create_approval(...) (Synchronous)
infralo.acreate_approval(...) (Asynchronous)

The SDK creates the request on the Infralo Platform using direct HTTP requests and returns the created approval object payload (including approval_id and status).

Automatic Trace Binding

When called inside an active trace context (with infralo.start_trace() or an @tool decorated function), the SDK automatically detects the active trace via ContextVar and binds trace_id to the approval request.

with infralo.start_trace(session_id="user-456") as trace:
    # trace_id is automatically attached — no need to pass trace_id manually!
    approval = infralo.create_approval(
        title="Approve Refund of $500",
        callback_url="https://api.myapp.com/webhooks/approval",
    )

You do not need to manually pass trace_id when calling inside a trace block!

Asynchronous Usage (`acreate_approval`)

In async applications (e.g. FastAPI, asyncio agents), use infralo.acreate_approval:

from infralo import Infralo

infralo = Infralo(api_key="vk_your_workspace_api_key")

async def process_transaction(amount: float, recipient: str):
    approval = await infralo.acreate_approval(
        title=f"Transfer ${amount} to {recipient}",
        description="High-value transfer requires manager approval.",
        review_data={
            "amount": amount,
            "recipient": recipient,
            "currency": "USD",
        },
        callback_url="https://agent.example.com/webhooks/approval-result",
        callback_headers={
            "x-webhook-secret": "sec_991823719"
        },
        client_reference_id="tx_run_9941",
    )

    print(f"Created approval ID: {approval['approval_id']}")
    print(f"Status: {approval['status']}")  # "pending"

Synchronous Usage (`create_approval`)

In synchronous scripts or worker jobs, use infralo.create_approval:

from infralo import Infralo

infralo = Infralo(api_key="vk_your_workspace_api_key")

approval = infralo.create_approval(
    title="Publish Blog Post to CMS",
    description="Please review formatted markdown before publishing.",
    review_data={
        "title": "Quarterly Update",
        "slug": "quarterly-update-q3",
    },
    callback_url="https://cms.example.com/api/approvals/callback",
    client_reference_id="post_772",
)

Parameter Reference

Both infralo.create_approval and infralo.acreate_approval accept the following arguments:

Argument	Type	Required	Description
`title`	`str`	Yes	Short summary displayed to dashboard reviewers (1-500 chars).
`callback_url`	`str`	Yes	Webhook URL called by Infralo once the request is reviewed. Must be a valid http(s) URL.
`description`	`str`	No	Detailed context or instructions for reviewers.
`review_data`	`dict[str, Any]`	No	Arbitrary JSON payload required for the review decision.
`callback_headers`	`dict[str, str]`	No	Custom HTTP headers sent with the webhook (stored encrypted).
`client_reference_id`	`str`	No	Opaque client ID for workflow correlation (e.g. run ID).
`trace_id`	`str`	No	Associated trace ID. Auto-populated from active trace if omitted.
`timeout`	`float`	No	HTTP request timeout in seconds (default `15.0`).

Return Value

Returns a dict containing the approval object data returned by the Infralo platform:

{
  "approval_id": "3a1c2d4e-5f6a-7b8c-9d0e-1f2a3b4c5d6e",
  "workspace_id": "11111111-2222-3333-4444-555555555555",
  "title": "Approve Refund of $500",
  "description": null,
  "review_data": {},
  "callback_url": "https://api.myapp.com/webhooks/approval",
  "client_reference_id": null,
  "status": "pending",
  "comment": null,
  "reviewed_by": null,
  "reviewed_at": null,
  "callback_status": "pending",
  "callback_attempts": 0,
  "trace_id": "7f8b9a0c-1234-4567-89ab-cdef01234567",
  "created_at": "2026-07-21T18:00:00Z"
}