Skip to content
AgentLatch

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

terminal
npm install @agentlatch/sdk

In 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.

.env
AGENTLATCH_API_KEY=al_live_••••••••••••••••••••••••••••••••
AGENTLATCH_BASE_URL=https://agents.mauricegarcia.com

3. Guard an action

refund-tool.ts
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.

policy (JSON stored in policies.match)
{
  "name": "Hold refunds over $100",
  "priority": 50,
  "effect": "require_approval",
  "match": {
    "action": "refund.*",
    "agent": "*",
    "conditions": [{ "field": "amount", "op": "gt", "value": 100 }]
  }
}
Condition operators
OperatorExample
gt / gte / lt / lteamount > 100
eq / neq / in / not_inenv in [staging, dev]
domain_in / domain_not_into domain not in [example.com]
contains / matches (glob)command contains "rm -rf"
exists / not_existsdry_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.

http
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

openai-tools.ts
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) });
}
langchain-tool.ts
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.

terminal 1
npm install
npm run dev
terminal 2
npm run sdk:example
# then approve the held refund at
# http://localhost:3000/app/projects/6d0c1f8e-0000-4000-8000-00000000a001/approvals

Demo 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.

See it in the live demo →