Skip to content

Agentic Governance

PolicyGrid

This page explains how agents are governed through policies with the agents SDK. For the full governance and policy product, see the PolicyGrid website and PolicyGrid documentation.

Governance keeps agents aligned with shared rules: who may send them work, how much, in what form, and what they may return. On AgentGr.id this is done with policies: small, versioned pieces of code stored in the policies system and attached to an agent in its specification. The platform calls them at fixed points. Changing a policy changes the agent's behavior without changing the agent's code.

  • Governance policies decide whether and how work is accepted and distributed: admission, rate limits, backlogs, load balancing, scaling.
  • Guardrails check and transform the content going into and coming out of the agent: input validation, redaction, output filtering.

Where Policies Run

Policy type (policy_type) Runs in Called with Return If missing
message_prechecker Executor, for every incoming task {"session_id", "message_data"} {"allowed": bool, "reason": {...}} or a bool Allow
rate_limiter Executor {"session_id", "message_data"}; settings get rate_counter {"allowed": bool, "metadata": {...}} or a bool Allow
message_backlog Executor {"session_id", "message_data"}; settings get backlog_store {"backlogged": true, "reason": {...}} or {"backlogged": false, "messages": [...]} Pass through
load_balancer Executor {"session_id", "message_data"}; settings get get_instances {"ok": true, "instance": "<id>"} Random instance
autoscaler Executor, every 30 s Instance count, IDs and queue depth "scale_up", "scale_down" or None No action
message_transformer Agent instance (SDK), before pre-processing {"task_id", "job_data", "task_metadata", "output_ptr"} The same shape, transformed Pass through
pre_processor Agent instance (SDK), before on_preprocess {"task_id", "job_data", "task_metadata", "output_ptr"} The same shape Pass through
post_processor Agent instance (SDK), after on_data The AgentResult fields The same shape Pass through

The executor policies are covered in detail in Scaling. This page focuses on writing and attaching policies, and on guardrails.

main(AgentClass) loads the message_transformer, pre_processor and post_processor policies declared in the specification and applies them to every task, whatever input stream it arrived on (Redis queue or WebSocket). The log shows Guardrail policy '<type>' loaded for each one.


Attaching a Policy to an Agent

Policies are listed in integrations.policies of the Agent Specification:

"integrations": {
  "policies": [
    {
      "policy_type": "message_prechecker",
      "policy_rule_uri": "guardrails.allowed-senders:1.0-stable",
      "parameters": { "allowed_orgs": ["ExampleOrg"] },
      "settings": {}
    },
    {
      "policy_type": "rate_limiter",
      "policy_rule_uri": "limits.per-session:1.0-stable",
      "parameters": { "max_per_minute": 30 }
    }
  ]
}
Field Description
policy_type Where the policy runs (see the table above). One policy per type
policy_rule_uri The policy in the policies system
parameters Values passed to the policy's eval, merged with the policy's own stored parameters
settings Values passed to the policy's constructor, merged with its stored settings. Platform objects such as rate_counter are injected here

Policies are loaded when the executor or instance starts, so redeploy (or restart the pods) after changing them.


Writing a Policy

A policy is a package with a code/function.py file, and optionally a requirements.txt, that defines a class named AIOSv1PolicyRule:

# code/function.py
class AIOSv1PolicyRule:

    def __init__(self, rule_id, settings, parameters):
        self.settings = settings        # includes injected objects, e.g. rate_counter
        self.parameters = parameters

    def eval(self, parameters, input_data, context):
        # Example: rate limiting per session
        counter = self.settings["rate_counter"]
        sid = input_data["session_id"]
        count = counter.increment(sid, expire_seconds=60)
        return {"allowed": count <= parameters.get("max_per_minute", 30)}

    def management(self, action, data):
        # Optional runtime commands, e.g. "reset"
        if action == "reset":
            self.settings["rate_counter"].reset(data["session_id"])
            return {"ok": True}
        return {"ok": False, "error": f"unknown action {action}"}

When the policy is loaded, the runtime fetches the policy record from POLICY_DB_URL (GET /policy/<policy_rule_uri>), downloads and unpacks the code archive (.zip or .tar.gz), installs requirements.txt and instantiates AIOSv1PolicyRule.

Local or Remote Execution

Variable Default Description
POLICY_EXECUTION_MODE local local runs the policy in-process. Any other value sends each evaluation to a policy executor service
POLICY_EXECUTOR_HOST_URL http://localhost:10000 Policy executor service (remote mode): POST /executor/<id>/execute_policy
POLICY_SYSTEM_EXECUTOR_ID executor-0 Executor ID (remote mode)

Remote mode keeps untrusted policy code out of the agent process, at the cost of a network call per evaluation.


Guardrails

Common guardrails and where to put them:

Guardrail Policy type Example behavior
Sender allow-list message_prechecker Block tasks whose message_data does not come from an allowed organisation, returning {"allowed": false, "reason": {"code": "sender_not_allowed"}}
Input schema validation message_prechecker or pre_processor Reject tasks with missing or malformed job_data
Prompt-injection or PII screening pre_processor Redact or strip content from job_data before the agent sees it
Output filtering post_processor Remove secrets or disallowed content from job_output, or set is_error
Quotas rate_limiter Limit tasks per session or per caller

Blocked tasks are rejected with HTTP 429, and the response carries stage and reason so callers can see which rule fired.

Failure Mode

What happens when an admission policy itself raises an error is set per executor with POLICY_FAIL_MODE:

POLICY_FAIL_MODE Behavior
open (default) The task is allowed, as if the policy were absent. Use it for availability-first agents
closed The task is blocked with HTTP 429, stage set to the failing step (pre_check, rate_limit or backlog) and reason: {"error": "policy_error", "message": "..."}. Use it when a guardrail must never be bypassed

Set it on the executor, for example in the deployer's executor template or with kubectl set env deployment/<executor> POLICY_FAIL_MODE=closed -n agents.


Creating and Onboarding Custom Policies

  1. Write the AIOSv1PolicyRule class and package it with its requirements.txt.
  2. Register the package in the policies system to get a policy_rule_uri. See the PolicyGrid documentation for the registration API.
  3. Attach it to the agent in integrations.policies with the right policy_type.
  4. Redeploy the agent, then check it with POST <executor>/dryRun (see Testing Agents).

PolicyGrid

Full documentation: PolicyGrid website · PolicyGrid documentation.