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.gzIt 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_SECONDSin 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_argsbefore confirming it, and the tool would then run with the new values.answerdoes 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
metadatagiven tocontinue_run, found by the call’s id. Agno fills infcandrun_contextitself 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
StopAgentRundoes not end a continued run in 3.2.1: its message, too, reaches the model and the run goes on. describeis where you write what a person reads. Give each tool a clear action name and state the amount, so rules such as “always allowpayment.refundup 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
ERRORand 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_inputorexternal_executionneeds 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_onfirst claims the parked run in a singleUPDATE … 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_ongives the claim back and does nothing; the webhook for the last decision continues the run. A rule can decide before the run is saved, soparkcallsgo_ononce itself, andstartthen returns the answer at once. Once the run is saved,startreturnsNonewhatever 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,
parkasks about it and saves it in place of the old requests. When it needs nothing more, the run is removed andon_webhookpasses 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,
parktakes 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_onasks 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:
checkthen saysallowedis false, and the call is rejected. - Like the loop above,
parkanswers confirmations only, and raises before asking anyone when the run waits for user input or an external result. on_webhookgoes 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,
parkwithdraws the requests it made and raises. If continuing fails or ends inERROR, 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 setclaimedback to 0. The sweep then goes on from wherever the run stands. UPDATE … RETURNINGneeds SQLite 3.35 or newer. On an older SQLite, claim with anUPDATEand 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.