Skip to main content
Hivenora
Sign inGet Started

Core Concepts

The evaluation model

Every evaluate() call passes through the same pipeline: intent analysis, blast radius estimation, policy matching, and decision. Understanding each stage makes the API predictable and your policies easier to write.

Action

An action is the operation the agent proposes to perform. Pass it as a dot-separated string: service.operation.

Examples:

  • crm.delete_contacts
  • stripe.issue_refund
  • gmail.bulk_send
  • database.drop_table
  • s3.delete_bucket

The action string is not a strict enumeration — you define your own naming convention. Policies are matched by exact string or prefix. Use consistent naming within your system.

Intent

Intent is the natural-language goal the user gave the agent, passed as a string. It is used for one purpose: intent mismatch detection.

If the scope of the action (as described by context) appears to significantly exceed what the intent describes, Hivenora setsintent_mismatch: true in the response. This surfaces cases where an agent may be doing more than the user intended.

Example:

Intent: "Clean up a few test contacts from Q1" Action: crm.delete_contacts Context: { records_affected: 4,821 } → intent_mismatch: true ("a few" vs 4,821)

Intent is used for analysis only. It does not influence the policy rule engine — policies match on action and context, not intent. A malicious intent string cannot bypass a policy.

Context

Context is a structured object with metadata about the action. It is the primary input to blast radius estimation and policy evaluation.

Recognized context fields

records_affectedint
Number of records, rows, or items the action will affect.
amountfloat
Financial amount in the smallest currency unit (e.g., cents). Used for financial action classification.
environmentstring
"production" or "sandbox". Production actions have higher blast radius by default.
data_sensitivitystring
Sensitivity classification: "public", "internal", "customer_pii", "financial", "health".
reversibilitystring
"high" (rollback available), "medium" (partial restore), "low" (permanent). Lower reversibility increases blast radius.
recipientsint
Number of recipients for communication actions (email, SMS, etc.).
resourcestring
Identifier of the primary resource being acted on.

Unknown context fields are ignored. You can pass any additional fields — they are stored in the audit record but do not affect evaluation.

Blast Radius

Blast radius is an estimate of potential impact, computed deterministically from context. The output is one of four levels:

critical
Catastrophic potential impact. Exceeds autonomous action threshold by default. Triggers require_approval unless policy explicitly allows.
high
Significant scope. May trigger review depending on agent policy configuration.
medium
Moderate scope. Allowed autonomously under default policy.
low
Minimal scope. Allowed autonomously under default policy.

Blast radius is computed before policy matching. The policy engine can use blast radius as a match condition. Example: "if blast_radius is critical, require_approval."

What determines blast radius

The computation considers: records affected, financial amount, reversibility, environment, and data sensitivity. The exact thresholds are deterministic and documented in the Control Room → Policy Editor. There is no LLM inference in this step.

The response includes blast_radius_factors — a list of human-readable strings explaining which inputs drove the classification:

"blast_radius_factors": [ "4,821 records affected", "317 active opportunities linked", "Production environment", "Reversibility: low — no undo path" ]

Policy

A policy is a rule that maps action conditions to decisions. Policies are defined per agent in the Control Room.

Policy structure

Policy: "Large Scope CRM Protection" Match: action starts with "crm." AND blast_radius IN ["critical", "high"] Decision: require_approval Priority: 10 Policy: "Production Financials Threshold" Match: action starts with "stripe." AND amount > 100000 Decision: require_approval Priority: 20

Policies are evaluated in priority order. The first matching policy wins. If no policy matches, the default agent decision is applied (configurable per agent — either allow or require_approval).

Decision types

  • allow — the action proceeds. Recorded in the audit log.
  • require_approval — the action is paused. An approval request appears in the Control Room. Your application polls or receives a webhook.
  • block — the action is refused. Not approvable.

Decision

The evaluation returns two decision fields:

  • decision — what the policy engine decided
  • effective_decision — what is actually applied

In enforcement mode, these are always equal. In Shadow Mode,effective_decision is always allowregardless of what decision says. See the Shadow Mode docs for details.

The response also includes convenience booleans:

  • is_allowed — effective_decision === "allow"
  • requires_approval — effective_decision === "require_approval"
  • is_blocked — effective_decision === "block"

The evaluation pipeline

Every evaluate() call runs in this order:

1. Authenticate API key → resolve agent + organization 2. Intent analysis Compare action scope (from context) against intent string → Set intent_mismatch if scope significantly exceeds intent 3. Blast radius estimation Compute from context: records_affected, amount, reversibility, environment, data_sensitivity → Classify: critical | high | medium | low 4. Policy matching Evaluate policies in priority order against action + context + blast_radius → First match wins; apply decision 5. Effective decision Enforcement mode: effective_decision = decision Shadow mode: effective_decision = allow (always) 6. Record Write to audit log (append-only) If require_approval: create Approval record 7. Return response
← QuickstartSDK Reference →