SDKs#
Clients over the REST API. Everything they do you can do with curl; they add retries with backoff, the long-poll loop, file uploads, idempotency keys and the typed shapes from the contract.
Both read their configuration the same way as the CLI: an explicit argument, then AGENTSFRAME_KEY and AGENTSFRAME_API, then the config file written by frame login, then the default API.
TypeScript#
npm install agentsframeimport { Frame } from "agentsframe";
const frame = new Frame(); // or new Frame({ key: "afk_w_…", api: "…" })
// approval: resolves when you answer (wait is on by default)
const { approved, outcome, comment } = await frame.approve("Deploy v2.3.1?", {
body: "212 tests passed",
class: "deploy.production",
timeout: 900, // seconds to wait, also the card's time to live
onExpire: "deny",
});
if (approved) await deploy();
// question: options shorthand, or typed fields
const { answer } = await frame.ask("Which thumbnail?", {
options: [{ id: "a", label: "Bold title" }, { id: "b", label: "Close-up" }],
});
// results, progress, notes, metrics, boards
await frame.showResult("./render.mp4", { title: "Episode 12", review: true });
const job = await frame.progress("Nightly import", { steps: ["Extract", "Load"], value: 0 });
await job.update(0.5, "Loading");
await job.stepDone("Extract");
await job.done("Imported"); // or job.fail("Load failed")
await frame.note("Backups verified.");
await frame.metric("youtube.subscribers", 48210, { format: "compact", better: "up" });
const boards = await frame.boards.list();
await frame.boards.patchTile("brd_home", "til_subs", { tint: "green" });
// lower level: one method per endpoint
const page = await frame.listCards({ state: "open", limit: 20 });
const { card, outcome: how } = await frame.wait("crd_8f2k1x", { timeout: 600 });ask, approve and showResult (with review) wait by default; pass wait: false to create the card and return at once with outcome: "timeout", then collect the answer with frame.wait(card.id). The result's outcome is answered, expired, withdrawn, done or timeout. Errors throw FrameError with code, status, hint and the request id. The package exports every type from contract/types.ts, verifyWebhook() and signWebhook().
Python#
pip install agentsframefrom agentsframe import Frame
frame = Frame() # or Frame(key="afk_w_…", api="…")
result = frame.approve("Deploy v2.3.1?", body="212 tests passed",
timeout=900, on_expire="deny", **{"class": "deploy.production"})
if result.approved:
deploy()
answer = frame.ask("Which thumbnail?", options=[{"id": "a", "label": "Bold title"}, {"id": "b", "label": "Close-up"}])
print(answer.answer)
frame.show_result("./render.mp4", title="Episode 12", review=True)
job = frame.progress("Nightly import", steps=["Extract", "Load"], value=0)
job.update(0.5, "Loading")
job.step_done("Extract")
job.done("Imported") # or job.fail("Load failed")
frame.note("Backups verified.")
frame.metric("youtube.subscribers", 48210, format="compact", better="up")
boards = frame.list_boards()
frame.patch_tile("brd_home", "til_subs", {"tint": "green"})Module-level shortcuts (agentsframe.ask, approve, show_result, progress) build a Frame() from the environment for one-off scripts. Python reserves class, so pass it as **{"class": "…"}. The client is synchronous and needs Python 3.10 or newer. Errors raise agentsframe.FrameError.
Webhook verification helpers#
Both SDKs ship the signature check described in the API reference. They return a result instead of throwing, so you decide the response:
import { verifyWebhook } from "agentsframe";
const check = verifyWebhook({ secret: process.env.WEBHOOK_SECRET!, signature: req.headers["frame-signature"] as string, body: rawBody });
if (!check.valid) return res.sendStatus(401); // check.reason: malformed_header | bad_signature | stalefrom agentsframe import verify_webhook
check = verify_webhook(WEBHOOK_SECRET, request.headers["Frame-Signature"], raw_body)
if not check.valid:
abort(401) # check.reason: malformed_header | bad_signature | staleVersioning#
The clients follow the API: /v1 only adds fields, so an old client keeps working. Both send User-Agent: agentsframe-<client>/<version>.