SDK and command line

TypeScript and Python clients, a command for scripts and CI, and hooks that put every tool call through approval.

Install

Both packages are served from this site for now. They will move to npm as @variantgate/agent and to PyPI as variantgate; the code stays the same. Neither has any dependencies.

# TypeScript and JavaScript
npm install https://variantgate.com/sdk/variantgate-agent-latest.tgz

# Python 3.9 or newer
pip install https://variantgate.com/sdk/variantgate-latest.tar.gz

The Python client and the variantgate command read the agent key from VARIANTGATE_KEY, and the address from VARIANTGATE_API_URL, which defaults to the hosted service. The TypeScript client takes both as options, as below.

Both fail closed. Pending, denied, expired, withdrawn, a paused workspace or agent, a timeout and an error all mean your code does not run.

TypeScript

guard asks, waits for the answer, and runs your function only on a yes. Afterwards it reports whether the function succeeded, so the record shows what was done. Anything but a yes throws NotApprovedError and your function never runs.

import { ApprovalClient } from "@variantgate/agent";

const approvals = new ApprovalClient({
  agent: "billing-bot",
  apiUrl: process.env.VARIANTGATE_API_URL ?? "https://api.variantgate.com",
  key: process.env.VARIANTGATE_KEY ?? "",
});

await approvals.guard(
  {
    action: "payment.refund",
    summary: "Refund €49.00 to ana@example.com for order 1182",
    amount: "49.00",
    currency: "EUR",
  },
  () => stripe.refunds.create({ payment_intent: order.paymentId })
);
ask(request, wait)
Ask, optionally waiting up to 30 seconds.
check(id, wait)
Read the answer, optionally waiting.
waitForDecision(decision)
Wait until it is decided; withdraw it if time runs out.
withdraw(id)
Take back a request nobody has decided.
reportOutcome(id, outcome, note)
Say whether the approved action succeeded.
verifyWebhook(secret, headers, body)
Check a signed webhook and return its event. Import it from @variantgate/agent/webhook.

Python

require_approval wraps a function, plain or async. Each call asks, waits, runs the function only on a yes, and reports how it went. Any field can be a function of the call’s arguments, so the summary names the real order and amount.

from variantgate import require_approval

@require_approval(
    "payment.refund",
    lambda order: f"Refund €{order.total} to {order.email} for order {order.id}",
    amount=lambda order: order.total,
    currency="EUR",
)
def refund(order):
    return stripe.Refund.create(payment_intent=order.payment_id).id

The same check works as a with block. Anything but a yes raises NotApprovedError before the block starts; an unreachable service raises ApprovalApiError. Both are VariantGateErrors. A key that may not ask for the action raises OutOfScopeError, an ApprovalApiError that asking again will not fix (see Agent keys). An approval of a changed version raises ChangedApprovalError, unless the block passes accept_changes=True and does only approved_summary, for at most approved_amount.

from variantgate import NotApprovedError, require_approval

try:
    with require_approval("deploy.production", "Deploy v2.14 to production") as approval:
        deploy("v2.14")
        approval.note = "deployed v2.14"
except NotApprovedError as refused:
    print(refused)  # Not approved: the request is denied (not on a Friday).

Agent tools

Put the check on the function that does the work, under the framework’s tool, and turn a refusal into an answer the model reads. This is LangChain; the OpenAI Agents SDK, CrewAI and plain tool loops work the same way.

from langchain_core.tools import tool
from variantgate import VariantGateError, require_approval

@require_approval(
    "email.send",
    lambda to, subject, body: f"Email {to}: {subject}",
    details=lambda to, subject, body: {"to": to, "body": body[:1000]},
)
def deliver(to: str, subject: str, body: str) -> str:
    return mailer.send(to=to, subject=subject, body=body).id

@tool
def send_email(to: str, subject: str, body: str) -> str:
    """Send an email to a customer."""
    try:
        return f"Sent, message {deliver(to, subject, body)}."
    except VariantGateError as refused:
        # Tell the model, so it stops instead of looking for another way.
        return f"Not sent. {refused} Do not try another way to send it."

The client

from variantgate import ApprovalClient, is_allowed

approvals = ApprovalClient("billing-bot")  # VARIANTGATE_KEY from the environment

asked = approvals.ask("email.send", "Send the March invoice to Acme", wait_seconds=30)
decision = approvals.wait(asked, timeout=120)
if is_allowed(decision):
    send_invoice()
    approvals.report_outcome(decision["id"], "succeeded", "message 42")
ask(action, summary, ...)
Ask, optionally waiting up to 30 seconds.
check(id, wait_seconds)
Read the answer, optionally waiting.
wait(decision, timeout)
Wait until it is decided; withdraw it if time runs out.
withdraw(id)
Take back a request nobody has decided.
report_outcome(id, outcome, note)
Say whether the approved action succeeded.
guard(act, action, summary, ...)
Ask, wait, run act only on a yes, and report how it went.
verify_webhook(secret, headers, body)
Check a signed webhook and return its event; raises WebhookVerificationError otherwise.

A webhook says that something happened, never that the agent may act: after verifyWebhook or verify_webhook, read the answer with check and act only on a yes. See Webhooks.

The command line

Both packages install the variantgate command. variantgate run runs a command only after a yes, passes on its exit code, and reports the outcome. variantgate ask exits 0 on a yes, 1 otherwise, 2 on a mistake or an unreachable service, and 3 when the yes was for a changed version, which it prints.

variantgate run --action deploy.production \
  --summary "Deploy v2.14 to production" -- ./deploy.sh v2.14

In a GitHub Actions job, without installing anything first:

- name: Wait for approval, then deploy
  env:
    VARIANTGATE_KEY: ${{ secrets.VARIANTGATE_KEY }}
  run: npx -y https://variantgate.com/sdk/variantgate-agent-latest.tgz run --action deploy.production --summary "Deploy ${{ github.sha }}" -- ./deploy.sh

Or with Python:

- name: Wait for approval, then migrate
  env:
    VARIANTGATE_KEY: ${{ secrets.VARIANTGATE_KEY }}
  run: |
    pip install https://variantgate.com/sdk/variantgate-latest.tar.gz
    variantgate run --action db.migrate --summary "Migrate production to ${{ github.sha }}" -- ./migrate.sh

Approve every tool call (hooks)

Skills and tools rely on the model choosing to ask. A hook does not: it runs before every matching tool call, asks, and lets the call through only on a yes. Use it for the tools that matter, such as shell commands, not for everything.

Install the command once:

npm install --global https://variantgate.com/sdk/variantgate-agent-latest.tgz

Claude Code, in ~/.claude/settings.json or the project’s .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "variantgate hook claude-code", "timeout": 180 }
        ]
      }
    ]
  }
}

Codex, in ~/.codex/config.toml. Codex asks you to trust a new hook under /hooks before it runs.

[[hooks.PreToolUse]]
matcher = "^Bash$"
[[hooks.PreToolUse.hooks]]
type = "command"
command = "variantgate hook codex"
timeout = 180
  • The hook waits up to two minutes for a person. Set VARIANTGATE_HOOK_WAIT to change it, in seconds, and keep the hook’s timeout (180 above) longer than that wait.
  • A request nobody answers in time is withdrawn and the call is denied.
  • If the service cannot be reached, Claude Code falls back to its own permission prompt. Codex has no such prompt for hooks, so there the call is denied.
  • If the key may not ask for the action, the call is denied in both, with the reason.
  • A hook that times out or cannot run, such as when variantgate is not installed, does not stop the call: Claude Code goes on with its own permission settings, and Codex documents only a denial as blocking. On Claude Code 2.1.295 or later, add "onFailure": "block" to the hook to deny the call instead.

Requests from the hook use actions such as shell.run, file.write and mcp.github.create_issue, so rules can let routine ones through.