12-factor agents · Factors 6 and 7
Contact humans with tool calls, enforced
AgentGuard® is a hosted gate an agent asks before it moves money or contacts a person. The agent makes one tool call. The answer is allow, held for a person, or blocked, with a signed receipt. This page maps that call to two factors of the 12-factor agents guide and gives you code to run against the public sandbox, with no key.
POST https://agentguard.run/api/gate/authorize
The decision is ordinary deterministic code under the operator's policy. No language model takes part in it.
The two factors, in their authors' words
12-factor agents is a public guide to building reliable agent software, published by HumanLayer and its contributors. Two of its factors describe the problem this gate works on.
Factor 7: Contact humans with tool calls
“Tools for different types of human contact allow for more specificity from the LLM”
Factor 6: Launch/Pause/Resume with simple APIs
“Agents and their orchestrating deterministic code should be able to pause an agent when a long-running operation is needed.”
“often AI orchestrators will allow for pause and resume, but not between the moment of tool selection and tool execution.”
The quotations are unchanged, from the factor 6 and factor 7 documents in that repository, whose content is licensed CC BY-SA 4.0. The rest of this page is ours. The authors of 12-factor agents have not reviewed or endorsed it.
What “enforced” adds
Factor 7 makes asking a person a structured step the agent chooses. That leaves two questions open: what happens when the agent does not choose it, and who makes sure the person who answers is the right one. The gate answers both outside the agent.
| The factor asks for | What the gate does | Guarantee |
|---|---|---|
| A tool call that contacts a human | The agent calls POST /api/gate/authorize (or the MCP tool gate_authorize) before a refund, credit, fee waiver or payout. When the policy holds the action, the answer is escalate and, with a vendor key, an approval is opened for a person. | G01: a hold never executes or signs an allow. |
| The person decides, not the agent | The amount above which a person decides is in the operator's policy. Pinned on the vendor key, it cannot be changed by a request. | G33: an amount above the rule's auto-approve limit is never allowed without a person. G04: a pinned policy wins over a policy in the request. |
| The right person is asked | The approver is the operator's setting on the key. A request that names its own approver is refused. The approval link goes to that approver and is not in the agent's response, unless the operator marked the key as living on a trusted server. Over MCP it is never returned. | G12: the approver is set by the operator and the link never goes back to the agent that asked. |
| The person sees facts, not the agent's pitch | The approval email, text message and page show the action, the amount and the reason the policy held it. They show the operator's own label for the tenant, and the agent's id only as a labelled code. | G34: words an agent chose never reach the person who decides. |
| One answer, on the record | The link works once and expires. The person's decision is a second signed receipt chained to the request. | G11: a held action becomes an allow only through the approver's own link, before it expires, and is decided once. G08: every receipt verifies with the published key. |
| Pause between tool selection and tool execution | The hold sits exactly there. The tool is chosen, the gate answers escalate, and your code does not run the tool. The approval id is all you need to keep. | G01. |
| Resume with a simple API | The agent polls GET /api/gate/approvals/:id/status with its vendor key and gets pending, approved, denied or expired, plus the signed decision once there is one. | G11. |
| Stop everything | An operator can pause a tenant. Every request is then blocked, and a hold that was already waiting cannot be decided until the pause is lifted. | G15: a paused tenant is blocked for everything. G31: no hold is approved or denied while paused. |
The gate also covers contact in the other direction, an agent calling or texting a person: calling hours in the recipient's time zone, a consent reference, per-recipient caps and opt-outs (G05, G06). The last line of the example below is one of those.
Run it: allowed, held, refused
Save this as gate-demo.mjs and run node gate-demo.mjs. It needs Node 18 or later and nothing else. It uses tenant sandbox, where the gate decides and signs and stores nothing.
// gate-demo.mjs: Node 18 or later, no dependencies, no key.
// Tenant "sandbox": the gate decides and signs, and stores nothing.
const GATE = process.env.AGENTGUARD_URL || 'https://agentguard.run';
// The operator's policy. In sandbox it travels with the request.
// With a vendor key the operator pins it on the key and a request cannot change it.
const policy = {
id: 'refunds-v1',
version: 1,
calling_window: { start: '08:00', end: '20:00' },
consent_required: true,
rules: {
issue_refund: {
required_capability: 'payment_execute',
auto_approve_max_cents: 10000, // up to $100.00 runs without a person
review_above_cents: 10000, // above $100.00 a person decides
hard_block_above_cents: 50000, // above $500.00 nobody is asked
},
place_call: { required_capability: 'data_write' },
},
};
async function askGate(action, extra = {}) {
const res = await fetch(`${GATE}/api/gate/authorize`, {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({
tenant_id: 'sandbox',
agent_id: 'refund-bot',
capability_claim: 'payment_execute',
action,
policy,
...extra,
}),
});
return { http: res.status, ...(await res.json()) };
}
// The tool the agent calls. execute() is your own code (the real refund, the real call).
// It runs only when the gate answers allow. A hold, a refusal or no answer: it does not run.
async function guarded(action, execute, extra) {
let gate;
try {
gate = await askGate(action, extra);
} catch {
return { executed: false, decision: 'block', decision_text: 'the gate did not answer' };
}
const { decision, decision_reason, decision_text, receipt } = gate;
if (decision !== 'allow') {
return { executed: false, http: gate.http, decision: decision || 'block', decision_reason, decision_text, error: gate.error, receipt };
}
return { executed: true, http: gate.http, decision, decision_reason, decision_text, receipt, result: await execute() };
}
const refund = (cents) => ({ type: 'issue_refund', amount_cents: cents, currency: 'USD', target_system: 'payments' });
const fakeRefund = async () => 'refund sent'; // stands in for your payment call
const fakeCall = async () => 'call placed'; // stands in for your dialer
const runs = [
['refund $40.00', await guarded(refund(4000), fakeRefund)],
['refund $150.00', await guarded(refund(15000), fakeRefund)],
['refund $900.00', await guarded(refund(90000), fakeRefund)],
// 9:15 PM in the recipient's time zone. Sandbox only: with a key the gate's own clock decides.
['call at 9:15 PM', await guarded(
{ type: 'place_call', recipient_ref: 'rcp_7f3a9c', recipient_tz: 'America/New_York', consent_ref: 'cns_01HZX' },
fakeCall,
{ capability_claim: 'data_write', evaluated_at: '2026-10-19T01:15:00.000Z' },
)],
];
for (const [label, out] of runs) {
console.log(`${label} -> ${out.decision} | ${out.decision_text} | executed: ${out.executed}`);
const r = out.receipt;
if (r) console.log(` signed receipt ${r.receipt_id} (${r.receipt_type})` + (r.human_decision ? `, human_decision: ${r.human_decision}` : ''));
}
Output from the public sandbox on November 10, 2026. Receipt ids differ on every run.
refund $40.00 -> allow | permitted under the policy | executed: true
signed receipt rcpt_9a39492719f60272440bdb03 (money_action_authorization)
refund $150.00 -> escalate | held for a person under the policy | executed: false
signed receipt rcpt_433626dc47283c5bf1622590 (money_action_authorization), human_decision: pending
refund $900.00 -> block | above the per-action limit set in the policy | executed: false
signed receipt rcpt_e2665c36b648cc48b202887d (money_action_authorization)
call at 9:15 PM -> block | outside the calling window set in the policy | executed: false
signed receipt rcpt_80a4bc0a8c07b160e760625d (contact_action_authorization)
Three things to notice. The $40.00 refund ran because the gate said allow. The $150.00 refund did not run: the receipt says human_decision: pending, and in the sandbox no approval is opened because nothing is stored. The $900.00 refund and the late call were refused, and each refusal is signed too.
If your agent speaks MCP, the same request is the tool gate_authorize on https://agentguard.run/api/mcp. Setup is on the hosted MCP page.
Pause and resume, with a key
This part needs a vendor key. Without one there is no tenant to hold an approval for, so the code below exits. With a key, the key names the tenant, the operator's pinned policy decides, and a hold opens an approval.
// gate-keyed.mjs: the same calls with a vendor key. This file needs a key; it does nothing useful without one.
// AGENTGUARD_VENDOR_KEY=agk_vendor_... node gate-keyed.mjs ask 15000
// AGENTGUARD_VENDOR_KEY=agk_vendor_... node gate-keyed.mjs wait apr_...
const GATE = process.env.AGENTGUARD_URL || 'https://agentguard.run';
const KEY = process.env.AGENTGUARD_VENDOR_KEY;
if (!KEY) { console.error('Set AGENTGUARD_VENDOR_KEY. Without a key, run gate-demo.mjs in sandbox.'); process.exit(1); }
const auth = { authorization: `Bearer ${KEY}` };
// No tenant_id and no policy: the key names the tenant, and the operator's pinned policy decides.
async function ask(cents) {
const res = await fetch(`${GATE}/api/gate/authorize`, {
method: 'POST',
headers: { 'content-type': 'application/json', ...auth },
body: JSON.stringify({
agent_id: 'refund-bot',
capability_claim: 'payment_execute',
action: { type: 'issue_refund', amount_cents: cents, currency: 'USD', target_system: 'payments' },
}),
});
return res.json();
}
// Pause: the hold is waiting for a person. Resume: poll until the person has decided.
// The approval link is not in the agent's response. It goes to the approver the operator set on the key.
async function status(approvalId) {
const res = await fetch(`${GATE}/api/gate/approvals/${approvalId}/status`, { headers: auth });
return res.json();
}
async function waitForPerson(approvalId, everyMs = 5000) {
for (;;) {
const s = await status(approvalId);
if (s.status !== 'pending') return s; // approved | denied | expired; s.receipt is the person's signed decision
await new Promise((r) => setTimeout(r, everyMs));
}
}
const [mode, arg] = process.argv.slice(2);
if (mode === 'ask') {
const g = await ask(Number(arg));
console.log(`${g.decision} | ${g.decision_text}` + (g.approval ? ` | approval ${g.approval.id}, link in response: ${'link' in g.approval}` : ''));
} else if (mode === 'status') {
const s = await status(arg);
console.log(`${s.status}` + (s.receipt ? ` | ${s.receipt.receipt_type}: ${s.receipt.decision}, ${s.receipt.decision_text}` : ''));
} else if (mode === 'wait') {
const s = await waitForPerson(arg);
console.log(`${s.status}` + (s.receipt ? ` | ${s.receipt.receipt_type}: ${s.receipt.decision}, ${s.receipt.decision_text}` : ''));
// approved: run the action now, then report its result to POST /api/gate/outcomes with s.receipt.
}
We do not publish output from a customer's tenant. The transcript below is this same file run against the gate's own request handlers on a laptop, with a test key, a test signing key and an in-memory store. It is not production output. The lines that start with # are steps taken by the operator or the approver, not by the agent, and their response bodies are trimmed to the fields shown.
$ node gate-keyed.mjs ask 4000
allow | permitted under the policy
$ node gate-keyed.mjs ask 15000
escalate | held for a person under the policy | approval apr_a1cdf9e31c108ce6cc44, link in response: false
$ node gate-keyed.mjs status apr_a1cdf9e31c108ce6cc44
pending
# the operator pauses the tenant (administered by AgentGuard, not possible with a vendor key)
$ node gate-keyed.mjs ask 4000
block | tenant paused by operator
# the approver uses their link while the tenant is paused
HTTP 409 {"error":"tenant_paused","detail":"This account is paused. No decision is taken while it is paused."}
$ node gate-keyed.mjs status apr_a1cdf9e31c108ce6cc44
pending
# the operator lifts the pause for the tenant (administered by AgentGuard, not possible with a vendor key)
# the approver uses their link and approves
HTTP 200 {"ok":true,"status":"approved","decision":"allow","receipt":{"receipt_type":"human_review_decision","decision_reason":"human_approved","human_decision":"approved","previous_receipt_id":"rcpt_1bb18ea9c889a852f785ecb8"}}
# the same link, used a second time
HTTP 409 {"error":"already_decided"}
$ node gate-keyed.mjs wait apr_a1cdf9e31c108ce6cc44 (started before the approval)
approved | human_review_decision: allow, permitted by a person under the policy
# decision receipt verifies with the published key: true
# a request that names its own approver
HTTP 400 {"error":"approver_set_by_operator"}
Reading it against factor 6:
- Pause. The $150.00 refund is held. The response carries an approval id and no link. The agent's work on that refund stops there.
- Resume.
waitForPersonreturns when the approver has decided. Onapprovedyour code runs the refund and reports the result toPOST /api/gate/outcomeswith the decision receipt. The gate does not call your agent back today: the agent polls. - A paused tenant. While the tenant is paused, a $40.00 refund the policy would allow is blocked with the text “tenant paused by operator”, and the approver's link answers
409 tenant_paused. The hold stays pending. When the pause is lifted the same link works, once.
The pause itself is not something a vendor key can do. Today AgentGuard sets it on the operator's request through an administered endpoint. The full contract, with approvals, fleet limits and pause, is on the vendors page.
How these claims are checked
Each guarantee named on this page has a property test that runs against the gate's real request handlers on every change. A property test generates requests instead of checking a few examples, and a change that breaks a guarantee fails a required check.
These five have also been checked against production:
- An action whose type, currency or target system is not a plain code is refused, and nothing is decided, signed or stored from it.
- A hold that was waiting when its tenant was paused cannot be approved.
- The auto-approve limit holds under a vendor key.
- Words an agent chose do not reach the approver's page or email.
- An action with no matching rule is blocked. The default-deny bypass found on November 3, 2026 is closed.
You can check the receipts yourself. Each one is signed with Ed25519 and verifies at agentguard.run/verify against the key published at /.well-known/jwks.json. Change one field and verification fails.
The scorecard lists every guarantee with its test and whether it has been checked on production. The guarantees file has the full wording.
What the gate does not do
- It does not launch, run or store your agent. Launching, and keeping the state you resume from, stay in your code. The gate keeps the approval and its signed decision.
- It does not run the refund, the payout or the call. Your code does, and only your code can make
execute()wait for allow. Theguardedfunction above is that wiring. An agent that can reach the payment API some other way is not stopped by a gate it never asks. - It does not read what the agent or the customer said. Requests carry action types, amounts and references. A request with a content field or a string over 256 characters is refused.
- It does not decide whether a refund is right. It applies the operator's limits, routes the hold to the operator's approver and signs what happened.
To try it with your own policy, the vendors page has the sandbox, the policy fields and how to ask for a pilot key.