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.gzThe 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).idThe 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.14In 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.shOr 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.shApprove 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.tgzClaude 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_WAITto change it, in seconds, and keep the hook’stimeout(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
variantgateis 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.