smolagents

Make a smolagents tool ask a person before it refunds or deletes, in a ToolCallingAgent or a CodeAgent, inside the run or hours later by webhook.

smolagents has no approval step of its own, and its step callbacks run after a step’s tools have run, so they can report a refund but not stop one. The place to ask is the tool itself: the refund tool asks VariantGate, waits while a person approves or denies it from a phone, an email link or Slack, and refunds only on a yes. The same tool works in a ToolCallingAgent and a CodeAgent.

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. Ask inside the tool

Install smolagents too: pip install smolagents. This code ran against smolagents 1.26.0 on Python 3.12. wait_for_approval asks, waits up to 900 seconds, and returns only on an approval of exactly what was asked. Anything else raises, and the tool turns that into an answer for the model.

import contextlib

from smolagents import tool
from variantgate import ApprovalApiError, ApprovalClient, NotApprovedError, VariantGateError

import shop  # your own refund code

approvals = ApprovalClient("support-agent")  # reads VARIANTGATE_KEY


class EndRun(BaseException):
    """Ends the run. A BaseException, like smolagents' own final_answer, so no
    except Exception, in smolagents or in code the model wrote, turns it into a retry."""


@tool
def refund_order(order_id: str, amount_eur: str) -> 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".
    """
    try:
        decision = approvals.wait_for_approval(
            "payment.refund",
            f"Refund €{amount_eur} for order {order_id}",
            amount=amount_eur,
            currency="EUR",
            details={"order": order_id},
            timeout=900,
        )
    except NotApprovedError as no:  # denied, expired, paused, or approved with changes
        return f"Not refunded. {no}"
    except ApprovalApiError as error:  # nobody could be asked: end the run
        raise EndRun(f"could not ask for approval: {error}. Nothing was refunded") from error
    try:
        refund_id = shop.refund(order_id, amount_eur)
    except Exception as error:  # approved, but it failed: record it, and no retry
        with contextlib.suppress(VariantGateError):
            approvals.report_outcome(decision["id"], "failed", f"refund raised, check the order: {error}")
        raise EndRun(f"the refund failed: {error}. Check the order before retrying") from error
    with contextlib.suppress(VariantGateError):  # the money moved: never fail the tool over the record
        approvals.report_outcome(decision["id"], "succeeded", f"refund {refund_id}")
    return f"Refunded €{amount_eur} for order {order_id}."
  • On a yes the refund runs and the record gets its refund id. 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 itself fails, the record says so and the run ends, rather than the model trying again under a new request.
  • Denied, expired, or approved while the workspace is paused: the model gets “Not refunded. Not approved: the request is denied.” as the tool’s result, so it tells the customer instead of looking for another way. A request still open after 900 seconds is withdrawn, so nobody approves it after the agent stopped listening.
  • If a person lowers the amount or rewords the request, nothing is refunded and the record says so. The model reads what was approved, such as “for at most 20.00 EUR”, and can ask again for that.
  • If the API cannot be reached or refuses the call, nobody has said no, so the tool does not answer as if they had. smolagents hands any ordinary exception back to the model with “Please try again or use another tool”, and in a CodeAgent an except in the code the model wrote could swallow it. EndRun gets past both and ends the run, with nothing refunded. The same exception ends the run when a refund fails, so read its message to tell the cases apart: a refund that raised may still have gone through.
  • State the amount, and a rule such as “always allow payment.refund up to €20” approves the small ones at once.

3. Run either kind of agent

from smolagents import CodeAgent, InferenceClientModel, ToolCallingAgent

model = InferenceClientModel()  # or LiteLLMModel, OpenAIModel, TransformersModel

# The model calls tools as JSON.
agent = ToolCallingAgent(tools=[refund_order], model=model)

# Or the model writes Python that calls the tool. A person can take longer than
# the 30 seconds smolagents gives one block of code, so take that limit off.
agent = CodeAgent(tools=[refund_order], model=model, executor_kwargs={"timeout_seconds": None})

try:
    print(agent.run("Order 1182 arrived broken. Please refund the €49."))
except EndRun as error:
    print(f"Stopped: {error}.")

A CodeAgent does not call tools one at a time: the model writes Python, and that code can call refund_order in a loop, behind an if, or twice in one block. There is no single call to catch before the code runs, and approving the code itself would ask a person to review Python. Every refund still passes through the tool’s own function, which is why the gate lives there.

Take off the 30-second limit as shown. It does not stop a call that is still waiting: smolagents lets the code finish, refund included, and then tells the model the step failed, which invites it to refund again. The code here uses the default local executor, where the tool runs in your process. A remote executor (E2B, Docker, Modal) copies tools into the sandbox beside the model’s code, so keep tools that move money out of one.

When the answer may take hours

For a decision that may take longer than a run should wait, let the tool ask with a longer ttl_seconds and return at once. The run ends with “Asked a person, request id …”, and the refund happens later, when a signed webhook says the request was decided. This uses approvals, EndRun and the imports from the first example.

import sqlite3

from variantgate import ChangedApprovalError, is_allowed, is_changed

CLAIM = """UPDATE refunds SET claimed = 1 WHERE request_id = ? AND claimed = 0
    RETURNING order_id, amount_eur"""


@contextlib.contextmanager
def database():
    """Your database. Each call is one transaction, committed on the way out."""
    with contextlib.closing(sqlite3.connect("refunds.db")) as db, db:
        yield db


with database() as db:
    db.execute("""CREATE TABLE IF NOT EXISTS refunds
        (request_id TEXT PRIMARY KEY, order_id TEXT, amount_eur TEXT, claimed INT)""")


@tool
def refund_order(order_id: str, amount_eur: str) -> str:
    """Refund an order to the customer's original payment method, once a person approves.

    Args:
        order_id: The order to refund, such as "1182".
        amount_eur: The amount in euros, such as "49.00".
    """
    try:
        asked = approvals.ask(
            "payment.refund",
            f"Refund €{amount_eur} for order {order_id}",
            amount=amount_eur,
            currency="EUR",
            details={"order": order_id},
            ttl_seconds=24 * 3600,
        )
    except ApprovalApiError as error:
        raise EndRun(f"could not ask for approval: {error}. Nothing was refunded") from error
    try:
        with database() as db:
            db.execute("INSERT INTO refunds VALUES (?, ?, ?, 0)", (asked["id"], order_id, amount_eur))
    except sqlite3.Error as error:  # unsaved, nobody could finish it: take it back
        with contextlib.suppress(VariantGateError):
            approvals.withdraw(asked["id"])
        raise EndRun(f"could not save the request: {error}. Nothing was refunded") from error
    try:
        done = finish(asked["id"])  # a rule may have answered before the row was saved
    except (VariantGateError, sqlite3.Error):
        done = None  # the webhook or the sweep finishes it
    except Exception as error:  # the refund itself failed: no retry
        raise EndRun(f"after asking ({asked['id']}): {error}") from error
    return done or f"Asked a person, request id {asked['id']}. Not refunded yet."


def finish(request_id: str) -> str | None:
    """Call for every signed webhook. Refunds at most once, and only on an unchanged yes."""
    with database() as db:
        row = db.execute(CLAIM, (request_id,)).fetchone()  # take it in one step
    if row is None:
        return None  # not ours, done already, or another delivery has it
    order_id, amount_eur = row
    try:
        decision = approvals.check(request_id)  # the webhook says when; this says what
    except VariantGateError:
        release(request_id)
        raise
    if decision["status"] == "pending":
        release(request_id)
        return None
    if not is_allowed(decision):
        return f"Not refunded for order {order_id}. {NotApprovedError(decision)}"
    if is_changed(decision):
        with contextlib.suppress(VariantGateError):
            approvals.report_outcome(request_id, "failed", "not done: approved with changes")
        return f"Not refunded for order {order_id}. {ChangedApprovalError(decision)}"
    try:
        refund_id = shop.refund(order_id, amount_eur)
    except Exception as error:  # stays claimed: look at the record before retrying
        with contextlib.suppress(VariantGateError):
            approvals.report_outcome(request_id, "failed", f"refund raised, check the order: {error}")
        raise
    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}."


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


def on_webhook(request_id: str) -> None:
    """From your signed-webhook handler, or a job it queues."""
    done = finish(request_id)
    if done:
        follow_up.run(f"{done} Tell the customer.")  # a new run, without the refund tool
  • The webhook only says when. finish reads the request with check and refunds only when allowed is true and nothing was changed, so a pause after the decision still stops it.
  • Webhooks can arrive twice. finish claims the row in a single UPDATE … RETURNING before it reads or acts, so only one delivery refunds. A request still pending, or an API that cannot be reached, gives the claim back for the next delivery.
  • The tool calls finish once itself, because a rule may approve the request before the row is saved, and that webhook would find nothing. A delivery can also arrive while another holds the claim, so run a sweep every few minutes that calls finish for each unclaimed row.
  • Once a request exists, no error goes back to the model as a plain failure, since smolagents would tell it to try again and a second request could mean a second refund. A row that cannot be saved withdraws the request and ends the run. An API or database that fails while finishing leaves the row for the webhook or the sweep. A refund that fails ends the run with EndRun and is recorded as failed with its error; it may still have gone through, so check the order. A row left claimed, for example because releasing it failed, is for a person to look at.
  • UPDATE … RETURNING needs SQLite 3.35 or newer. On an older SQLite, claim with an UPDATE and check that it changed one row.
  • The model never decides whether to refund here: finish does exactly what was asked and approved. The new run only tells the customer, so give follow_up an agent without the refund tool.

When to add VariantGate

If you run the agent yourself at a terminal, an input() prompt inside the tool is enough. VariantGate 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.