OpenAI Agents SDK
Make an OpenAI Agents SDK function tool ask a person first, using the HTTP API.
In the OpenAI Agents SDK an agent acts through function tools. Put the approval inside the tool, before the call that changes something, and the action cannot happen without a person’s yes.
1. A small helper
Save this as approvals.py. It needs requests and the agent key in VARIANTGATE_KEY.
import os
import requests
API_URL = os.environ.get("VARIANTGATE_API_URL", "https://api.variantgate.com")
HEADERS = {"Authorization": f"Bearer {os.environ['VARIANTGATE_KEY']}"}
def ask_person(action: str, summary: str, **fields) -> dict:
"""Ask for approval and wait until the request is no longer pending."""
body = {"agent": "support-agent", "action": action, "summary": summary,
"wait_seconds": 30, **fields}
response = requests.post(f"{API_URL}/v1/requests", headers=HEADERS,
json=body, timeout=40)
response.raise_for_status()
request = response.json()
while request["status"] == "pending":
response = requests.get(f"{API_URL}/v1/requests/{request['id']}",
headers=HEADERS, params={"wait_seconds": 30},
timeout=40)
response.raise_for_status()
request = response.json()
return request
def report(request_id: str, outcome: str, note: str = "") -> None:
"""Say how the approved action went: "succeeded" or "failed"."""
response = requests.post(f"{API_URL}/v1/requests/{request_id}/outcome",
headers=HEADERS, json={"outcome": outcome, "note": note},
timeout=10)
response.raise_for_status()2. Ask inside the function tool
from agents import Agent, Runner, function_tool
from approvals import ask_person, report
@function_tool
def refund_order(order_id: str, amount_eur: str) -> str:
"""Refund an order to the customer's original payment method."""
summary = f"Refund €{amount_eur} for order {order_id}"
answer = ask_person(
"payment.refund",
summary,
amount=amount_eur,
currency="EUR",
details={"order": order_id},
)
if answer["allowed"] is not True:
return "Not refunded: a person did not approve it."
if answer["approved_summary"] != summary:
# A person reworded it, perhaps to another order. This tool can only
# do what it asked for, so it does nothing.
report(answer["id"], "failed", "not done: approved with other wording")
return f"Not refunded. Approved instead: {answer['approved_summary']}"
amount = answer["approved_amount"] # a person may have lowered it
shop.refund(order_id, amount)
report(answer["id"], "succeeded")
return f"Refunded €{amount} for order {order_id}."
agent = Agent(
name="Support",
instructions="Help customers with their orders.",
tools=[refund_order],
)
result = Runner.run_sync(agent, "Order 1182 arrived broken. Please refund it.")
print(result.final_output)- Act only when
allowedistrue. Pending, denied, expired and withdrawn all mean stop, and so does a paused workspace. - Refund
approved_amount, never the amount asked: a person may approve a partial refund. - On a no, return a sentence the model can pass on, rather than raising.
- Write a rule such as “always allow
payment.refundup to €20” and small refunds go through at once, while larger ones wait for a person.
In TypeScript
The JavaScript version of the SDK works the same way. This helper uses only fetch; call askPerson at the top of the tool’s execute function.
const API_URL = process.env.VARIANTGATE_API_URL ?? "https://api.variantgate.com";
const HEADERS = {
authorization: `Bearer ${process.env.VARIANTGATE_KEY}`,
"content-type": "application/json",
};
interface Answer {
allowed: boolean;
/** Once approved: the most money the action may move. Act on this. */
approved_amount: string | null;
/** Once approved: the wording to act on. */
approved_summary: string | null;
/** True when a person approved a narrower version than was asked. */
changed: boolean;
id: string;
status: "pending" | "approved" | "denied" | "expired" | "withdrawn";
}
async function call(path: string, init?: RequestInit): Promise<Answer> {
const response = await fetch(`${API_URL}${path}`, { ...init, headers: HEADERS });
if (!response.ok) {
throw new Error(`approvals API answered ${response.status}`);
}
return (await response.json()) as Answer;
}
/** Asks for approval and waits until the request is no longer pending. */
export async function askPerson(action: string, summary: string, fields = {}) {
const body = { agent: "support-agent", action, summary, wait_seconds: 30, ...fields };
let answer = await call("/v1/requests", { body: JSON.stringify(body), method: "POST" });
while (answer.status === "pending") {
answer = await call(`/v1/requests/${answer.id}?wait_seconds=30`);
}
return answer;
}Or use the TypeScript client, whose guard asks, waits, runs your function only on a yes and reports the outcome.