Skip to content
Alquimia Platform Alquimia Platform Alquimia Platform

Human-in-the-loop approvals

Autonomous agents are powerful, but not every action should run without oversight. Alquimia Platform’s human-in-the-loop support lets you pause execution, request approval, and resume only after a human makes an explicit decision.

What the use case looks like

Section titled “What the use case looks like”

An agent determines that a customer is eligible for a large refund. Before processing it, the agent:

  1. Suspends the tool execution.
  2. Sends an approval request to the customer’s assigned manager on WhatsApp.
  3. Waits for the manager’s reply.
  4. Resumes execution with the approval decision and completes or cancels the refund.

The entire exchange — request, wait, decision, resume — is captured in the worklog.

Approval is policy-driven, not a global switch

Section titled “Approval is policy-driven, not a global switch”

Approvals are configured per tool operation in the registry, combined with the agent’s role tier. A destructive operation always requires approval. A mutating operation can require approval for some roles but not others.

Terminal window
alquimia registry tools add finance-tools \
  --provider-id mcp \
  --connection-config '{"url": {"$secretRef": "FINANCE_MCP_URL"}}'


# Refunds are mutating but we want a human in the loop
alquimia registry tools set-operation finance-tools process_refund \
  --severity mutating-recoverable \
  --tier-grants editor,operator \
  --approval-required


# Account closure is destructive and always requires approval
alquimia registry tools set-operation finance-tools close_account \
  --severity destructive \
  --tier-grants operator

The agent spec declares an operator ceiling and references the tool by ID:

{
  "assistant_id": "refunds-agent",
  "role": "operator",
  "response": {
    "provider_id": "alquimia",
    "profile": {
      "system_prompt": "You assist with refund requests. Only process refunds after human approval.",
      "tools": [
        {
          "provider_id": "mcp",
          "tool_ref": "finance-tools",
          "human_approval": "NONE"
        }
      ],
      "evaluation_strategy": {
        "evaluation_strategy_id": "native",
        "max_steps": 10
      }
    },
    "config": {
      "provider_id": "openai",
      "params": {
        "model": "gpt-4o-mini",
        "temperature": 0.1,
        "api_key": {"$secretRef": "RESPONSE_PROVIDER_API_KEY"}
      }
    }
  }
}

Even though human_approval is NONE in the spec, the registry policy forces approval for process_refund and always forces approval for the destructive close_account operation.

Shields guard the approval boundary

Section titled “Shields guard the approval boundary”

Before asking for approval, a shield can detect anomalies — for example, a refund amount above a threshold or a suspicious pattern in the request.

{
  "shields": {
    "refund-risk": {
      "provider_id": "shield-config",
      "connector": {
        "provider_id": "alquimia",
        "profile": {
          "system_prompt": "Evaluate the refund request. Output JSON: {\"risk\": \"low\"|\"medium\"|\"high\", \"reason\": \"...\"}",
          "evaluation_strategy": {
            "evaluation_strategy_id": "one-shoot",
            "structured_output": {
              "method": "json_schema",
              "json_schema": {
                "type": "object",
                "properties": {
                  "risk": {"type": "string", "enum": ["low", "medium", "high"]},
                  "reason": {"type": "string"}
                },
                "required": ["risk", "reason"]
              }
            }
          }
        },
        "config": {"model_ref": "gpt-4o-mini-classifier"}
      },
      "action": "observe"
    }
  },
  "empathy": {
    "rules": [
      {
        "rule_id": "high-risk-refund",
        "strategy": "override",
        "requirements": ["refund-risk"],
        "conditions": ["refund-risk.get('risk') == 'high'"],
        "response": {
          "provider_id": "fixed",
          "message": "This refund was flagged as high risk and requires manual review before approval."
        }
      }
    ]
  }
}

Channel-native approvals

Section titled “Channel-native approvals”

Approval requests are delivered over the same channel the user already uses. A manager can approve a refund with a reply on WhatsApp, Slack, or Email, and the runtime routes the decision back to the waiting task through POST /event/tool-approval.

For application teams

Section titled “For application teams”

Channel-native approvals

Approval requests can be delivered over WhatsApp, Slack, Email, or custom channels, meeting users where they work.

Tool-scoped gates

Configure approvals per tool or per tool category, not as a global switch.

Timeout handling

Define how long to wait for a human and what the default action should be when time expires.

For platform / SRE teams

Section titled “For platform / SRE teams”

Non-blocking design

Pending approvals do not tie up worker threads; tasks wait in the state store and resume on the next event.

Audit decisions

Every approval request and response is recorded with the approver identity, timestamp, and channel.

Fraud resistance

Approval messages are routed back through the original authenticated channel, reducing the risk of intercepted or spoofed approvals.

When to use approvals

Section titled “When to use approvals”
ActionApproval pattern
Financial transactions above a thresholdManager approval via WhatsApp or Email
Access grants or privilege escalationSecurity team approval via Slack
Data exports containing PIIData owner approval via ticket comment
Irreversible infrastructure changesOn-call engineer approval via page response

Example outcomes

Section titled “Example outcomes”
  • Faster straight-through processing for routine actions.
  • Built-in controls for regulated or high-risk operations.
  • Clear accountability for decisions made by or with agents.
Section titled “Related pages”