Concepts

AgenticContract provides six governance primitives that work together to constrain, monitor, and audit AI agent behavior. Each primitive is a first-class entity stored in the .acon binary file.

Why Governance Primitives?

Traditional access control is binary: allow or deny. AI agents need richer governance:

• Graduated responses: Some actions should be allowed, some denied, some gated behind approval, some merely audited
• Quantitative limits: "Don't spend more than $100" is not a boolean rule — it requires tracking state
• Temporal obligations: "Submit a report by Friday" requires deadline tracking and overdue detection
• Audit requirements: Even allowed actions may need to be recorded for compliance review

AgenticContract models governance as a graph of interconnected primitives, not a flat list of permissions.

Policy

A policy is a named rule governing agent behavior. Policies are the primary enforcement mechanism.

Fields

Scope

Policies apply at one of three scopes:

• Global: Applies to all agents and sessions. Use for organization-wide rules.
• Session: Applies within the current session only. Use for task-specific constraints.
• Agent: Applies to a specific agent. Use for per-agent capability boundaries.

Action

When a policy matches an action, it produces one of four outcomes:

• Allow: The action may proceed. This is the default when no policy matches.
• Deny: The action is blocked. A violation is typically recorded.
• RequireApproval: The action is gated behind an approval workflow.
• AuditOnly: The action proceeds but is logged for review.

Precedence

When multiple policies match, the most restrictive action wins:

Deny > RequireApproval > AuditOnly > Allow

Example

engine.add_policy(
    "No production deploys without approval",
    scope="global",
    action="require_approval"
)

result = engine.check_policy("deploy to production")
# Returns: RequireApproval

Risk Limit

A risk limit sets quantitative boundaries on agent operations. Unlike policies (which are boolean), risk limits track continuous values against thresholds.

Fields

Limit Types

• Rate: Operations per time window (e.g., 100 API calls per hour)
• Threshold: Maximum value that must not be exceeded (e.g., error rate below 5%)
• Budget: Cumulative spending cap (e.g., $100 total API spend)
• Count: Simple counter with a maximum (e.g., no more than 10 retries)

Usage Tracking

# Set a budget limit
engine.set_risk_limit("API spend", max=100.0, type="budget")

# Before each API call, check and increment
limit = engine.check_risk_limit("API spend", amount=0.05)
if limit.would_exceed:
    engine.report_violation("Budget exceeded", severity="critical")
else:
    engine.increment_risk_limit(limit.id, 0.05)

Window Expiration

Rate limits with a window_secs value automatically expire. When window_expired() returns true, the current value resets to zero at the next check.

Approval

The approval system gates high-stakes actions behind human or automated review. It has three components.

Approval Rule

Defines when approval is required.

Approval Request

A pending approval submitted by an agent.

Approval Decision

The outcome of an approval request.

Workflow

Agent action triggers policy -> RequireApproval
  |
approval_request created (status: Pending)
  |
Human or automated approver reviews
  |
approval_decide: Approve or Deny
  |
If Approved -> action proceeds
If Denied -> violation recorded, action blocked

Condition

A condition is a prerequisite that must be satisfied before an action can proceed. Conditions decouple "when can this happen?" from "is this allowed?"

Condition Types

• Threshold: A numeric value must be above or below a target
• TimeBased: An action can only happen during certain time windows
• Dependency: Another action or state must exist first
• Custom: Arbitrary expression evaluated at runtime

Status Lifecycle

Unevaluated -> Met      (condition satisfied)
            -> NotMet   (condition not satisfied)
            -> Unknown  (evaluation failed or inconclusive)

Conditions are re-evaluated on demand via condition_evaluate. They do not auto-update.

Example

engine.add_condition(
    "Business hours only",
    type="time_based",
    expression="09:00-17:00 UTC weekdays"
)

result = engine.evaluate_condition(condition_id)
if not result.is_met:
    print("Action blocked: outside business hours")

Obligation

An obligation represents a commitment that an agent must fulfill, optionally with a deadline.

Status Lifecycle

Pending -> Fulfilled  (completed on time)
        -> Overdue    (deadline passed, not fulfilled)
        -> Waived     (explicitly excused)

Fields

Overdue Detection

is_overdue() returns true when the deadline has passed and the status is still Pending. The engine does not automatically transition to Overdue — call obligation_check to trigger detection.

Example

engine.add_obligation(
    "Submit weekly compliance report",
    description="Generate and submit the weekly compliance summary",
    assignee="compliance-agent",
    deadline="2026-03-07T17:00:00Z"
)

# Periodic check
overdue = engine.check_obligations()
for ob in overdue:
    engine.report_violation(
        f"Missed obligation: {ob.label}",
        severity="warning"
    )

Violation

A violation records a breach of a policy or contract term. Violations are the audit trail.

Severity Levels

Severity implements Ord, so violations can be sorted and filtered by severity.

Fields

Example

engine.report_violation(
    "Agent exceeded API budget by $12.50",
    severity="critical",
    actor="data-agent-3"
)

Contract Engine

The ContractEngine is the central runtime that ties all six primitives together. It wraps the .acon file format and provides:

• CRUD operations for all entity types
• Policy evaluation with text-matching and precedence
• Risk limit tracking with window expiration
• Approval workflow management
• Obligation deadline monitoring
• Violation recording and querying
• Statistics and summary reporting

The engine is the only entry point for modifying the contract store. All MCP tools, CLI commands, FFI functions, and Python SDK methods delegate to it.

Entity Relationships

Policies -------> RequireApproval --> Approval Rules
    |                                    |
    |                                    v
    |                              Approval Requests
    |                                    |
    |                                    v
    |                              Approval Decisions
    |
    +-------> Conditions (prerequisites)
    |
    +-------> Violations (breaches)

Risk Limits --> Violations (on exceed)

Obligations --> Violations (on overdue)

All entities are identified by ContractId (UUID-based) and timestamped with created_at. This enables temporal queries and audit trails across the full governance lifecycle.