DEV Community: sekera-radim

Add Human Approval to a Cron Job

sekera-radim — Sun, 02 Aug 2026 10:50:02 +0000

Add human approval to a cron job so the schedule fires but the side effect waits for your go-ahead — with a working Python example and expiry window guidance.

Why scheduled jobs are a blind spot

Cron jobs run without anyone watching. A weekly newsletter goes out even if the draft has a typo. A nightly database purge fires even if someone is in the middle of a migration. A deploy job kicks off at 3 AM regardless of whether there is an active incident.

The instinct is to add an environment flag or a config toggle to pause them. That works, but it requires you to remember to flip the flag before the window opens — and a toggle you forgot is the same as no toggle at all.

A better pattern: the schedule fires on time, but the job proposes its action to you and cannot proceed until you approve. The cron script does its preparation work, then blocks on your decision, then either executes or exits cleanly.

How the pattern works

cron fires
    │
    ├── job prepares the payload (draft newsletter, purge SQL, deploy config)
    │
    ├── POST /v1/actions  →  Impri stores it, notifies you on phone/Slack/email
    │
    ├── job polls GET /v1/actions/:id  (blocks until decided or expired)
    │
    ├─[approved]─ executes with final_preview content
    │
    └─[rejected/expired]─ exits without side effect, logs reason

The cron tab entry stays unchanged. What changes is that the script itself will not fire its side effect until a human decision comes back.

Example: weekly newsletter send (Python)

This script runs via cron every Monday morning. It drafts the newsletter, pushes it to Impri for approval, then either sends or exits cleanly.

#!/usr/bin/env python3
"""weekly-newsletter.py — push draft for approval, then send on go-ahead."""

import os
import time
import requests

API_BASE = "https://api.impri.dev"
HEADERS = {
    "Authorization": f"Bearer {os.environ['IMPRI_API_KEY']}",
    "Content-Type": "application/json",
}

def draft_newsletter() -> str:
    # Your existing newsletter generation logic here
    return "**This week in AI tools** — five picks from the past 7 days..."

def send_newsletter(body: str) -> None:
    # Your existing send logic (MailerLite, Postmark, etc.)
    print(f"Sending newsletter ({len(body)} chars)")

def main():
    body = draft_newsletter()

    # Push the action — give 12 hours to approve before the window closes
    resp = requests.post(f"{API_BASE}/v1/actions", headers=HEADERS, json={
        "kind": "newsletter.send",
        "title": "Weekly newsletter — 14 Jul 2026",
        "preview": {"format": "markdown", "body": body},
        "expires_in": 43200,          # 12 hours
        "editable": ["preview.body"], # allow last-minute edits before approving
    })
    resp.raise_for_status()
    action = resp.json()
    action_id = action["id"]
    print(f"Pushed: {action_id}  inbox: {action['inbox_url']}")

    # Poll until decided or expired
    while True:
        result = requests.get(f"{API_BASE}/v1/actions/{action_id}", headers=HEADERS)
        result.raise_for_status()
        data = result.json()
        status = data["status"]
        if status != "pending":
            break
        time.sleep(30)  # check every 30 seconds

    if status == "approved":
        # Always use final_preview — it carries human edits when editable fields were changed
        final_body = data["decision"]["final_preview"]["body"]
        send_newsletter(final_body)

        requests.post(
            f"{API_BASE}/v1/actions/{action_id}/result",
            headers=HEADERS,
            json={"status": "executed"},
        )
        print("Newsletter sent and result reported.")
    else:
        print(f"Newsletter not sent: action {status}. Exiting cleanly.")

if __name__ == "__main__":
    main()

Wire it into your crontab:

0 7 * * 1  IMPRI_API_KEY=im_... /usr/local/bin/python3 /opt/jobs/weekly-newsletter.py

Choosing the right expiry window

expires_in is the window within which you must approve. After it passes, the action cannot be approved and the script exits cleanly.

Job type	Suggested `expires_in`	Reasoning
Newsletter send	3–12 hours	Wide review window; content goes stale after a few days
Database purge	1–4 hours	Narrow window — if you miss it, wait for the next run checkpoint
Deployment	900 s (15 min)	Tight window forces attention; stale deploys are risky
Report generation	86400 s (24 h)	Reporting is low-risk and can wait a full day

The default is 72 hours. For most scheduled jobs, something shorter is safer: it forces the decision to happen while the data is still fresh and stops an old action from being accidentally approved days later.

What rejection and expiry mean

When status is rejected or expired, the script exits without the side effect. Nothing is sent, deleted, or deployed.

Rejection is explicit: someone reviewed the draft and declined. Expiry is implicit: no one responded within the window. Both are safe exits. You can treat them identically in your error handling or distinguish them if you want different alerting behavior:

elif status == "rejected":
    print("Rejected by reviewer. Exiting.")
elif status == "expired":
    print("No response within window. Scheduled for next cycle.")

Expiry is not a failure — it is a correctness feature. A draft newsletter from three days ago is probably not worth sending. Setting a short window and letting it expire is a valid workflow.

Handling human edits

When you set editable: ["preview.body"], the reviewer can modify the draft before approving. The polling response then carries:

decision.final_preview.body — the version the human approved (use this, not the original)
decision.diff — a unified diff of what changed (present only when something was actually modified)

Always execute with final_preview.body. This is how one-click corrections work: the reviewer fixes a typo or updates a link directly in the inbox card, approves, and the corrected version goes out automatically.

Next steps

Quickstart — get an API key and push your first test action in under five minutes
Notifications — configure email, Slack, or Telegram so you are alerted the moment a cron job pushes an action
Audit log — review a history of what ran, what was approved, what was rejected, and when

Human Approval Before an Agent Sends SMS

sekera-radim — Sun, 02 Aug 2026 07:10:02 +0000

An AI agent that can text customers can also text the wrong customer, at 2am, with a broken merge field — add a human approval gate before any SMS goes out and you catch that before it's sent, not after.

Why SMS needs its own gate

Email has a delete-before-read grace period. SMS doesn't. It lands on a phone, in a notification, usually within seconds — there is no draft folder, no "recall message," and no spam filter quietly eating the mistake. If your agent drafts appointment reminders, shipping updates, or re-engagement texts, a bad run (wrong phone number pulled from a stale record, a broken template variable rendering as {{first_name}}, a message meant for internal QA going to a real customer) becomes a customer-facing incident immediately.

Twilio, Vonage, and similar providers will happily send whatever string you hand them — they don't know if the content makes sense. That check has to happen before the API call, and it has to be a human, not another prompt asking the model to "double-check itself."

The gate in practice

Say you run a scheduling agent for a dental clinic. It reads tomorrow's appointment list, drafts a reminder text per patient, and used to call the Twilio API directly. Now it pushes each draft to Impri first and only sends after a receptionist approves it:

import os
import time
import requests

IMPRI_KEY = os.environ["IMPRI_API_KEY"]
BASE = "https://api.impri.dev"
HEADERS = {"Authorization": f"Bearer {IMPRI_KEY}", "Content-Type": "application/json"}

def push_sms_for_approval(to_number, body):
    resp = requests.post(f"{BASE}/v1/actions", headers=HEADERS, json={
        "kind": "sms.send",
        "title": f"Reminder SMS to {to_number}",
        "preview": {"format": "plain", "body": body},
        "expires_in": 3600,          # stale reminder isn't worth sending after an hour
        "editable": ["preview.body"],
        "idempotent": False,         # resending would double-text the patient
    })
    resp.raise_for_status()
    return resp.json()["id"]

def wait_for_decision(action_id, poll_every=5):
    while True:
        resp = requests.get(f"{BASE}/v1/actions/{action_id}", headers=HEADERS)
        data = resp.json()
        if data["status"] != "pending":
            return data
        time.sleep(poll_every)

action_id = push_sms_for_approval("+15551234567", "Hi Sam, reminder: your cleaning is tomorrow at 2pm.")
decision = wait_for_decision(action_id)

if decision["status"] == "approved":
    final_body = decision["decision"]["final_preview"]["body"]
    # send via Twilio only after approval
    twilio_client.messages.create(to="+15551234567", from_=CLINIC_NUMBER, body=final_body)
    requests.post(f"{BASE}/v1/actions/{action_id}/result", headers=HEADERS,
                  json={"status": "executed"})

The Twilio call is inside the if approved branch and nowhere else in the codebase — that's what makes this a real gate rather than a formality. If the agent (or a bug, or a prompt-injected instruction from some upstream data source) tries to skip straight to twilio_client.messages.create(...), it still needs the API key and the wrapper, and neither one is reachable outside that branch.

What the receptionist sees, and why editable matters

Setting editable: ["preview.body"] means the approval card in the inbox isn't just an approve/reject button — the receptionist can fix a typo, adjust the tone, or correct a name before sending, and Impri returns that edited text as decision.final_preview.body. Always send that field, never the original preview.body; if a human touched the message, the original is not what should go out.

This matters more for SMS than most channels because there's no second chance to clarify. An email with an awkward phrase gets a follow-up. A text that says "your appointment is cancelled" instead of "your appointment is confirmed" because of one autocorrected word gets a phone call from a confused patient.

Rate limits and batch runs

If your agent processes a full day's appointment list in one run, it might push 40-50 actions in a burst. POST /v1/actions is capped at 60 requests per minute per key, which comfortably covers a clinic's daily volume — but if you're running this for a larger operation (a pharmacy chain, a multi-location practice), stagger the pushes or use separate keys per location rather than hammering one key past the limit.

Boundaries

Impri stores the drafted message, notifies the reviewer, and holds the decision — it does not read the message content, does not know what "sounds right" for your clinic's tone, and does not talk to Twilio on your behalf. Your agent still owns sending the SMS; Impri owns making sure a human said yes first. For the two other integration paths (MCP tool calls instead of raw HTTP, and wiring the executor so the credential genuinely can't be reached without an approval) see the main integration guide.

If you want the reviewer to approve straight from Slack instead of the web inbox, see Slack approval. New to Impri? Start with the quickstart.

Approve Refunds Issued by an AI Support Agent

sekera-radim — Sat, 01 Aug 2026 18:10:03 +0000

Give a support agent the power to resolve tickets by issuing refunds and you've also given it the power to drain your Stripe balance on a bad day — gate every refund behind human approval and the agent can still resolve the ticket fast, just not unsupervised.

Why refunds are a different risk class than replies

Most AI support agent mistakes are annoying: a wrong tone, a repeated answer, a missed nuance. A refund mistake is a wire transfer. If the agent misreads a policy ("full refund for any complaint within 30 days"), gets talked into it by a customer who knows the trigger phrases, or simply hallucinates an order total, the money moves. Stripe doesn't ask the agent if it's sure — refunds.create executes on the API call, not on the intent behind it.

This is also the failure mode most likely to compound: a support agent processing a queue of 200 tickets doesn't make one mistake, it makes the same mistake 200 times if the bad reasoning is systemic (e.g., a misconfigured refund policy in its prompt). A human checkpoint before the Stripe call catches that on ticket one instead of ticket two hundred.

Wiring the gate into the refund path

The agent's refund tool should never call Stripe directly — it should call a wrapper that pushes the proposal to Impri and only calls Stripe once approved:

import Stripe from "stripe";

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
const IMPRI_KEY = process.env.IMPRI_API_KEY!;
const BASE = "https://api.impri.dev";

interface RefundProposal {
  chargeId: string;
  amountCents: number;
  customerEmail: string;
  reason: string;
}

async function proposeRefund(p: RefundProposal): Promise<string> {
  const res = await fetch(`${BASE}/v1/actions`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${IMPRI_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      kind: "payment.refund",
      title: "`Refund $${(p.amountCents / 100).toFixed(2)} — ${p.customerEmail}`,"
      preview: {
        format: "markdown",
        body: `**Charge:** ${p.chargeId}\n**Amount:** $${(p.amountCents / 100).toFixed(2)}\n**Reason given by agent:** ${p.reason}`,
      },
      expires_in: 43200, // 12h — support tickets shouldn't sit longer than that
      idempotent: false,
      undo: "No automatic undo — a reversed refund requires a new manual charge",
    }),
  });
  const { id } = await res.json();
  return id;
}

async function waitForDecision(actionId: string) {
  while (true) {
    const res = await fetch(`${BASE}/v1/actions/${actionId}`, {
      headers: { Authorization: `Bearer ${IMPRI_KEY}` },
    });
    const data = await res.json();
    if (data.status !== "pending") return data;
    await new Promise((r) => setTimeout(r, 5000));
  }
}

async function refundWithApproval(p: RefundProposal) {
  const actionId = await proposeRefund(p);
  const decision = await waitForDecision(actionId);

  if (decision.status !== "approved") {
    return { executed: false, status: decision.status };
  }

  const refund = await stripe.refunds.create({ charge: p.chargeId, amount: p.amountCents });

  await fetch(`${BASE}/v1/actions/${actionId}/result`, {
    method: "POST",
    headers: { Authorization: `Bearer ${IMPRI_KEY}`, "Content-Type": "application/json" },
    body: JSON.stringify({ status: "executed", payload: { refundId: refund.id } }),
  });

  return { executed: true, refundId: refund.id };
}

The stripe.refunds.create call sits behind the decision.status !== "approved" early return — that's the whole point. The agent's ticket-resolution logic can decide a refund is warranted, draft the reasoning, and call refundWithApproval, but the actual money movement is one if away from a human decision, not from the agent's own judgment.

What the reviewer sees, and how it maps to risk

The preview.body above deliberately surfaces the charge ID, the dollar amount, and the agent's stated reasoning — a reviewer approving refunds from a phone needs those three facts and nothing else to make a fast, correct call. undo is set because refunds genuinely have none through this API; the reviewer should know that before tapping approve, not find out after.

Refund path	Recommended handling
Under a set threshold (e.g. $20), clear policy match	Still gate it — small refunds add up across a queue
Above threshold, or ambiguous policy match	Gate it, and consider routing to a senior reviewer via a separate key/inbox
Duplicate charge, customer-verified error	Gate it — `idempotent: false` warns the reviewer a retry would double-refund
Chargeback already filed	Don't refund via the agent at all — that's a payments-team process, not a support ticket

Result payload and audit trail

Reporting result with payload: { refundId: refund.id } means the Stripe refund ID is attached to the approval record — when finance asks "who approved this and why," the answer is in one place instead of split across Stripe's dashboard and your support tool's logs. See audit log for how these records are retained and queried.

Boundaries

Impri does not know your refund policy and does not evaluate whether $340 is reasonable for this ticket — it shows the reviewer what the agent proposed and holds the yes/no. The agent still owns the reasoning; the reviewer still owns the judgment call; Impri owns making sure the Stripe call can't happen without both. For the full three-call pattern (REST and MCP) and how to make the wrapper an actual chokepoint rather than a suggestion, see the main integration guide. If your team wants a Slack-based approve/reject flow instead of the web inbox, see approving agent actions from Slack.

New to Impri? Start with the quickstart.

Human Approval Before an AI Agent Deploys Code

sekera-radim — Wed, 29 Jul 2026 14:50:02 +0000

Add human approval before an AI agent deploys code — gate the deploy call itself, review the diff and rollback plan, and stop a bad deploy before it ever ships.

Why "run the tests" isn't the same as "safe to ship"

Coding agents that open PRs, fix CI failures, and merge on green are common now. The next step — letting the same agent trigger the deploy once the merge lands — is where teams get nervous, for good reason. Green tests confirm the code does what the test suite checked for. They say nothing about whether this is the right week to ship a schema migration, whether the change touches a service currently mid-incident, or whether the agent's fix for a flaky test quietly widened a retry loop that will hammer a downstream API. A human glancing at the diff and the target environment for ten seconds catches things a test suite structurally cannot.

Bolting a "confirm before deploying" instruction into the agent's prompt doesn't hold up under the same failure mode every other ungated action has: it's a suggestion, not a gate, and an agent reasoning about a wall of CI logs can talk itself past a suggestion. What actually holds is making the deploy call itself unreachable until an external decision says so.

Gating the deploy call, not the merge

Push the deploy as an action before the pipeline step that actually ships it, then block on the decision. Here's the pattern in Go, for a service triggering a Kubernetes rollout:

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
    "os"
    "os/exec"
    "time"
)

const base = "https://api.impri.dev"

func pushDeploy(commitSHA, env, diffURL string, hasMigration bool) (string, error) {
    body, _ := json.Marshal(map[string]any{
        "kind":  "deploy.trigger",
        "title": fmt.Sprintf("Deploy %s to %s", commitSHA[:7], env),
        "preview": map[string]string{
            "format": "markdown",
            "body": fmt.Sprintf("**Environment:** %s\n**Commit:** `%s`\n**Includes migration:** %v\n\n[View diff](%s)",
                env, commitSHA, hasMigration, diffURL),
        },
        "idempotent": false,
        "undo":       fmt.Sprintf("kubectl rollout undo deployment/api -n %s", env),
        "expires_in": 1800,
        "target_url": diffURL,
    })
    req, _ := http.NewRequest("POST", base+"/v1/actions", bytes.NewReader(body))
    req.Header.Set("Authorization", "Bearer "+os.Getenv("IMPRI_API_KEY"))
    req.Header.Set("Content-Type", "application/json")
    res, err := http.DefaultClient.Do(req)
    if err != nil {
        return "", err
    }
    defer res.Body.Close()
    var out struct{ ID string `json:"id"` }
    json.NewDecoder(res.Body).Decode(&out)
    return out.ID, nil
}

func awaitAndDeploy(actionID, env string) error {
    for {
        req, _ := http.NewRequest("GET", base+"/v1/actions/"+actionID, nil)
        req.Header.Set("Authorization", "Bearer "+os.Getenv("IMPRI_API_KEY"))
        res, _ := http.DefaultClient.Do(req)
        var out struct{ Status string `json:"status"` }
        json.NewDecoder(res.Body).Decode(&out)
        res.Body.Close()

        if out.Status == "pending" {
            time.Sleep(10 * time.Second)
            continue
        }
        if out.Status != "approved" {
            return fmt.Errorf("deploy blocked: %s", out.Status)
        }
        return exec.Command("kubectl", "apply", "-f", "manifests/"+env).Run()
    }
}

Notice there's no editable field here. A social post or an email draft is text a reviewer can reasonably fix inline; a deploy plan isn't — you don't want a reviewer hand-editing which commit ships. The decision is binary: ship this exact diff to this exact environment, or don't.

What belongs on the approval card

A reviewer approving a deploy from a phone notification needs three things without clicking through: which environment, which commit, and whether there's a migration attached (migrations are the one class of deploy that can't be rolled back by redeploying the previous image). Everything else — full diff, test results, affected services — belongs behind the target_url link to your CI run, not crammed into the preview body.

Field	Purpose
`title`	One line: commit + environment, scannable in a push notification
`preview.body`	Environment, commit, migration flag — the three facts that change the decision
`target_url`	Link to the full CI run / PR diff for anyone who wants to dig deeper
`undo`	The exact rollback command, shown on the card so the reviewer knows the escape hatch exists before approving
`idempotent: false`	Re-running a deploy trigger isn't a safe retry — it's a second rollout

Staging versus production

Not every environment needs the same gate. A reasonable default:

Environment	Gate before deploy?
Preview / ephemeral branch envs	No — low blast radius, fast iteration matters more
Staging	Optional — gate if staging feeds a demo or QA signs off there
Production	Yes, always, especially with a schema migration attached

Rejected, expired, and rollback

rejected and expired both mean exec.Command never runs — same rule as any gated action. Set expires_in short enough that an approval can't sit stale past a deploy window; a production deploy approved two days late, after three more commits have merged on top, isn't the same deploy the reviewer looked at. If the code still needs to ship, push a fresh action against the current commit rather than resurrecting an old approval.

What Impri isn't doing here

Impri stores the deploy request, notifies a human, and holds the decision — it does not run kubectl apply itself, does not know whether your tests are trustworthy, and does not evaluate whether the diff is actually safe. That judgment stays with whoever's holding the phone. For the base three-call pattern this builds on, see how to add human approval to an AI agent; if the agent doing the merging runs on the Claude Agent SDK, see that integration guide for wiring the gate into the same process. Once you're gating deploys, the audit log gives you a record of every production rollout, who approved it, and when — useful the next time someone asks "who shipped this."

Next step: quickstart to get an API key and try this against a staging pipeline first.

Gate Database Writes From an AI Agent

sekera-radim — Wed, 29 Jul 2026 08:30:02 +0000

A text-to-SQL agent's query is a guess. Gate database writes from an AI agent — INSERT, UPDATE, DELETE — behind human approval before they touch production.

The shape of the problem

Text-to-SQL agents are useful precisely because they turn "mark these five overdue invoices as written off" into a working query without anyone hand-writing SQL. That's also what makes them dangerous: the query the model generates is a guess at intent, and a guess that's slightly too broad — a missing WHERE clause, a join that fans out rows, a LIKE pattern that matches more than intended — turns into a write that touches thousands of rows instead of five.

Read-only queries (SELECT) don't need this. Writes do. The dividing line for where to put the gate is simple:

Query type	Gate before executing?
`SELECT`	No — read access is not a side effect Impri needs to mediate
`INSERT` / `UPDATE`	Yes — the row didn't exist / didn't look like that before
`DELETE` / `TRUNCATE`	Yes, and treat as high-severity — see gating deletes specifically
`DDL` (`ALTER TABLE`, etc.)	Yes — schema changes are rarely something an agent should self-approve

Wiring the gate with the Impri MCP server

If the agent runs inside Claude Code, Claude Desktop, or another MCP client, the cleanest integration point is the query-execution tool itself — not the SQL-generation step. The model can draft as many candidate queries as it wants; only the executor is gated.

Add the Impri MCP server to the agent's config:

{
  "mcpServers": {
    "impri": {
      "command": "npx",
      "args": ["@impri/mcp"],
      "env": {
        "IMPRI_API_KEY": "im_your_key_here",
        "IMPRI_BASE_URL": "https://api.impri.dev"
      }
    }
  }
}

Then the agent's write-executor tool is described (in its own tool definition) as requiring an approved Impri action before it will run. The flow the agent follows, driven by MCP tool calls:

import { execute } from "./db";

interface WriteRequest {
  sql: string;
  params: unknown[];
  affectedTable: string;
  estimatedRowCount: number;
}

async function proposeWrite(req: WriteRequest): Promise<string> {
  // impri_push_action is called by the agent's MCP client, not by app code —
  // shown here as the equivalent REST call for clarity.
  const res = await fetch("https://api.impri.dev/v1/actions", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.IMPRI_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      kind: "db.write",
      title: `${req.sql.split(" ")[0]} on ${req.affectedTable} (~${req.estimatedRowCount} rows)`,
      preview: {
        format: "markdown",
        body: `\`\`\`sql\n${req.sql}\n\`\`\`\n\nParams: \`${JSON.stringify(req.params)}\`\n\nEstimated rows affected: **${req.estimatedRowCount}**`,
      },
      idempotent: req.sql.trim().toUpperCase().startsWith("INSERT") ? false : undefined,
      undo: "No automatic undo — write is applied directly to production.",
      expires_in: 1800,
    }),
  });
  const { id } = await res.json();
  return id;
}

async function awaitAndExecute(actionId: string, req: WriteRequest) {
  let status = "pending";
  let decision;
  while (status === "pending") {
    await new Promise((r) => setTimeout(r, 5000));
    const res = await fetch(`https://api.impri.dev/v1/actions/${actionId}`, {
      headers: { Authorization: `Bearer ${process.env.IMPRI_API_KEY}` },
    });
    ({ status, decision } = await res.json());
  }

  if (status !== "approved") {
    console.log(`Write blocked: ${status}`);
    return;
  }

  await execute(req.sql, req.params);

  await fetch(`https://api.impri.dev/v1/actions/${actionId}/result`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.IMPRI_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ status: "executed" }),
  });
}

estimatedRowCount is worth computing before pushing the action — run the WHERE clause as a SELECT COUNT(*) first. A reviewer approving "update 5 rows" and a reviewer approving "update rows matching this filter, count unknown" are making very different decisions; give them the number.

Why the SQL text belongs in the preview, not just a summary

It's tempting to summarize: title: "Update invoice statuses". Don't drop the raw SQL from the body. The whole value of gating a text-to-SQL agent is that the human reviewing the action can catch exactly the kind of subtle bug — wrong column, wrong comparison operator, unquoted string — that a paraphrased summary would hide. Show the query, the bound parameters separately (never interpolated into the SQL string), and the estimated row count. That's the minimum a reviewer needs to make the call in a few seconds instead of having to go dig through logs.

Scopes and keys

Use a key scoped to actions only for this flow — it doesn't need watch or admin. If the same service also runs Impri watchers for something unrelated, use a separate key for that; see API keys.

Rejected, expired, and retried writes

Same rule as any gated action: rejected and expired both mean the write does not happen, no exceptions. Don't have the agent silently retry a rejected write with a narrower WHERE clause — if the query needs revision, that's a new action with a new preview the reviewer sees, not a retry that reuses the old approval.

For the full three-call pattern this builds on, see how to add human approval to an AI agent. For wiring this specifically into a Claude-based agent, see the Claude Agent SDK guide. For the MCP server details, see MCP.

Require Human Approval Before an Agent Deletes Data

sekera-radim — Mon, 27 Jul 2026 09:10:02 +0000

Delete is the one action an agent can't undo by apologizing. Here's how to gate DELETE calls behind a human decision so a bad prompt never turns into a bad purge.

Why deletes need a different posture than sends or posts

Most human-in-the-loop guides use "send an email" as the example, because a bad email is embarrassing but recoverable — you can send a correction. A bad delete is not recoverable in the same way. If an agent runs a cleanup job, purges stale accounts, or removes rows a user asked it to "clean up," the failure mode isn't "oops, awkward" — it's "the data is gone and there's no undo button in the UI."

That changes what the approval card needs to show. For a delete, the reviewer isn't just checking tone or wording — they're checking scope: which rows, how many, and whether the filter is right. A WHERE last_login < '2020-01-01' clause that accidentally matches every row because of a bad NULL comparison is exactly the kind of thing a five-second human glance catches and an agent running unattended doesn't.

Wrapping the delete function

Say you have a support-ops agent with a tool that deletes inactive customer accounts. The unsafe version calls the database directly:

def delete_inactive_accounts(account_ids: list[str]) -> None:
    db.execute("DELETE FROM accounts WHERE id = ANY(%s)", [account_ids])

The agent's only path to that side effect should be a wrapped version that requires an approved Impri action first. Everything else — the model choosing to call the tool, the reasoning that led there — stays exactly as flexible as before. What changes is that the tool itself refuses to run without a decision:

import os
import time
import requests

IMPRI_BASE = "https://api.impri.dev"
HEADERS = {"Authorization": f"Bearer {os.environ['IMPRI_API_KEY']}"}

def delete_inactive_accounts(account_ids: list[str], reason: str) -> None:
    action = requests.post(
        f"{IMPRI_BASE}/v1/actions",
        headers=HEADERS,
        json={
            "kind": "data.delete",
            "title": f"Delete {len(account_ids)} inactive accounts",
            "preview": {
                "format": "markdown",
                "body": f"**Reason:** {reason}\n\n**Account IDs:**\n" +
                        "\n".join(f"- {a}" for a in account_ids),
            },
            "idempotent": False,
            "undo": "No undo — restore from the nightly accounts backup snapshot if needed.",
            "expires_in": 3600,
        },
    ).json()
    action_id = action["id"]

    while True:
        result = requests.get(f"{IMPRI_BASE}/v1/actions/{action_id}", headers=HEADERS).json()
        if result["status"] != "pending":
            break
        time.sleep(10)

    if result["status"] != "approved":
        print(f"Delete blocked: {result['status']}")
        return

    db.execute("DELETE FROM accounts WHERE id = ANY(%s)", [account_ids])
    requests.post(
        f"{IMPRI_BASE}/v1/actions/{action_id}/result",
        headers=HEADERS,
        json={"status": "executed", "payload": {"deleted_count": len(account_ids)}},
    )

The account_ids list is not editable here — for a delete, letting a human silently trim the list without the agent knowing is more confusing than useful. If you want that, add "editable": ["preview.body"] and re-derive the ID list from the edited markdown before executing, rather than trusting the original.

`idempotent: false` and `undo` are doing real work here

Two of Impri's optional fields matter more for deletes than for almost any other action kind:

idempotent: false — a retried delete of the same IDs is harmless (they're already gone), but a retry that includes newly matched rows because the filter re-ran is not. Setting this to false puts a "retrying may duplicate this action" warning on the card, which for a delete reads more like "retrying may delete more than you think" — worth the reviewer's attention.
undo — even when there's no real undo, say so explicitly ("No undo — restore from backup"). A blank field reads as "reversible" by omission. A stated boundary reads as what it is.

What the reviewer is actually deciding

Question the card should answer	Where it comes from
How many rows / records are affected?	`preview.body` — state the count, not just "some accounts"
Why is this happening?	`title` + a reason line in the body
Can this be undone?	`undo`
Could a re-run duplicate the damage?	`idempotent: false`

If your agent can't answer "how many rows" before pushing the action, that's worth fixing upstream — a delete proposal without a scoped count is asking the human to approve a blank check.

Rejected and expired deletes

Treat rejected and expired identically: the delete never runs. For a destructive action, don't auto-retry a rejected delete with a "maybe try smaller batches" fallback unless a human explicitly asked for that — silently re-proposing a delete the reviewer just said no to defeats the point of asking.

See the full three-call pattern in how to add human approval to an AI agent, how approvals show up in the audit log, and how to auto-route delete-kind actions to a specific reviewer with rules.

Approve Payments Before Your AI Agent Charges a Card

sekera-radim — Sun, 26 Jul 2026 12:10:27 +0000

Approve payments before your AI agent charges a card — review the vendor, amount, and card on file so no charge fires without a human saying yes.

The problem with autonomous spend

Agents that manage ad budgets, top up cloud credits, or renew a vendor subscription eventually need to move money. That's a different risk class than sending an email or posting a tweet: a wrong or duplicated email is embarrassing, a wrong or duplicated charge is a chargeback, a support ticket, and possibly a compliance question. If the agent's only path to charging a card runs through a human decision first, a hallucinated amount or a mis-parsed invoice never reaches the payment provider at all.

The pattern is the same three-call gate used for any other action — push, poll, execute — but payments warrant two adjustments: the amount should not be editable by the reviewer, and the action should be marked so the approval card visibly warns that retrying it is unsafe.

Wiring the gate with the TypeScript SDK

A spend agent that tops up an ad account when the daily budget drops below a floor:

import { ImpriClient, ImpriRejected, ImpriTimeout } from '@impri/sdk'

const impri = new ImpriClient({ apiKey: process.env.IMPRI_API_KEY! })

async function topUpAdBudget(vendor: string, amountUsd: number, cardLast4: string) {
  const action = await impri.createAction({
    kind: 'payment.charge',
    title: `Top up ${vendor} ad budget — $${amountUsd.toFixed(2)}`,
    preview: {
      format: 'markdown',
      body: `**Vendor:** ${vendor}\n**Amount:** $${amountUsd.toFixed(2)}\n**Card:** •••• ${cardLast4}\n\nDaily budget dropped below the $50 floor; campaigns pause otherwise.`,
    },
    payload: { amount: amountUsd, currency: 'USD', vendor },
    expiresIn: 3600, // 1 hour — a paused campaign can wait that long
    editable: [],    // binary approval only, see below
  })

  try {
    const decided = await impri.awaitDecision(action.id, { timeoutS: 3600 })
    await chargeCard(vendor, amountUsd, cardLast4)   // your payment provider call
    await impri.reportResult(decided.id, 'executed')
  } catch (e) {
    if (e instanceof ImpriRejected) {
      console.log('Top-up declined — campaigns stay paused until someone reviews spend manually.')
    } else if (e instanceof ImpriTimeout) {
      console.log('No decision within the hour — treat this run as not approved.')
    } else {
      throw e
    }
  }
}

chargeCard sits inside the try block after awaitDecision resolves — there's no branch that reaches it on rejection or timeout.

Why payment approvals should not be editable

For a drafted email or social post, letting the reviewer tweak the wording before approving is the whole point. For a charge, it's the opposite: if the reviewer could edit preview.body and change the number, they'd be approving a different transaction than the one your reconciliation and idempotency logic expects — the card, the vendor, and the amount need to match what the agent actually submitted. Set editable: [] on payment actions. The reviewer's job is binary: this exact charge, yes or no.

Marking the charge as non-idempotent

POST /v1/actions accepts an idempotent hint and an undo description that show up directly on the approval card. For a charge, both are worth setting:

curl -X POST https://api.impri.dev/v1/actions \
  -H "Authorization: Bearer $IMPRI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "payment.charge",
    "title": "Renew Acme Corp annual plan — $1,200.00",
    "preview": { "format": "plain", "body": "Card ending 4242, vendor: Acme Corp" },
    "idempotent": false,
    "undo": "Refund through the Stripe dashboard or the payment providers refund API"
  }'

idempotent: false puts a "retrying may duplicate this action" badge on the card — useful context if an agent retry loop somehow pushed the same charge twice. undo tells the reviewer the escape hatch up front, before they approve, not after something's already gone wrong.

Auto-approving the ones that don't need a human

Not every charge needs a person to look at it. Impri's rules engine evaluates payload_conditions against the payload field you send, so a small recurring top-up can skip the queue while anything larger still waits for a human:

{
  "name": "Auto-approve small ad top-ups",
  "kind_pattern": "payment.*",
  "payload_conditions": [
    { "path": "amount", "op": "lt", "value": 25 },
    { "path": "currency", "op": "eq", "value": "USD" }
  ],
  "rule_action": "auto_approve"
}

Set a second rule with rule_action: "escalate" on larger amounts if you want those routed to a specific Slack or Telegram channel instead of the default notification.

What happens on rejection, timeout, or expiry

ImpriRejected and ImpriTimeout are normal outcomes, not errors — a rejected top-up just means the campaign stays paused until a human tops it up manually or approves the next attempt. Impri never decides whether a charge is a good idea; it stores the proposed charge, notifies someone, and holds the decision. The judgment about whether $1,200 for an annual renewal is reasonable stays entirely with the person who taps approve, and the audit log keeps a record of exactly who approved which charge and when.

Next step: the TypeScript SDK reference for the full createAction/awaitDecision/reportResult API this example uses.

Human Approval Before an Agent Posts to Social Media

sekera-radim — Sat, 25 Jul 2026 21:10:03 +0000

Add human approval before an agent posts to social media — review the exact text, edit tone or facts, and stop a bad post before it ever goes live.

Why social posts need a slower gate than they get

A support-triage agent that misreads a ticket wastes ten minutes. A social agent that misreads a trending topic, a competitor's outage, or a user complaint and posts about it publicly wastes a lot more than ten minutes — and it's visible to everyone, indexed by search engines, and screenshot-able forever. Agents that monitor mentions, drafts replies, or schedule posts from a content calendar are exactly the kind of "drafts well, doesn't know when to stop" system that needs a human in the loop before the "publish" call, not after.

The naive fix — telling the agent "always ask before posting" in its system prompt — is not a gate. It's a suggestion the model can talk itself past, especially once external content (a scraped tweet, a Reddit thread, a competitor's blog) is sitting in its context and shaping what it decides to write. What you want instead is a code path where the actual platform API call is unreachable until an external decision says so.

The gate, end to end (Python)

Three calls: push the draft, poll for a decision, execute only on approval.

import os
import time
import requests

IMPRI_BASE = "https://api.impri.dev"
HEADERS = {
    "Authorization": f"Bearer {os.environ['IMPRI_API_KEY']}",
    "Content-Type": "application/json",
}

def push_post_for_approval(draft_text: str, scheduler_url: str) -> str:
    resp = requests.post(
        f"{IMPRI_BASE}/v1/actions",
        headers=HEADERS,
        json={
            "kind": "social.post",
            "title": "LinkedIn: reply to outage thread mentioning our API",
            "preview": {"format": "markdown", "body": draft_text},
            "target_url": scheduler_url,
            "expires_in": 1800,  # 30 min — a stale reply reads as tone-deaf
            "editable": ["preview.body"],
        },
    )
    resp.raise_for_status()
    return resp.json()["id"]

def wait_for_decision(action_id: str) -> dict:
    while True:
        data = requests.get(f"{IMPRI_BASE}/v1/actions/{action_id}", headers=HEADERS).json()
        if data["status"] != "pending":
            return data
        time.sleep(10)

action_id = push_post_for_approval(draft, "https://buffer.com/queue/abc123")
decision = wait_for_decision(action_id)

if decision["status"] == "approved":
    final_body = decision["decision"]["final_preview"]["body"]
    post_to_linkedin(final_body)  # your platform call
    requests.post(
        f"{IMPRI_BASE}/v1/actions/{action_id}/result",
        headers=HEADERS,
        json={"status": "executed"},
    )
else:
    logger.info("post not published, status=%s", decision["status"])

post_to_linkedin only runs inside the approved branch — there is no code path from "agent drafted a reply" to "reply is live" that skips the decision.

What the reviewer sees on the approval card

Title — a one-line summary ("reply to outage thread"), not the full post, so a reviewer scanning a phone notification knows what's being asked.
Preview body — the exact text that will be posted, rendered as markdown, editable inline. A reviewer can fix a wrong product name or soften a line without kicking it back to the agent.
target_url — a link to the draft sitting in your scheduling tool (Buffer, Hootsuite, or the platform's own composer), so the reviewer can see formatting and any attached media before approving.
Expiry countdown — set short (30–60 minutes) for anything time-sensitive. A reply to a live incident thread that sits pending for two days is worth rejecting on principle, since expiry is a correctness feature, not just cleanup.

Handling rejection, expiry, and edits

A rejected or expired status means the polling loop above exits with post_to_linkedin never called — nothing gets special-cased. If the reviewer edited the draft, decision.final_preview.body carries the edited text; always read from there, never from the original preview.body, since the API only returns the version the human actually approved.

Situation	What happens
Reviewer approves as-is	Original draft posts unchanged
Reviewer edits then approves	Edited text posts (`final_preview.body`)
Reviewer rejects	Nothing posts; log and move on
Window expires unattended	Treated as rejected; re-draft if still relevant

What Impri does not check

Impri stores the draft, notifies a human, and holds the decision — it does not read the post and judge whether it violates a platform's terms of service, your brand voice guide, or defamation law. That judgment stays with the human reviewing the card. Impri also isn't a scheduling tool: it doesn't manage a content calendar or pick posting times, it just gates the one action — the actual platform-side publish call — that turns a draft into something public.

For a phone-first workflow, pair this with Telegram approval so a reviewer can approve or edit from a notification without opening a dashboard, and check the audit log later for a record of every post approved, by whom, and what was changed before it went out.

Next step: quickstart to get an API key and try this against a test project.

Approve Slack Messages From an AI Agent

sekera-radim — Fri, 24 Jul 2026 22:30:02 +0000

Put a human approval step in front of every Slack message your AI agent sends — review, edit, or reject the exact wording before chat.postMessage fires.

Two different "Slack" problems

There are two unrelated things people mean by "Slack" and Impri approvals, and it's worth being explicit about which one this page covers. Approve AI agent actions from Slack is about using Slack as your notification channel — approval cards for any kind of action (emails, GitHub issues, refunds) show up in a Slack DM with buttons. This page is the other direction: your agent's job is to post messages into Slack, and you want a human to read the exact text before it goes out. The action being gated has kind: "slack.message.send", not the notification transport.

You can combine both — get the review card in Slack for an action that itself posts to Slack — but for a customer-facing channel, most teams don't want approve/reject noise landing in the same workspace the customer can see, so the example below routes notifications elsewhere.

Scenario: a bot in a shared support channel

A company runs a support bot in a Slack Connect channel shared with a customer. The bot reads incoming messages, drafts a reply, and — before this gate existed — posted it immediately. One bad reply in a channel the customer can see is worse than a slow reply, so every draft now waits for a teammate to approve it from their phone.

import os
import time
import httpx
from slack_sdk import WebClient

IMPRI_API_KEY = os.environ["IMPRI_API_KEY"]
IMPRI_BASE = "https://api.impri.dev"
slack = WebClient(token=os.environ["SLACK_BOT_TOKEN"])


def propose_and_wait(channel: str, draft: str) -> tuple[str, str] | None:
    """Push a Slack reply draft for approval. Returns (action_id, approved_text), or None."""
    resp = httpx.post(
        f"{IMPRI_BASE}/v1/actions",
        headers={"Authorization": f"Bearer {IMPRI_API_KEY}"},
        json={
            "kind": "slack.message.send",
            "title": f"Reply in #{channel}",
            "preview": {"format": "plain", "body": draft},
            "expires_in": 900,              # 15 minutes — a stale support reply isn't worth sending
            "editable": ["preview.body"],
        },
        timeout=10,
    )
    resp.raise_for_status()
    action_id = resp.json()["id"]

    while True:
        poll = httpx.get(
            f"{IMPRI_BASE}/v1/actions/{action_id}",
            headers={"Authorization": f"Bearer {IMPRI_API_KEY}"},
            timeout=10,
        ).json()
        if poll["status"] != "pending":
            break
        time.sleep(5)

    if poll["status"] != "approved":
        return None

    return action_id, poll["decision"]["final_preview"]["body"]


def handle_customer_message(channel_id: str, draft_reply: str) -> None:
    decision = propose_and_wait(channel_id, draft_reply)
    if decision is None:
        return  # rejected or expired — the bot stays quiet

    action_id, approved_text = decision
    slack.chat_postMessage(channel=channel_id, text=approved_text)

    httpx.post(
        f"{IMPRI_BASE}/v1/actions/{action_id}/result",
        headers={"Authorization": f"Bearer {IMPRI_API_KEY}"},
        json={"status": "executed"},
        timeout=10,
    )

handle_customer_message never calls slack.chat_postMessage on a rejected or expired draft — propose_and_wait returns None and the function exits before reaching the Slack client at all.

What the reviewer sees and can change

Because editable includes preview.body, the approver can fix a tone problem or a factual slip directly in the Impri card before tapping approve. poll["decision"]["final_preview"]["body"] always carries whatever the reviewer left — the edited version if they changed it, the original otherwise — so handle_customer_message never needs to check whether an edit happened; it just uses the field.

Field	What it controls
`preview.body`	The draft text shown to the reviewer, and posted to Slack if approved unedited
`editable: ["preview.body"]`	Lets the reviewer rewrite the reply before approving
`expires_in: 900`	How long an unanswered draft stays postable — short here because support replies age fast
`decision.final_preview.body`	What actually gets sent — always read from here, never from the original draft

Picking where the approval notification lands

Nothing about this pattern requires the approval card itself to avoid Slack — you can route it to a Slack channel via Slack approval exactly as described there, as long as it's a different, internal channel from the one the bot posts into. If you'd rather not stand up Slack OAuth just for reviewing outbound bot messages, a push notification through ntfy or web push gets a reviewer the same one-tap approve/reject without opening Slack at all.

Where this breaks down

This gate only holds if slack.chat_postMessage(or your equivalent Slack call) is unreachable except through handle_customer_message. If the bot process also has a cron job, a webhook handler, or another code path that holds the same SLACK_BOT_TOKEN and can post independently, that path bypasses the gate — Impri has no way to intercept a Slack API call it never sees. Keep the bot token scoped to the one function that calls propose_and_wait first.

Next step

Quickstart — get an API key and push your first action
How to add human approval to an AI agent — the push → poll → execute pattern this page builds on
Approve AI agent actions from Slack — the other direction: getting approval notifications delivered inside Slack

Approve Emails Before Your AI Agent Sends Them

sekera-radim — Thu, 23 Jul 2026 20:50:02 +0000

Give your email-sending AI agent a human approval gate: push the draft, let the reviewer edit subject and body, then send only the approved version.

Why email is the highest-risk action for an AI agent

Most agent side effects are reversible or low-stakes. An email is neither. It lands in someone's inbox immediately, carries your name, and can cause real damage if the tone is wrong, the facts are off, or it goes to the wrong address. A reply to a customer complaint, a cold outreach, a notification to a partner — any of these can go sideways when drafted by an agent that misread context or received a subtly manipulated input.

The instinct is to add a confirmation message in the system prompt: "Always ask for approval before sending emails." That reduces mistakes. It does not eliminate them, and it is not auditable. The model can rationalize past it.

A structural gate removes that discretion: the email cannot be sent unless an external system returns a human decision of approved. The agent literally cannot reach the sending code without it.

What this looks like in practice

The flow is three steps from the agent's perspective:

Agent produces draft
  │
  ├─ POST /v1/actions  →  Impri stores draft, notifies you
  │
  ├─ GET /v1/actions/:id  (poll until decided)
  │    Human opens inbox card, reads draft,
  │    optionally edits subject or body, approves or rejects
  │
  └─ On "approved": send decision.final_preview.body
     On "rejected" or "expired": abort, log, optionally retry

The gate is not a confirmation prompt — it is a data dependency. The send function is never called without the API returning status: "approved".

Code example: Node.js email agent with approval gate

This example uses TypeScript with nodemailer for sending. The Impri calls are plain fetch.

import nodemailer from "nodemailer";

const IMPRI_KEY = process.env.IMPRI_API_KEY!;
const IMPRI_BASE = "https://api.impri.dev";

async function sendWithApproval(opts: {
  to: string;
  subject: string;
  body: string;
  expiresIn?: number; // seconds; default 3600
}): Promise<"sent" | "rejected" | "expired"> {
  // 1. Push the draft to Impri for human review
  const push = await fetch(`${IMPRI_BASE}/v1/actions`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${IMPRI_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      kind: "email.send",
      title: `Email to ${opts.to}: ${opts.subject}`,
      preview: {
        format: "markdown",
        body: `**To:** ${opts.to}\n**Subject:** ${opts.subject}\n\n---\n\n${opts.body}`,
      },
      editable: ["preview.body"],           // let the reviewer edit the body
      expires_in: opts.expiresIn ?? 3600,
    }),
  });

  if (!push.ok) throw new Error(`Impri push failed: ${push.status}`);
  const { id: actionId } = await push.json();

  // 2. Poll until the human decides (or the action expires)
  let result: { status: string; decision?: { final_preview?: { body: string }; diff?: string } };
  for (;;) {
    const poll = await fetch(`${IMPRI_BASE}/v1/actions/${actionId}`, {
      headers: { Authorization: `Bearer ${IMPRI_KEY}` },
    });
    result = await poll.json();
    if (result.status !== "pending") break;
    await new Promise((r) => setTimeout(r, 10_000));
  }

  if (result.status !== "approved") {
    return result.status as "rejected" | "expired";
  }

  // 3. Send using the version the human approved (may differ from original draft)
  const approvedBody = result.decision!.final_preview!.body;

  const transporter = nodemailer.createTransport({
    host: process.env.SMTP_HOST,
    port: 587,
    auth: { user: process.env.SMTP_USER, pass: process.env.SMTP_PASS },
  });

  await transporter.sendMail({
    from: process.env.SMTP_FROM,
    to: opts.to,
    subject: opts.subject,
    text: approvedBody,
  });

  // 4. Report the outcome back to Impri (populates the audit log)
  await fetch(`${IMPRI_BASE}/v1/actions/${actionId}/result`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${IMPRI_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ status: "executed" }),
  });

  return "sent";
}

Call this from your agent whenever it wants to send an email. The agent passes its draft; sendWithApproval blocks until a human decides; the outcome is returned as a string the agent can act on.

Letting the human edit before approving

Setting editable: ["preview.body"] adds an edit field to the inbox card. The reviewer can rewrite the greeting, fix a factual error, adjust the closing — whatever the draft needs — before clicking Approve.

The decision always carries:

decision.final_preview — the body as it was when the human approved (use this to send)
decision.diff — a unified diff of what changed (present only when something was modified)

Never send the original body argument — send final_preview.body. Even if the human approved without editing, that field holds the canonically approved text. The original is not surfaced in the decision response.

This editing capability is what makes the gate useful for email specifically. AI-drafted copy often needs light touch-ups in tone or specifics. Rather than forcing a reject → regenerate cycle, the reviewer can fix the draft in place and approve it in one step.

Setting the right expiry

expires_in: 3600      // 1 hour  — good for time-sensitive follow-ups
expires_in: 86400     // 24 hours — reasonable for non-urgent outreach
expires_in: 259200    // 72 hours — the default; fine for async review flows

An email that sat in the approval queue for two days has probably lost its context: the meeting it was following up on happened, the deal moved on, the thread continued without it. Set expires_in to match the actual window in which the email would still make sense to send.

Treat expired the same as rejected: do not send, and surface the outcome to your agent so it can log, notify, or reschedule as appropriate.

Scope and boundaries

Impri is the gate only. It stores the draft, notifies the human (via inbox, Slack, Telegram, or Discord), and holds the decision. It does not interpret the email content, check grammar, filter for spam signals, or send anything itself.

The gate is structural only as long as the agent cannot reach your email-sending credential through any other path. If the agent also has direct access to your SMTP credentials or an email API key outside this wrapper, it can route around the approval step. Keep the sending credential inside the wrapper; do not expose it to the agent.

Concern	Impri handles it
Gate: block send until human says yes	Yes
Notify reviewer via Slack / Telegram	Yes (notifications)
Let reviewer edit body before approving	Yes (`editable: ["preview.body"]`)
Audit log of what was approved, when, by whom	Yes (audit log)
Check email for spam / deliverability	No
Drafting or improving email content	No
Scheduling the send for a future time	No

Next steps

Quickstart — get an API key and push your first action in five minutes
Webhooks — receive a callback instead of polling when the decision arrives
Notifications and approval channels — approve from Slack or Telegram without opening the inbox

Human Approval for the Vercel AI SDK

sekera-radim — Wed, 22 Jul 2026 16:30:03 +0000

Gate risky tool calls in the Vercel AI SDK behind human approval — pause execution until a reviewer approves, edits, or rejects the draft first.

Where the gate belongs

The ai package runs tools as plain async functions passed to generateText or streamText. Most tools are safe to let run unattended — a lookup, a read-only API call. A smaller set reach into the world in ways you cannot take back: issuing a refund, sending an email, posting to a customer. Those are the ones worth pausing on.

There is no special SDK feature needed for this. A tool's execute function can await anything, including a call that blocks on a human decision. As long as the side effect happens inside execute — not before it — the tool call itself becomes the gate.

Scenario: refunds from a support inbox

A support-triage agent reads incoming tickets and, when a customer clearly deserves one, issues a Stripe refund. Refunds are exactly the kind of action you don't want an LLM approving on its own: wrong charge ID, wrong amount, or a customer who talked the model into a refund it shouldn't have granted are all real failure modes.

import { generateText, tool, stepCountIs } from 'ai'
import { openai } from '@ai-sdk/openai'
import { z } from 'zod'
import Stripe from 'stripe'

const IMPRI_API_KEY = process.env.IMPRI_API_KEY!
const IMPRI_BASE = 'https://api.impri.dev'
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!)

async function pushAndAwait(kind: string, title: string, body: string) {
  const created = await fetch(`${IMPRI_BASE}/v1/actions`, {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${IMPRI_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      kind,
      title,
      preview: { format: 'markdown', body },
      expires_in: 3600,
      editable: ['preview.body'],
    }),
  }).then((r) => r.json())

  while (true) {
    const poll = await fetch(`${IMPRI_BASE}/v1/actions/${created.id}`, {
      headers: { Authorization: `Bearer ${IMPRI_API_KEY}` },
    }).then((r) => r.json())

    if (poll.status !== 'pending') return { actionId: created.id, poll }
    await new Promise((resolve) => setTimeout(resolve, 10_000))
  }
}

const issueRefund = tool({
  description: 'Propose a Stripe refund for a customer. Requires human approval before it is issued.',
  inputSchema: z.object({
    chargeId: z.string(),
    amountCents: z.number(),
    reason: z.string(),
  }),
  execute: async ({ chargeId, amountCents, reason }) => {
    const preview = `**Charge:** \`${chargeId}\`\n**Amount:** $${(amountCents / 100).toFixed(2)}\n\n${reason}`
    const { actionId, poll } = await pushAndAwait(
      'stripe.refund.create',
      `Refund $${(amountCents / 100).toFixed(2)} — ${chargeId}`,
      preview,
    )

    if (poll.status !== 'approved') {
      return { issued: false, reason: `Not approved — status was "${poll.status}".` }
    }

    // decision.final_preview carries any edits the reviewer made to the reason/amount note
    const refund = await stripe.refunds.create({ charge: chargeId, amount: amountCents })

    await fetch(`${IMPRI_BASE}/v1/actions/${actionId}/result`, {
      method: 'POST',
      headers: { Authorization: `Bearer ${IMPRI_API_KEY}`, 'Content-Type': 'application/json' },
      body: JSON.stringify({ status: 'executed' }),
    })

    return { issued: true, refundId: refund.id }
  },
})

const result = await generateText({
  model: openai('gpt-4.1'),
  system:
    'You handle refund requests from the support inbox. Use issueRefund for every refund — never tell the customer a refund was issued unless the tool result has issued: true.',
  prompt: 'Charge ch_1PxYz: item arrived broken, customer wants a full refund of $42.00.',
  tools: { issueRefund },
  stopWhen: stepCountIs(5),
})

console.log(result.text)

What actually blocks execution

generateText awaits each tool's execute function before it can use the result to continue the conversation. Inside issueRefund, pushAndAwait polls GET /v1/actions/:id until the status leaves pending — the function does not return, so the model has no tool result to reason about and stripe.refunds.create is never reached, until a human decides. Reject or let it expire and the if (poll.status !== 'approved') branch returns early; the refund call is skipped entirely.

This only holds as long as issueRefund is the agent's sole path to stripe.refunds.create. If another tool or a direct Stripe key elsewhere in your codebase can also trigger a refund, the gate only covers the path that goes through it.

Multi-step loops and `stopWhen`

stopWhen: stepCountIs(5) caps how many tool-call rounds the model can take in one generateText call. Each poll inside execute can take anywhere from seconds to the full expires_in window, so a single gated tool call can dominate the run's wall-clock time — that's expected, not a bug. If the agent runs inside a request handler with its own timeout (a Vercel serverless function, for instance), a long-pending approval will hit that timeout before Impri's. For approvals that can sit for hours, run the agent from a durable worker or queue consumer instead of an HTTP handler, so the wait doesn't get killed by an unrelated timeout.

Next step

Quickstart — get an API key and push your first action
TypeScript SDK — a typed client instead of raw fetch calls
How to add human approval to an AI agent — the underlying push → poll → execute pattern this page builds on

Human-in-the-Loop for Pydantic AI Agents

sekera-radim — Tue, 21 Jul 2026 11:30:02 +0000

Add human-in-the-loop for Pydantic AI agents at the tool boundary: wrap a refund tool in Impri's approval_gate, and no charge reverses until a person says yes.

Why the tool function, not the system prompt

A Pydantic AI agent with a stripe.refund-shaped tool will eventually call it on a customer's word alone, because that's what the system prompt told it to be helpful about. Telling the model "always ask before refunding" in the prompt doesn't hold up once the conversation gets long or the customer is insistent — the instruction is competing with the rest of the context for the model's attention.

The reliable version puts the check in the tool function itself, where the model has no way to talk its way past it. The agent still decides when to call issue_refund — but the function's body, not the model, decides whether the refund actually happens.

A refund tool with a human gate

import os
import stripe
from dataclasses import dataclass
from pydantic_ai import Agent, RunContext
from impri import ImpriClient, ImpriRejected, ImpriTimeout

@dataclass
class Deps:
    impri: ImpriClient
    stripe_key: str

agent = Agent(
    "openai:gpt-4o",
    deps_type=Deps,
    system_prompt="You are a billing support agent for a SaaS product.",
)

@agent.tool
async def issue_refund(
    ctx: RunContext[Deps], customer_id: str, amount_cents: int, reason: str
) -> str:
    """Refund a customer. Requires human approval before the charge is reversed."""
    body = f"**Customer:** {customer_id}\n**Amount:** ${amount_cents / 100:.2f}\n**Reason:** {reason}"

    try:
        async with ctx.deps.impri.approval_gate(
            kind="stripe.refund",
            title=f"Refund ${amount_cents / 100:.2f} to {customer_id}",
            preview={"format": "markdown", "body": body},
            editable=["preview.body"],
            timeout_s=600,
        ) as approved:
            refund = stripe.Refund.create(
                customer=customer_id,
                amount=amount_cents,
                reason="requested_by_customer",
                api_key=ctx.deps.stripe_key,
            )
            return f"Refund {refund.id} issued for {customer_id}."
    except ImpriRejected as e:
        return f"Refund not issued — a reviewer rejected it (action {e.action_id})."
    except ImpriTimeout:
        return "Refund not issued — no reviewer decision within 10 minutes."


async def main():
    deps = Deps(impri=ImpriClient(), stripe_key=os.environ["STRIPE_SECRET_KEY"])
    result = await agent.run(
        "Customer cust_9f2 was double-charged on the March invoice, refund $42.00.",
        deps=deps,
    )
    print(result.output)

approval_gate is the SDK's context-manager form: it pushes the action, blocks until a human decides, and calls report_result automatically on the way out — executed on a clean exit, execute_failed if the stripe.Refund.create call inside the block raises. See Python SDK for the full method reference.

Handling rejection inside the tool, not outside it

Notice the try/except lives inside issue_refund, wrapping the whole gate. If you let ImpriRejected propagate up instead, Pydantic AI's tool-calling loop sees an unhandled exception from a tool call — depending on your retry settings, the agent may interpret that as a transient failure and call issue_refund again with the same arguments, which is the last thing you want after a human explicitly said no. Catching it and returning a plain string turns "rejected" into ordinary tool output: the agent reads it, tells the customer no refund went out, and moves on.

Sync agent, async gate

approval_gate is an async context manager, so issue_refund has to be declared async def and the run driven with await agent.run(...) rather than agent.run_sync(...). If the rest of your agent is otherwise synchronous, this one tool is a reason to switch the entry point to the async form — Pydantic AI supports mixing sync and async tools on the same agent, but the gate itself only comes in async.

What's actually verified, and what isn't

Exception	What it means	What the tool does
(none — approved)	A human read the card and approved it	Calls Stripe, reports `executed`
`ImpriRejected`	A human explicitly declined	Returns a string, Stripe is never called
`ImpriTimeout`	No decision within `timeout_s`	Returns a string, action stays pending server-side

Impri verified that a human looked at exactly the card shown — customer ID, amount, reason — and approved it. It did not verify that customer_id is correct, that the amount matches the actual overcharge, or anything about Stripe's response. Those are the agent's and your billing system's job. And the gate only holds if issue_refund is the only path from this agent to stripe.Refund.create — a second tool with its own Stripe key would bypass it entirely.

Next step

See How to add human approval to an AI agent for the underlying REST pattern, or Quickstart to get an API key before wiring this into a real agent.

DEV Community: sekera-radim

Add Human Approval to a Cron Job

Why scheduled jobs are a blind spot

How the pattern works

Example: weekly newsletter send (Python)

Choosing the right expiry window

What rejection and expiry mean

Handling human edits

Next steps

Human Approval Before an Agent Sends SMS

Why SMS needs its own gate

The gate in practice

What the receptionist sees, and why editable matters

Rate limits and batch runs

Boundaries

Approve Refunds Issued by an AI Support Agent

Why refunds are a different risk class than replies

Wiring the gate into the refund path

What the reviewer sees, and how it maps to risk

Result payload and audit trail

Boundaries

Human Approval Before an AI Agent Deploys Code

Why "run the tests" isn't the same as "safe to ship"

Gating the deploy call, not the merge

What belongs on the approval card

Staging versus production

Rejected, expired, and rollback

What Impri isn't doing here

Gate Database Writes From an AI Agent

The shape of the problem

Wiring the gate with the Impri MCP server

Why the SQL text belongs in the preview, not just a summary

Scopes and keys

Rejected, expired, and retried writes

Require Human Approval Before an Agent Deletes Data

Why deletes need a different posture than sends or posts

Wrapping the delete function

idempotent: false and undo are doing real work here

What the reviewer is actually deciding

Rejected and expired deletes

Approve Payments Before Your AI Agent Charges a Card

The problem with autonomous spend

Wiring the gate with the TypeScript SDK

Why payment approvals should not be editable

Marking the charge as non-idempotent

Auto-approving the ones that don't need a human

What happens on rejection, timeout, or expiry

Human Approval Before an Agent Posts to Social Media

Why social posts need a slower gate than they get

The gate, end to end (Python)

What the reviewer sees on the approval card

Handling rejection, expiry, and edits

What Impri does not check

Approve Slack Messages From an AI Agent

Two different "Slack" problems

Scenario: a bot in a shared support channel

What the reviewer sees and can change

Picking where the approval notification lands

Where this breaks down

Next step

Approve Emails Before Your AI Agent Sends Them

Why email is the highest-risk action for an AI agent

What this looks like in practice

Code example: Node.js email agent with approval gate

Letting the human edit before approving

Setting the right expiry

Scope and boundaries

Next steps

Human Approval for the Vercel AI SDK

Where the gate belongs

Scenario: refunds from a support inbox

What actually blocks execution

Multi-step loops and stopWhen

Next step

Human-in-the-Loop for Pydantic AI Agents

Why the tool function, not the system prompt

A refund tool with a human gate

Handling rejection inside the tool, not outside it

Sync agent, async gate

What's actually verified, and what isn't

`idempotent: false` and `undo` are doing real work here

Multi-step loops and `stopWhen`