Agno

Mark an Agno tool requires_confirmation and answer the paused run with a person's decision from an inbox, inside the run or hours later by webhook.

Agno can stop a tool before it runs. Mark the tool @tool(requires_confirmation=True) and agent.run returns a paused run instead of an answer, with one requirement for each call in active_requirements. You answer each one with confirm() or reject(note) and pass them to continue_run. Who decides, and where, is up to you. This page makes each call a request in your VariantGate inbox, so the answer can come from a phone, an email link or Slack, a rule can settle the routine ones, and every decision is kept on the record.

1. Install the client

pip install https://variantgate.com/sdk/variantgate-latest.tar.gz

It has no dependencies beyond the standard library and works on Python 3.9 or newer. Make an agent key under Agents in your workspace and put it in VARIANTGATE_KEY. The client reads it from there.

2. Answer the paused run with a person’s decision

Install Agno with its OpenAI and SQLite extras too: pip install "agno[openai,sqlite]". This code ran against agno 3.2.1 on Python 3.12. The loop around the run asks a person about every call the agent wants to make, so they appear side by side, waits for the answers, and confirms or rejects each call before the run goes on.

import contextlib
import logging
import time

from agno.agent import Agent
from agno.db.sqlite import SqliteDb
from agno.models.openai import OpenAIChat
from agno.models.response import ToolExecution
from agno.run import RunContext, RunStatus
from agno.run.requirement import RunRequirement
from agno.tools import tool
from agno.tools.function import FunctionCall
from variantgate import (
    ApprovalClient,
    ChangedApprovalError,
    NotApprovedError,
    VariantGateError,
    is_allowed,
    is_changed,
)

import shop  # your own refund code

approvals = ApprovalClient("support-agent")  # reads VARIANTGATE_KEY
log = logging.getLogger(__name__)
WAIT_SECONDS = 900  # how long the run waits for a person


@tool(requires_confirmation=True)
def refund_order(order_id: str, amount_eur: str, fc: FunctionCall, run_context: RunContext) -> str:
    """Refund an order to the customer's original payment method.

    Args:
        order_id: The order to refund, such as "1182".
        amount_eur: The amount in euros, such as "49.00".
    """
    request_id = (run_context.metadata or {}).get("approvals", {}).get(fc.call_id)
    if request_id is None:  # confirmed without a person's approval
        return "Not refunded: this call has no approval."
    try:
        refund_id = shop.refund(order_id, amount_eur)
    except Exception:  # approved, but it failed: record it, and no retry
        log.exception("refund failed for order %s", order_id)
        with contextlib.suppress(VariantGateError):
            approvals.report_outcome(request_id, "failed", "the refund raised: check the order")
        return f"The refund for order {order_id} failed and may have gone through. Do not retry."
    with contextlib.suppress(VariantGateError):  # the money moved: never fail over the record
        approvals.report_outcome(request_id, "succeeded", f"refund {refund_id}")
    return f"Refunded €{amount_eur} for order {order_id}."


agent = Agent(
    model=OpenAIChat(id="gpt-5"),
    instructions="Help customers with their orders.",
    tools=[refund_order],
    db=SqliteDb(db_file="agno.db"),  # keeps sessions and paused runs
)


def describe(call: ToolExecution) -> dict:
    """What a person sees for one tool call: an action, a summary, an amount."""
    args = call.tool_args or {}
    if call.tool_name == "refund_order":
        return {
            "action": "payment.refund",
            "summary": f"Refund €{args['amount_eur']} for order {args['order_id']}",
            "amount": args["amount_eur"],
            "currency": "EUR",
            "details": {"order": args["order_id"]},
        }
    return {"action": f"tool.{call.tool_name}", "summary": f"Run {call.tool_name}", "details": args}


def answer(requirement: RunRequirement, decision: dict, approved: dict[str, str]) -> None:
    """Confirm the call only on an unchanged yes; otherwise reject it and tell the model why."""
    if not is_allowed(decision):
        if decision["status"] == "approved":  # approved, but agents are paused
            not_done(decision["id"], "paused")
        requirement.reject(str(NotApprovedError(decision)))
    elif is_changed(decision):  # a person approved less, or other wording
        not_done(decision["id"], "approved with changes")
        requirement.reject(str(ChangedApprovalError(decision)))
    else:
        requirement.confirm()
        approved[requirement.tool_execution.tool_call_id] = decision["id"]


def not_done(request_id: str, why: str) -> None:
    """Close an approved request on the record. Nothing ran, so a lost note harms nobody."""
    with contextlib.suppress(VariantGateError):
        approvals.report_outcome(request_id, "failed", f"not done: {why}")


def withdraw(asked: list[dict]) -> None:
    """Take back requests nobody will act on, and close any already approved as not done."""
    for request in asked:
        try:
            approvals.withdraw(request["id"])
        except VariantGateError:  # decided already, or the API is down
            with contextlib.suppress(VariantGateError):
                if approvals.check(request["id"])["status"] == "approved":
                    not_done(request["id"], "asking about the run's calls failed")


def run(text: str) -> str:
    result = agent.run(text)
    while result.is_paused:
        requirements = result.active_requirements
        if not all(r.needs_confirmation for r in requirements):
            raise RuntimeError("this loop answers confirmations only")
        asked: list[dict] = []
        deadline = time.monotonic() + WAIT_SECONDS  # one wait for all of them
        try:  # ask about every call first, so a person sees them side by side
            for requirement in requirements:
                request = describe(requirement.tool_execution)
                asked.append(approvals.ask(**request, ttl_seconds=3600))
            decisions = [approvals.wait(q, max(0.0, deadline - time.monotonic())) for q in asked]
        except VariantGateError:
            withdraw(asked)  # nothing runs, so nobody should be left deciding
            raise
        approved: dict[str, str] = {}
        for requirement, decision in zip(requirements, decisions, strict=True):
            answer(requirement, decision, approved)
        result = agent.continue_run(
            result, requirements=result.requirements, metadata={"approvals": approved}
        )
    if result.status == RunStatus.error:  # Agno returns a failed run, and a tool may have run
        raise RuntimeError(f"run {result.run_id} failed: look at the record before retrying")
    return result.content


if __name__ == "__main__":
    try:
        print(run("Order 1182 arrived broken. Please refund the €49."))
    except VariantGateError as error:  # the API could not be asked: nothing was refunded
        print(f"Stopped: could not ask for approval: {error}")
  • An approved call runs. A denied, expired or withdrawn one, or any call while the workspace is paused, is rejected with the reason. Agno hands that note to the model as the tool’s result, such as “Not approved: the request is denied (refund policy is 30 days).”, so it can tell the customer instead of trying again. An approval that a pause stops is closed on the record as not done. The run waits WAIT_SECONDS in all, however many calls it asked about; a request still open then is withdrawn and its call rejected, so nobody approves a call that will never run.
  • Agno would let you change a call’s tool_args before confirming it, and the tool would then run with the new values. answer does not: an approval of a changed version is not an approval of the call the model made. If a person lowers the amount or rewords the request, the call is rejected and the record says nothing was done. The model reads what was approved, such as “for at most 20.00 EUR”, and can ask again for that.
  • The request id reaches the tool through the metadata given to continue_run, found by the call’s id. Agno fills in fc and run_context itself and leaves them out of what the model sees. A call confirmed any other way finds no approval and refunds nothing.
  • Once the money has moved, a failure to record it never fails the tool, so nothing tempts the model into a second refund. If the refund raises, the tool records it as failed and tells the model not to retry; left alone, Agno would hand the model the exception’s text as the result. Raising StopAgentRun does not end a continued run in 3.2.1: its message, too, reaches the model and the run goes on.
  • describe is where you write what a person reads. Give each tool a clear action name and state the amount, so rules such as “always allow payment.refund up to €50” approve the small ones without anyone waiting.
  • If the API cannot be reached or refuses the call, nobody has said no, so no call is rejected and the model is not told anything. The loop raises and withdraws what it can of the requests it already made, so nobody approves a call that will not run; one already approved is closed on the record as not done. The run stays paused and nothing is refunded. If the answer to an ask is lost on its way back, the request may still be in your inbox with nothing waiting for it: deny it there.
  • When the model fails after a tool ran, Agno does not raise: it returns the run with status ERROR and stale text as its content. The loop raises then instead of passing that text on, since the refund may have gone through.
  • The loop answers confirmations only. A tool marked requires_user_input or external_execution needs a different answer, so the loop raises when it meets one.

When the answer may take hours

The loop above holds the run open while a person decides. For a decision that may take longer, let the run stop. Agno keeps the paused run in the agent’s database, and continue_run with its run_id and session_id picks it up in another process. start runs the agent until it needs a person, and park asks without waiting and saves those two ids with the request ids. Call on_webhook for every signed webhook, and sweep every few minutes. The webhook only says when: go_on reads each request with check, and the same answer confirms a call only on an unchanged yes. With the code above saved as support.py:

import contextlib
import logging
import os
import sqlite3
from collections.abc import Iterator, Mapping

from agno.agent import RunOutput
from agno.run import RunStatus
from variantgate import VariantGateError, verify_webhook

import shop  # your own code
from support import agent, answer, approvals, describe, withdraw

log = logging.getLogger(__name__)
CLAIM = "UPDATE parked SET claimed = 1 WHERE run_id = ? AND claimed = 0 RETURNING session_id"
DECIDED = {"request.approved", "request.denied", "request.expired", "request.withdrawn"}
SCHEMA = """
CREATE TABLE IF NOT EXISTS parked (run_id TEXT PRIMARY KEY, session_id TEXT, claimed INT);
CREATE TABLE IF NOT EXISTS asked (request_id TEXT PRIMARY KEY, run_id TEXT, call_id TEXT);
"""


@contextlib.contextmanager
def database() -> Iterator[sqlite3.Connection]:
    """Your database: a connection per call, so a webhook on any thread can use it."""
    with contextlib.closing(sqlite3.connect("parked.db")) as db, db:  # commits on the way out
        yield db


with database() as db:
    db.executescript(SCHEMA)


def start(text: str) -> str | None:
    """Run until the agent needs a person. Returns its answer, or None while it waits."""
    return park(agent.run(text))


def save(result: RunOutput, asked: list[tuple[str, str]]) -> None:
    """Park the run, unclaimed, with the requests asked about it: (request id, call id)."""
    with database() as db:  # one transaction: the old requests go, the new ones come
        db.execute("DELETE FROM asked WHERE run_id = ?", (result.run_id,))
        db.execute(
            "INSERT OR REPLACE INTO parked VALUES (?, ?, 0)", (result.run_id, result.session_id)
        )
        db.executemany(
            "INSERT INTO asked VALUES (?, ?, ?)", [(q, result.run_id, c) for q, c in asked]
        )


def park(result: RunOutput) -> str | None:
    """Ask about the run's calls without waiting, and save it. A run that did not pause is done."""
    if result.status == RunStatus.error:  # Agno returns a failed run, and a tool may have run
        raise RuntimeError(f"run {result.run_id} failed: look at its requests on the record")
    if not result.is_paused:
        with database() as db:
            db.execute("DELETE FROM asked WHERE run_id = ?", (result.run_id,))
            db.execute("DELETE FROM parked WHERE run_id = ?", (result.run_id,))
        return result.content
    requirements = result.active_requirements
    if not all(r.needs_confirmation for r in requirements):  # before asking anyone
        raise RuntimeError("park answers confirmations only")
    asked: list[dict] = []
    try:
        for requirement in requirements:
            request = describe(requirement.tool_execution)
            asked.append(approvals.ask(**request, ttl_seconds=24 * 3600))
    except VariantGateError:
        withdraw(asked)
        save(result, [])  # nobody asked yet: the sweep asks again
        log.warning("could not ask about run %s yet", result.run_id, exc_info=True)
        return None
    calls = [requirement.tool_execution.tool_call_id for requirement in requirements]
    try:
        save(result, [(q["id"], call) for q, call in zip(asked, calls, strict=True)])
    except sqlite3.Error:
        withdraw(asked)  # unsaved, nobody could finish them: take them back
        raise
    try:
        return go_on(result.run_id)  # a rule may have decided before the row was saved
    except Exception as error:  # saved, maybe refunded: never start it again
        log.warning("run %s parked, going on failed: %s", result.run_id, type(error).__name__)
        return None


def release(run_id: str) -> None:
    with database() as db:
        db.execute("UPDATE parked SET claimed = 0 WHERE run_id = ?", (run_id,))


def go_on(run_id: str) -> str | None:
    """Goes on with a parked run once, when every call it waits for is decided."""
    with database() as db:
        row = db.execute(CLAIM, (run_id,)).fetchone()  # take the run in one step
    if row is None:
        return None  # done already, or another delivery has it
    try:
        with database() as db:
            asked = db.execute("SELECT call_id, request_id FROM asked WHERE run_id = ?", (run_id,))
            calls = asked.fetchall()
        decisions = {call_id: approvals.check(request) for call_id, request in calls}
    except (VariantGateError, sqlite3.Error):
        release(run_id)
        raise
    if any(decision["status"] == "pending" for decision in decisions.values()):
        release(run_id)
        return None  # the webhook for the last decision goes on
    paused = agent.get_run_output(run_id=run_id, session_id=row[0])
    if paused is None or not paused.is_paused:  # stays claimed: look at the run
        raise RuntimeError(f"run {run_id} is not paused in Agno's database")
    requirements = paused.active_requirements
    if any(r.tool_execution.tool_call_id not in decisions for r in requirements):
        return park(paused)  # nobody was asked about these calls yet
    approved: dict[str, str] = {}
    for requirement in requirements:
        answer(requirement, decisions[requirement.tool_execution.tool_call_id], approved)
    result = agent.continue_run(
        run_id=run_id,
        session_id=row[0],
        requirements=paused.requirements,
        metadata={"approvals": approved},
    )
    return park(result)  # the agent may need a person again


def on_webhook(headers: Mapping[str, str], body: bytes) -> None:
    """From your signed-webhook handler, or a job it queues, with the body as it arrived."""
    event = verify_webhook(os.environ["VARIANTGATE_WEBHOOK_SECRET"], headers, body)
    request_id = event.get("data", {}).get("request_id")
    if event.get("type") not in DECIDED or not request_id:
        return  # such as webhook.test: answer 2xx, nothing to go on with
    with database() as db:
        row = db.execute("SELECT run_id FROM asked WHERE request_id = ?", (request_id,)).fetchone()
    if row and (reply := go_on(row[0])):  # the webhook says when; go_on reads what
        shop.send_reply(reply)  # your own code: the agent's answer to the customer


def sweep() -> None:
    """Every few minutes: asks again, and goes on with runs a webhook could not finish."""
    with database() as db:
        waiting = db.execute("SELECT run_id FROM parked WHERE claimed = 0").fetchall()
    for (run_id,) in waiting:
        try:
            if reply := go_on(run_id):
                shop.send_reply(reply)
        except Exception:  # one run's failure must not hold up the others
            log.exception("sweep could not go on with run %s", run_id)
  • Webhooks can arrive twice, and a run with two calls gets one per call, so go_on first claims the parked run in a single UPDATE … RETURNING. Only the delivery that claims it goes on. That matters in Agno: continuing a run that already finished is not a no-op, it starts a copy of the run and calls the model again.
  • While any of the run’s requests is still pending, go_on gives the claim back and does nothing; the webhook for the last decision continues the run. A rule can decide before the run is saved, so park calls go_on once itself, and start then returns the answer at once. Once the run is saved, start returns None whatever goes wrong after, so never retry it: a second run would ask again and could refund twice. The webhook, the sweep or a person goes on with the saved run.
  • When the continued run asks for another call, park asks about it and saves it in place of the old requests. When it needs nothing more, the run is removed and on_webhook passes the agent’s answer to your code to send to the customer.
  • If asking fails, at the start or after a continued run asks again, park takes back what it asked and saves the run with no requests. The sweep asks again once the API answers. Whenever the calls Agno waits for are not the ones asked about, go_on asks again rather than answer them. The sweep logs a run that fails and goes on with the others.
  • A pause after the decision still stops the refund: check then says allowed is false, and the call is rejected.
  • Like the loop above, park answers confirmations only, and raises before asking anyone when the run waits for user input or an external result.
  • on_webhook goes on only for a decided, expired or withdrawn request. Any other event, such as the test you send from the webhook settings, is checked and then ignored, so your handler can answer it with a 2xx.
  • If saving fails, park withdraws the requests it made and raises. If continuing fails or ends in ERROR, saving fails after a continued run, or Agno no longer has the run as paused, the row stays claimed rather than going back: the tool may already have run, so look at the run’s requests on the record before you set claimed back to 0. The sweep then goes on from wherever the run stands.
  • UPDATE … RETURNING needs SQLite 3.35 or newer. On an older SQLite, claim with an UPDATE and check that it changed one row.

When the built-in approval is enough

If the person chatting with the agent is the one who should decide, answer the requirements in your own UI and leave VariantGate out. It earns its place when the agent runs with nobody watching, when someone else must decide, when rules should settle the routine calls, or when you need a record of who approved what. The framework comparison goes through that choice.