Policies

Policies are the compliance rules that govern how AI agents behave in the Kyvvu platform. Each policy combines a rule function with specific parameters to enforce requirements at different points in the agent lifecycle — during registration, at each execution step, or at task completion.

---

How Policies Work

A policy has three components:

1. Rule function — the underlying check (e.g., "field must not be empty", "node must be preceded by approval")

2. Parameters — configuration for that rule (e.g., {"field": "purpose"})

3. Targeting — when and to whom the policy applies (scope, risk classification, agent ID)

When an agent registers or logs execution steps, the platform evaluates all applicable policies. If a policy fails, an incident is created automatically with the severity level defined in the policy. Policies do not block execution — they record violations so operators can review and respond.

---

Policy Scopes

Policies are evaluated at three distinct points:

Scope	When Evaluated	Purpose
agent_registration	When an agent is created or updated via POST /api/v1/agents	Enforce documentation and accountability requirements before deployment
step_execution	At every logged step during task execution (POST /api/v1/logs)	Enforce runtime behaviour constraints (e.g., approval before sensitive operations)
task_execution	Only at END_NODE step, with visibility of the entire task	Enforce requirements that span the full execution (e.g., "must contain a PII check somewhere")

At END_NODE, both step_execution and task_execution policies are evaluated together — the former applies to the END_NODE step itself, the latter to the completed task history.

---

Policy Targeting

Policies can be narrowed by:

• Risk classification — apply only to agents of a specific risk level (high, limited, minimal, unacceptable, unclassified). Null means all agents.

• Agent ID — apply only to a specific agent. Null means all agents.

A policy with no targeting filters is universal and applies to every agent at the appropriate scope.

---

Rule Functions

Rule functions are Python functions decorated with @PolicyRule.register(). They take three arguments:

• data — the data being evaluated (agent fields or step fields)

• params — configuration parameters from the policy

• context — a RuleContext object providing access to execution history, database, and agent information

The function returns True if the policy passes, False if violated.

Available Rule Functions

1. Field Validation Rules

These rules check agent or step data fields. They apply to both agent_registration and step_execution scopes.

field_not_empty

Checks if a field has a non-empty value (not None, not empty string).

Parameters:

• field (string, required) — name of the field to check

Example use case: Ensure every agent has a documented purpose before deployment.

{
  "rule_type": "field_not_empty",
  "params": {"field": "purpose"},
  "scope": "agent_registration",
  "severity": "high"
}

---

field_in_list

Checks if a field value is in an allowed list.

Parameters:

• field (string, required) — name of the field to check

• values (array, required) — list of allowed values

Example use case: Restrict agents to valid risk classifications.

{
  "rule_type": "field_in_list",
  "params": {
    "field": "risk_classification",
    "values": ["high", "limited", "minimal"]
  },
  "scope": "agent_registration",
  "severity": "critical"
}

---

field_matches_regex

Checks if a field value matches a regular expression pattern.

Parameters:

• field (string, required) — name of the field to check

• pattern (string, required) — regular expression pattern

Example use case: Ensure agent purpose contains a meaningful description (minimum 20 characters).

{
  "rule_type": "field_matches_regex",
  "params": {
    "field": "purpose",
    "pattern": "^.{20,}$"
  },
  "scope": "agent_registration",
  "severity": "medium"
}

---

2. Sequence & Predecessor Rules

These rules enforce ordering requirements during execution. They apply to step_execution and task_execution scopes.

node_directly_preceded_by

Ensures specified node types are immediately preceded by a required node type.

Parameters:

• required_predecessor_type (string, required) — node type that must come immediately before (e.g., HUMAN_APPROVAL)

• target_node_types (array, optional) — node types to check. If omitted, checks all nodes.

Example use case: Require human approval immediately before any tool call with write permissions.

{
  "rule_type": "node_directly_preceded_by",
  "params": {
    "required_predecessor_type": "HUMAN_APPROVAL",
    "target_node_types": ["TOOL_CALL"]
  },
  "scope": "step_execution",
  "severity": "critical"
}

Example use case (strict mode): Require human approval before every step (omit target_node_types).

{
  "rule_type": "node_directly_preceded_by",
  "params": {
    "required_predecessor_type": "HUMAN_APPROVAL"
  },
  "scope": "step_execution",
  "severity": "high"
}

---

node_requires_predecessor

Ensures specified node types have a required predecessor node somewhere before them in the execution (not necessarily immediately).

Parameters:

• required_predecessor_type (string, required) — node type that must appear before (e.g., PII_CHECK)

• target_node_types (array, required) — node types that require the predecessor

Example use case: Ensure a PII check happens before any LLM call in the execution.

{
  "rule_type": "node_requires_predecessor",
  "params": {
    "required_predecessor_type": "PII_CHECK",
    "target_node_types": ["LLM_CALL"]
  },
  "scope": "step_execution",
  "severity": "high"
}

Difference from node_directly_preceded_by:

• node_directly_preceded_by — predecessor must be the immediate previous step

• node_requires_predecessor — predecessor can be anywhere earlier in the execution

---

execution_contains_node_before_current

Ensures the execution contains a specific node type somewhere in the history before the current step.

Parameters:

• required_node_type (string, required) — node type that must appear (e.g., HUMAN_APPROVAL)

Scope: task_execution only (evaluated at END_NODE).

Example use case: Ensure high-risk agents have human approval somewhere in the completed task.

{
  "rule_type": "execution_contains_node_before_current",
  "params": {"required_node_type": "HUMAN_APPROVAL"},
  "scope": "task_execution",
  "risk_classification": "high",
  "severity": "critical"
}

---

3. Access Control Rules

These rules restrict what agents can do based on risk classification.

node_forbidden_for_agent_classification

Prevents agents with specific risk classifications from performing certain operations.

Parameters:

• forbidden_node_type (string, required) — node type that is forbidden (e.g., TOOL_CALL)

• agent_risk_classifications (array, required) — list of risk classifications this applies to (e.g., ["high"])

• node_attribute_filter (object, optional) — additional conditions (e.g., {"is_external_call": true})

Example use case: Prevent high-risk agents from making external API calls.

{
  "rule_type": "node_forbidden_for_agent_classification",
  "params": {
    "forbidden_node_type": "TOOL_CALL",
    "agent_risk_classifications": ["high"],
    "node_attribute_filter": {"is_external_call": true}
  },
  "scope": "step_execution",
  "severity": "critical"
}

---

4. Audit Trail & Limits

These rules enforce execution limits and workflow patterns.

execution_max_tool_calls

Limits the number of times a specific node type can appear in a single execution.

Parameters:

• max_calls (integer, required) — maximum allowed calls

• node_type (string, required) — node type to count (e.g., TOOL_CALL)

Scope: task_execution (evaluated at END_NODE).

Example use case: Prevent runaway agents by capping tool calls to 10 per task.

{
  "rule_type": "execution_max_tool_calls",
  "params": {
    "max_calls": 10,
    "node_type": "TOOL_CALL"
  },
  "scope": "task_execution",
  "severity": "high"
}

---

execution_requires_node_sequence

Ensures the execution contains nodes in a specific order.

Parameters:

• required_sequence (array, required) — ordered list of node types that must appear

• strict_order (boolean, optional) — if true, nodes must appear consecutively. If false (default), other nodes can appear between them.

Scope: task_execution (evaluated at END_NODE).

Example use case: Require that agents follow a plan → execute → verify workflow (with other steps allowed in between).

{
  "rule_type": "execution_requires_node_sequence",
  "params": {
    "required_sequence": ["PLAN_NODE", "EXECUTE_NODE", "VERIFY_NODE"],
    "strict_order": false
  },
  "scope": "task_execution",
  "severity": "medium"
}

Example use case (strict consecutive ordering): Require immediate sequence of approval then tool call.

{
  "rule_type": "execution_requires_node_sequence",
  "params": {
    "required_sequence": ["HUMAN_APPROVAL", "TOOL_CALL"],
    "strict_order": true
  },
  "scope": "task_execution",
  "severity": "high"
}

---

Creating Policies

Via API

Create a policy with POST /api/v1/policies:

{
  "name": "Agent must have documented purpose",
  "description": "EU AI Act Article 13 requires clear documentation",
  "scope": "agent_registration",
  "rule_type": "field_not_empty",
  "params": {"field": "purpose"},
  "severity": "high",
  "enabled": true,
  "risk_classification": null,
  "agent_id": null
}

Retrieve available rule functions and their schemas with GET /api/v1/policies/rules.

Via Dashboard

The web dashboard provides a form-based interface for creating policies. It automatically populates rule parameters based on the selected rule type.

Via Policy Templates

Policy templates bundle multiple related policies for one-click application. Available templates are listed at GET /api/v1/policy-templates.

Apply a template with POST /api/v1/policy-templates/{template_id}/apply. All created policies are tagged with source_template so they can be removed as a group later.

Example templates:

• eu_ai_act_basic — essential documentation requirements for EU AI Act Article 13

• ai_act_comprehensive — full set of policies for high-risk agent compliance

• data_minimization — policies to enforce data handling best practices

Templates are YAML files stored in api/app/policies/templates/. See existing templates for structure.

---

Policy Templates

Templates are stored as YAML files in api/app/policies/templates/. Each template defines metadata and a list of policy definitions.

Template structure:

name: "Template Name"
description: |
  Detailed description of what this template enforces.
version: "1.0"

policies:
  - name: "Policy name"
    description: "What this policy checks"
    rule_type: field_not_empty
    params:
      field: purpose
    severity: high
    scope: agent_registration
    risk_classification: null  # optional, defaults to null (all agents)

Applying a template:

POST /api/v1/policy-templates/eu_ai_act_basic/apply
{
  "enabled": true
}

This creates all policies from the template in one operation. All created policies are tagged with source_template: eu_ai_act_basic.

Removing a template:

DELETE /api/v1/policy-templates/eu_ai_act_basic/remove

This deletes all policies created from the template, unless any have associated incidents (for audit trail preservation).

---

For Partners: Extending Rule Functions

If you have access to the API codebase and need custom compliance logic not covered by the built-in rules, you can add new rule functions.

Adding a Custom Rule

1. Open api/app/policies/rule_functions.py

2. Define your function and decorate it with @PolicyRule.register():

@PolicyRule.register(
    name='my_custom_rule',
    description='Checks for a custom compliance requirement',
    params_schema={
        'threshold': {
            'type': 'integer',
            'required': True,
            'description': 'Minimum value required'
        }
    },
    scopes=['agent_registration', 'step_execution']
)
def check_my_custom_rule(
    data: Dict[str, Any],
    params: Dict[str, Any],
    context: RuleContext
) -> bool:
    """Check custom compliance rule.

    Args:
        data: Data dictionary to evaluate.
        params: Rule parameters with 'threshold' key.
        context: Evaluation context.

    Returns:
        True if rule passes, False if violated.
    """
    value = data.get('some_field', 0)
    threshold = params['threshold']

    return value >= threshold

1. The rule is immediately available via GET /api/v1/policies/rules and can be used in policies.

Rule Context API

The RuleContext object provides access to:

• context.db — SQLAlchemy database session

• context.scope — current evaluation scope (agent_registration, step_execution, task_execution)

• context.agent_id — agent being evaluated

• context.execution_id — current task ID

• context.current_step_id — current log entry ID

• context.now — current UTC datetime

• context.hour — current hour (0-23) for time-based rules

Helper methods:

• context.get_current_agent() — retrieve Agent model object (cached)

• context.get_previous_step() — get immediately previous log entry (cached)

• context.get_all_steps_in_execution() — get all log entries in current execution before current step (cached, ordered ascending)

• context.count_nodes_of_type(node_type) — count occurrences of a node type in execution history

Example — time-based rule:

@PolicyRule.register(
    name='working_hours_only',
    description='Agent can only operate during business hours',
    params_schema={
        'start_hour': {'type': 'integer', 'required': True},
        'end_hour': {'type': 'integer', 'required': True}
    },
    scopes=['step_execution']
)
def check_working_hours(data, params, context):
    start = params['start_hour']
    end = params['end_hour']

    return start <= context.hour < end

Example — execution history check:

@PolicyRule.register(
    name='max_llm_calls_per_task',
    description='Limit LLM calls in a single execution',
    params_schema={
        'max_calls': {'type': 'integer', 'required': True}
    },
    scopes=['task_execution']
)
def check_max_llm_calls(data, params, context):
    count = context.count_nodes_of_type('LLM_CALL')
    return count <= params['max_calls']

Testing Your Rule

Add tests to api/app/policies/tests/test_rule_functions.py:

def test_my_custom_rule(db_session, sample_agent):
    context = RuleContext(
        db=db_session,
        scope='agent_registration',
        agent_id=sample_agent.agent_id
    )

    # Test pass case
    data = {'some_field': 100}
    params = {'threshold': 50}
    assert check_my_custom_rule(data, params, context) is True

    # Test violation case
    data = {'some_field': 10}
    assert check_my_custom_rule(data, params, context) is False

Run tests with:

pytest api/app/policies/tests/ -v

---

Further Reading

• API Reference — data models and endpoint behaviours

• Incidents — how violations are tracked and resolved

• Policy Templates — applying pre-built compliance frameworks