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¶
- Write the
AIOSv1PolicyRuleclass and package it with itsrequirements.txt. - Register the package in the policies system to get a
policy_rule_uri. See the PolicyGrid documentation for the registration API. - Attach it to the agent in
integrations.policieswith the rightpolicy_type. - Redeploy the agent, then check it with
POST <executor>/dryRun(see Testing Agents).
PolicyGrid
Full documentation: PolicyGrid website · PolicyGrid documentation.