Mandate SDK

Runtime enforcement for AI agent authority.

Mandate SDK serves as the foundational component of the Know Your Agent (KYA) infrastructure, delivering mechanical enforcement of AI agent authority at runtime rather than relying solely on prompt suggestions. This ensures that AI agents have a stable identity and enforces the policies established for their operations.

The Problem

As AI agents increasingly function as economic actors—spending money, interfacing with APIs, and making consequential decisions—they risk operating in an ungoverned manner. Presently, these agents act as unbanked entities characterized by:

• ❌ Anonymity: Lacking a stable identity.
• ❌ Fungibility: Being indistinguishable from one another.
• ❌ Prompt-constrained behavior: Authority is more of a suggestion rather than a firm mandate.
• ❌ No accountability: Lacking an audit trail for actions taken.

What Goes Wrong

Without strong enforcement, the following issues can arise:

1. Budget Runaway: An agent may inadvertently overspend by looping through requests, resulting in significant costs.
2. Retry Storms: A transient error may trigger excessive retries, leading to wasted resources.
3. Tool Abuse: Agents may call high-risk tools (delete_*, execute_*) due to unintentional hallucinations by language models.
4. No Accountability: Tracking which agent initiated a problematic action becomes challenging, complicating ownership and responsibility.
5. Silent Failures: Tools may return apparent successes, despite failures in execution (e.g., email accepted but not delivered).

The Solution

Mandate SDK provides a robust runtime enforcement mechanism through a layered execution model:

import { MandateClient, createToolAction } from "@mandate/sdk";

const client = new MandateClient({
  mandate: {
    version: 1,
    id: "mandate-1",
    agentId: "email-agent",
    issuedAt: Date.now(),
    maxCostTotal: 10.0, // $10 total budget
    allowedTools: ["send_email"], // Tool permissions
    toolPolicies: {
      send_email: {
        rateLimit: {
          maxCalls: 5,
          windowMs: 60_000,
        },
        chargingPolicy: {
          type: "ATTEMPT_BASED",
        },
      },
    },
  },
  auditLogger: "console",
});

const action = createToolAction("email-agent", "send_email", {
  to: "user@example.com",
  subject: "Invoice",
});

try {
  await client.executeTool(action, () => sendEmail());
} catch (error) {
  // Blocked if policy violations occur.
}

What Just Happened:

1. Authorization: The policy is examined before any execution takes place.
2. Execution: Actions are permitted only if they comply with established rules.
3. Settlement: The actual costs are reconciled against estimates.
4. Accounting: Budgets are updated upon successful commitment.
5. Audit: Each decision is logged, providing complete traceability.

Architecture Overview

Mandate SDK is structured to maintain a separation of concerns, utilizing a Policy Engine and a State Manager to enforce policies at runtime effectively. Key components include:

• MandateClient: The primary interface for executing actions.
• PolicyEngine: Responsible for policy evaluation in a deterministic manner.
• StateManager: Tracks the state and manages agent activity.
• KillSwitch: Offers emergency termination options.

Phase 3 introduces a Redis backend for distributed state management, allowing for atomic operations and global limits across multiple servers.

Why Choose Mandate?

Mandate ensures AI agents are governable at the identity level, providing essential features such as:

• ✅ Mechanical Enforcement: Actions are dictated by policy without ambiguity.
• ✅ Determinism: Input yields predictable outputs.
• ✅ Explainability: Every policy decision is documented with reasoning.
• ✅ Fail-Closed System: Unknown inputs are treated as denied actions.

Use Cases

Mandate serves various audiences including:

1. AI Engineers: Enforcing budgets mechanically during execution, thereby eliminating uncertainty in operational costs.
2. Product Teams: Ensuring transparency and accountability in agent actions with full audit trails.
3. Enterprises: Maintaining compliance and risk management through structured governance.

Getting Started

Mandate SDK offers a seamless integration experience with examples and thorough documentation covering all aspects of its functionality. For detailed usage and exploration, refer to the documentation and examples.

Community and Contributions

Contributions are welcomed, and interested developers can participate in expanding the functionalities or improving documentation. For issues, discussions, or feature requests, visit the relevant sections on GitHub.

For further learning, refer to the detailed guides and examples provided in this repository.