aegis.guard()

The core method. Evaluates an AI agent action against all registered guardrail rules, logs an immutable 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.

---

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 taken for rule evaluation, in milliseconds.

---

Example

TypeScript

const result = await aegis.guard({
  action: 'execute_query',
  payload: {
    query: 'DELETE FROM users WHERE last_login < NOW() - INTERVAL 1 YEAR',
    database: 'prod-postgres',
  },
  agentId: 'db-cleanup-bot',
  userId: 'admin_user_01',
  tags: { team: 'data-engineering', risk: 'high' },
});

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

Python

result = aegis.guard(
    action="execute_query",
    payload={
        "query": "DELETE FROM users WHERE last_login < NOW() - INTERVAL '1 year'",
        "database": "prod-postgres",
    },
    agent_id="db-cleanup-bot",
    user_id="admin_user_01",
    tags={"team": "data-engineering", "risk": "high"},
)

if result.approved:
    db.execute(result.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 shipped to the Auditail API asynchronously on a background worker, with zero impact on your agent's response time.