Microsoft Agent Framework
Mark a Microsoft Agent Framework tool approval_mode="always_require" and answer each function approval request with a person's decision from an inbox.
Microsoft Agent Framework can stop a tool before it runs. Mark the tool approval_mode="always_require" and the run ends with a function approval request instead of a result. You answer it with to_function_approval_response(True) or False and run the agent again in the same session. Who decides, and where, is up to you. This page makes each approval 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.
Agent Framework is Microsoft’s successor to Semantic Kernel and AutoGen. AutoGen is no longer maintained, and Microsoft points new projects here, so this is also the page to follow if you came from AutoGen.
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 approvals with a person’s decision
Install the framework too: pip install agent-framework brings in every provider, and this code needs only agent-framework-core and agent-framework-openai. It ran against agent-framework-core 1.26. The tool is an ordinary tool with approval switched on. The loop around the run asks a person about every call the agent wants to make at once, so they appear side by side, waits for the answers, and sends them back.
import asyncio
import contextlib
from agent_framework import Agent, AgentResponse, AgentSession, Content, Message, tool
from agent_framework.openai import OpenAIChatClient
from variantgate import (
ApprovalClient,
ChangedApprovalError,
NotApprovedError,
VariantGateError,
is_allowed,
is_changed,
)
import shop # your own refund code
approvals = ApprovalClient("support-agent") # reads VARIANTGATE_KEY
@tool(approval_mode="always_require")
def refund_order(order_id: str, amount_eur: str) -> str:
"""Refund an order to the customer's original payment method."""
refund_id = shop.refund(order_id, amount_eur)
return f"Refunded €{amount_eur} for order {order_id} as {refund_id}."
agent = Agent(
client=OpenAIChatClient(model="gpt-5"),
instructions="Help customers with their orders.",
tools=[refund_order],
)
def describe(call: Content) -> dict:
"""What a person sees for one tool call: an action, a summary, an amount."""
args = call.parse_arguments() or {}
if call.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.name}", "summary": f"Run {call.name}", "details": args}
def approval_requests(result: AgentResponse) -> list[Content]:
return [r for r in result.user_input_requests if r.type == "function_approval_request"]
def answer(request: Content, decision: dict) -> tuple[list, bool]:
"""Approve the call only on an unchanged yes; otherwise tell the model why not."""
if not is_allowed(decision):
no = NotApprovedError(decision)
return [request.to_function_approval_response(False), str(no)], False
if is_changed(decision): # a person approved less, or other wording
approvals.report_outcome(decision["id"], "failed", "not done: approved with changes")
no = ChangedApprovalError(decision)
return [request.to_function_approval_response(False), str(no)], False
return [request.to_function_approval_response(True)], True
def record(result: AgentResponse, approved: dict[str, str]) -> None:
"""Tell the record how each approved call went."""
for content in (c for m in result.messages for c in m.contents):
if content.type == "function_result" and content.call_id in approved:
outcome = "failed" if content.exception else "succeeded"
with contextlib.suppress(VariantGateError): # the tool ran: never fail over the record
approvals.report_outcome(approved[content.call_id], outcome, str(content.result))
async def continue_run(session: AgentSession, decided: list[tuple[Content, dict]]) -> AgentResponse:
"""Answer each call with a person's decision, run on, and record the outcomes."""
reply, approved = [], {}
for request, decision in decided:
contents, approves = await asyncio.to_thread(answer, request, decision)
reply += contents
if approves:
approved[request.function_call.call_id] = decision["id"]
result = await agent.run(Message("user", reply), session=session)
await asyncio.to_thread(record, result, approved)
return result
async def run(text: str) -> str:
session = agent.create_session()
result = await agent.run(text, session=session)
while requests := approval_requests(result):
# Ask about every call at once, so a person sees them side by side.
asked = await asyncio.gather(
*(asyncio.to_thread(approvals.ask, **describe(r.function_call)) for r in requests)
)
decisions = await asyncio.gather(
*(asyncio.to_thread(approvals.wait, q, 900) for q in asked)
)
result = await continue_run(session, list(zip(requests, decisions, strict=True)))
return result.text
if __name__ == "__main__":
print(asyncio.run(run("Order 1182 arrived broken. Please refund the €49.")))- An approved call runs. A denied, expired or withdrawn one, or any call while the workspace is paused, is rejected. The model then gets the framework’s “Tool call invocation was rejected” result, and the reason, such as “Not approved: the request is denied”, as text in the same message, so it can tell the customer instead of trying again.
- The framework’s approval is a plain yes or no: it cannot pass the tool a lower amount. So if a person lowers the amount or rewords the request,
answerrejects the call and records that nothing was done. The model is told what was approved and can ask again for that. 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 €20” approve the small ones without anyone waiting.answersays which calls it approved, and after the run goes on,recordfinds those calls’ results and reportssucceeded, orfailedwhen the tool raised. Once the tool has run, a failure to record never fails the run, so nothing tempts the agent into a second refund.- The calls to the API run in a thread, so other runs on the same event loop keep going while a person decides. If the API cannot be reached, the run fails and nothing is refunded. A request still open after 900 seconds is withdrawn and the call rejected, so nobody can approve a call that will never run.
In .NET the same pattern uses ApprovalRequiredAIFunction and ToolApprovalRequestContent; Microsoft’s tool approval guide shows both languages.
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 end with the calls still waiting. An AgentSession turns into a plain dict with to_dict, and the approval requests do too, so you can save both with the request ids and stop. start runs the agent until it needs a person, asks without waiting and saves the run with park. Call resume on every signed webhook about one of the run’s requests. The webhook only says when: resume reads each request with check, and a call is approved only on an unchanged yes. With the code above saved as support.py:
import asyncio
import contextlib
import json
import sqlite3
from collections.abc import Iterator
from agent_framework import AgentResponse, AgentSession, Content
from variantgate import VariantGateError
from support import agent, approval_requests, approvals, continue_run, describe
CLAIM = """UPDATE runs SET claimed = 1
WHERE id = (SELECT run_id FROM asked WHERE request_id = ?) AND claimed = 0
RETURNING id, data"""
@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("runs.db")) as db, db: # commits on the way out
yield db
with database() as db:
db.execute("CREATE TABLE IF NOT EXISTS runs (id TEXT PRIMARY KEY, data TEXT, claimed INT)")
db.execute("CREATE TABLE IF NOT EXISTS asked (request_id TEXT PRIMARY KEY, run_id TEXT)")
async def start(run_id: str, text: str) -> str | None:
"""Run until the agent needs a person. Returns its answer, or None while it waits."""
session = agent.create_session()
return await park(run_id, session, await agent.run(text, session=session))
async def park(run_id: str, session: AgentSession, result: AgentResponse) -> str | None:
"""Ask about the run's calls without waiting, and save it. With no calls, it is done."""
requests = approval_requests(result)
asked = await asyncio.gather(
*(
asyncio.to_thread(approvals.ask, **describe(r.function_call), ttl_seconds=24 * 3600)
for r in requests
)
)
calls = [[r.to_dict(), q["id"]] for r, q in zip(requests, asked, strict=True)]
with database() as db: # one transaction: the old run goes, the new one comes
db.execute("DELETE FROM asked WHERE run_id = ?", (run_id,))
db.execute("DELETE FROM runs WHERE id = ?", (run_id,))
if not calls:
return result.text
saved = json.dumps({"session": session.to_dict(), "calls": calls})
db.execute("INSERT INTO runs VALUES (?, ?, 0)", (run_id, saved))
db.executemany("INSERT INTO asked VALUES (?, ?)", [(q["id"], run_id) for q in asked])
return await resume(asked[0]["id"]) # a rule may have decided before the row was saved
def release(run_id: str) -> None:
with database() as db:
db.execute("UPDATE runs SET claimed = 0 WHERE id = ?", (run_id,))
async def resume(request_id: str) -> str | None:
"""Call on every signed webhook, and from a sweep. Goes on once, when all are decided."""
with database() as db:
row = db.execute(CLAIM, (request_id,)).fetchone() # take the run in one step
if row is None:
return None # unknown, done already, or another delivery has it
run_id, saved = row[0], json.loads(row[1])
try:
decisions = await asyncio.gather(
*(asyncio.to_thread(approvals.check, request_id) for _, request_id in saved["calls"])
)
except VariantGateError:
release(run_id)
raise
if any(decision["status"] == "pending" for decision in decisions):
release(run_id)
return None # the webhook for the last decision tries again
calls = [Content.from_dict(call) for call, _ in saved["calls"]]
session = AgentSession.from_dict(saved["session"])
result = await continue_run(session, list(zip(calls, decisions, strict=True)))
return await park(run_id, session, result) # the agent may need a person again- Webhooks can arrive twice, and a run with two calls gets one per call, so
resumefirst claims the saved run in a singleUPDATE … RETURNING. Only the delivery that claims it goes on, so the run cannot refund twice. - While any of the run’s requests is still pending,
resumeputs the run back and does nothing; the webhook for the last decision continues it. A rule can decide before the run is saved, soparkcallsresumeonce itself after saving. A webhook can also arrive while another delivery holds the claim, so run a sweep every few minutes that callsresumewith one request id of each unclaimed run. - When the continued run asks for another approval,
parkasks and saves it in place of the old one. When it needs none, the run is removed andresumereturns the agent’s answer. - Each call opens its own connection, so webhook handlers and the sweep can run on any thread.
- If continuing itself fails, the run stays claimed rather than going back: the tool may already have run, so look at its requests on the record before you set
claimedback to 0.
When the built-in approval is enough
If the person chatting with the agent is the one who should decide, answer the approval requests 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.