SDK reference

Install

npm install @aegis/agent-sdk

Initialize

import { Aegis } from "@aegis/agent-sdk";

const aegis = new Aegis({
  apiKey: process.env.AEGIS_API_KEY!,
  baseUrl: process.env.AEGIS_BASE_URL!, // e.g. "https://app.yourcompany.com"
});

Get an API key from your Aegis dashboard’s Developers → API Keys.

Report an event

track() reports an action your agent already took — it does not ask permission.

await aegis.track({
  agent: "finance-agent",
  eventType: "TOOL_CALL",
  action: "invoice.read",
  resource: "invoice",
  status: "SUCCESS",
  metadata: { invoiceId: "inv_123" },
});

Ask for authorization

authorize() asks Aegis for a decision before your agent acts. The result is a discriminated union on decision ("ALLOW" | "BLOCK" | "REQUIRE_APPROVAL"), so TypeScript narrows the rest of the fields once you check it. The SDK never executes anything on your behalf — your code always makes the final call:

const auth = await aegis.authorize({
  agent: "finance-agent",
  action: "refund.issue",
  resource: "payment",
  context: { amount: 1250 },
});

if (auth.decision === "BLOCK") {
  throw new Error("Action blocked by Aegis");
}

if (auth.decision === "REQUIRE_APPROVAL") {
  const approval = await aegis.waitForApproval({
    approvalRequestId: auth.approvalRequestId,
  });
  if (approval.status !== "APPROVED") {
    throw new Error(`Action not approved: ${approval.status}`);
  }
}

await issueRefund(); // your code always makes the final call

Waiting for a human decision

waitForApproval() polls with capped backoff (starts at 1s, caps at 5s) and gives up after a timeout (default 120s) — it never waits forever unless you explicitly ask it to. Throws a timeout error if the request is still pending when the deadline passes.

Registering an agent

registerAgent() skips a dashboard visit for a brand-new agent. Idempotent by name — calling it again returns the same agent rather than creating a duplicate.

Errors

Typed errors distinguish authentication failures, rate limits, validation errors, network errors, and timeouts. Transient failures (429, 5xx, network errors) are retried automatically with bounded exponential backoff; other 4xx errors are never retried.

Idempotency

Pass idempotencyKey to authorize() to make a retried call safe — the same key with an equivalent request replays the original decision instead of creating a second approval request.