aegis.guard()

The core method. Evaluates an AI agent action against all registered guardrail rules, records a tamper-evident audit event, and returns a decision.

---

Signature

TypeScript

await aegis.guard(options: GuardOptions): Promise<GuardResult>

Python

# Synchronous
result = aegis.guard(action, payload, agent_id, user_id?, tags?)

# Async
result = await aegis.guard_async(action, payload, agent_id, user_id?, tags?)

---

Parameters — GuardOptions

Parameter	Type	Required	Description
action	string	✅	The action name. Use a consistent naming convention: send_email, execute_query, http_request.
payload	object	✅	The full data payload for this action. This is logged in full.
agentId	string	✅	Identifier for the agent. Used for filtering in the dashboard.
userId	string	—	The user or session ID that triggered the agent.
tags	object	—	Key-value metadata tags. Useful for filtering by team, feature, or risk level.
wait	boolean	—	For require_approval rules: false returns immediately with pending: true instead of waiting for the human. Default true.

---

Return Value — GuardResult

Field	Type	Description
approved	boolean	true if the action is safe to proceed.
auditId	string	Unique ID for this audit event.
reason	string?	Block reason from the matching rule (only present when approved: false).
matchedRule	string?	Name of the rule that fired.
timestamp	string	ISO 8601 UTC timestamp.
latencyMs	number	Time guard() took in milliseconds. Includes the wait when a human approval was required.
approval	object?	Present when a require_approval rule fired: id, status (approved, denied, expired, pending, unavailable), decidedBy, comment.
pending	boolean?	true only with wait: false while the request awaits a human. approved is false until it is decided.

---

Example

TypeScript

const payload = {
  query: 'DELETE FROM users WHERE last_login < NOW() - INTERVAL 1 YEAR',
  database: 'prod-postgres',
};

const result = await aegis.guard({
  action: 'execute_query',
  payload,
  agentId: 'db-cleanup-bot',
  userId: 'admin_user_01',
  tags: { team: 'data-engineering', risk: 'high' },
});

if (result.approved) {
  await db.execute(payload.query);
} else {
  logger.warn({
    message: 'Agent action blocked',
    auditId: result.auditId,
    rule: result.matchedRule,
    reason: result.reason,
  });
}

Python

payload = {
    "query": "DELETE FROM users WHERE last_login < NOW() - INTERVAL '1 year'",
    "database": "prod-postgres",
}

result = aegis.guard(
    action="execute_query",
    payload=payload,
    agent_id="db-cleanup-bot",
    user_id="admin_user_01",
    tags={"team": "data-engineering", "risk": "high"},
)

if result.approved:
    db.execute(payload["query"])
else:
    logger.warning(f"Blocked [{result.matched_rule}]: {result.reason}")

---

Latency

Rule evaluation happens synchronously in-process. For typical rule sets (< 10 rules, no async DB lookups), evaluation takes < 5ms. The audit event is delivered to Auditail in the background (batched, retried, idempotent), so guard() never waits on the network. Call flush() before a serverless function returns.