Docs
SDK quickstart
Five minutes from “my agent can issue refunds” to “my agent asks first”. The SDK is a thin client — every decision happens on the server.
1. Install
npm install @agentlatch/sdkIn this repository the SDK lives in packages/sdk and builds with npm run sdk:build (tsup → ESM + CJS + types).
2. Create an API key
In the dashboard open your project → API keys → Create key. The key is shown exactly once; we store only a SHA-256 hash. Keep it server-side, next to your agent.
AGENTLATCH_API_KEY=al_live_••••••••••••••••••••••••••••••••
AGENTLATCH_BASE_URL=https://agents.mauricegarcia.com3. Guard an action
import { AgentLatch, AgentLatchDeniedError } from "@agentlatch/sdk";
const latch = new AgentLatch({
apiKey: process.env.AGENTLATCH_API_KEY!,
baseUrl: process.env.AGENTLATCH_BASE_URL,
agentId: "support-bot-7",
redact: ["card_number"], // masked in dashboard, Discord & audit log
});
export async function refund(args: { amount: number; chargeId: string; card_number?: string }) {
try {
return await latch.guard("refund.create", args, () => payments.refund(args.chargeId, args.amount), {
onPending: (r) => console.log("waiting for approval", r.id),
});
} catch (err) {
if (err instanceof AgentLatchDeniedError) return { blocked: true, reason: err.request.reason };
throw err;
}
}guard()submits the action, waits while it is held (long-poll + backoff, default timeout 10 min), consumes the single-use approval, then runs your function.- Denied, auto-denied or expired →
AgentLatchDeniedError. Timeout →AgentLatchTimeoutError. Your function never runs in either case. omit: ["field"]strips a field before it leaves your process (policies can't see it either).
4. Write policies
Policies match an action glob, an agent glob and argument conditions. Highest priority wins; at equal priority deny beats require approval beats allow. If nothing matches, the request is held for a human.
{
"name": "Hold refunds over $100",
"priority": 50,
"effect": "require_approval",
"match": {
"action": "refund.*",
"agent": "*",
"conditions": [{ "field": "amount", "op": "gt", "value": 100 }]
}
}| Operator | Example |
|---|---|
| gt / gte / lt / lte | amount > 100 |
| eq / neq / in / not_in | env in [staging, dev] |
| domain_in / domain_not_in | to domain not in [example.com] |
| contains / matches (glob) | command contains "rm -rf" |
| exists / not_exists | dry_run exists |
Use the Test a request panel in the policy editor to dry-run a request before saving.
5. Approve
Held requests appear in Approvals (and Discord, if connected). Reviewers see the action, masked arguments, agent, matched policy and risk notes, then choose Allow once, Allow for N minutes (repeat calls of the same action by the same agent auto-allow until the grant ends) or Deny with a reason.
REST API
All agent endpoints take Authorization: Bearer <api key> and are rate-limited per key.
POST /api/v1/requests
{ "agentId": "support-bot-7", "action": "refund.create", "args": { "amount": 250 }, "ttlSeconds": 600 }
→ 201 { "id": "…", "status": "pending" | "auto_allowed" | "auto_denied", "reason": "…" }
GET /api/v1/requests/:id?wait=25 # long-poll while pending (max 25 s)
→ 200 { "id": "…", "status": "allowed", "consumed": false, … }
POST /api/v1/requests/:id/consume # single-use; replays get 409
→ 200 { "ok": true } | 409 { "ok": false, "error": { "code": "already_consumed" } }Frameworks
const tools = {
"refund.create": latch.tool("refund.create", (a: { amount: number; charge: string }) => payments.refund(a)),
"email.send": latch.tool("email.send", (a: { to: string; subject: string; body: string }) => mailer.send(a)),
};
for (const call of message.tool_calls ?? []) {
const result = await tools[call.function.name](JSON.parse(call.function.arguments))
.catch((e) => (e instanceof AgentLatchDeniedError ? `Blocked: ${e.request.reason}` : Promise.reject(e)));
messages.push({ role: "tool", tool_call_id: call.id, content: JSON.stringify(result) });
}const deleteFile = tool((input) => latch.guard("file.delete", input, () => fs.rm(input.path)), {
name: "delete_file", description: "Delete a file", schema: z.object({ path: z.string() }),
});Run the example locally
With no environment variables the app runs in demo mode with an in-memory store and a public, demo-only key.
npm install
npm run devnpm run sdk:example
# then approve the held refund at
# http://localhost:3000/app/projects/6d0c1f8e-0000-4000-8000-00000000a001/approvalsDemo key: al_demo_LocalDevOnlyNotASecret0001 — only valid against the synthetic demo store, never in a configured deployment.
Limits
- AgentLatch only protects actions routed through the SDK/API; it cannot stop an agent that bypasses it.
- It is not a sandbox — pair it with least-privilege credentials.
- Discord notifications open the dashboard; there are no unauthenticated one-click approvals.