Policy

One policy file for access, approvals, guards, budgets and limits per tool, team and environment. Concepts: Policy file.

Policy: one file that sets approvals, budgets, guardrails, limits and access per tool and env.

ENV_VAR = 'AA_ENV' module-attribute

PolicySource = str | os.PathLike[str] | Mapping[str, Any] | PolicySpec module-attribute

TeamOf = Callable[[ToolContext], str] module-attribute

BudgetRule

Bases: _Strict

A BudgetHook: a spend limit per scope, optionally per UTC day or month.

Condition

A parsed condition: comparisons (== != < <= > >= in not in), and, or, not.

Operands are argument names (dotted for nested fields), numbers, strings, true, false, null and lists of those. Secret-named arguments cannot be read.

Raises:

Type	Description
ConditionError	anything outside that grammar, or a secret-named argument.

evaluate(args)

True when the arguments meet the condition.

Raises:

Type	Description
ConditionError	a missing argument, or values that cannot be compared.

shown()

The text with every string literal as '...', for explanations and logs.

ConditionError

Bases: ValueError

A condition cannot be parsed, or cannot be decided for these arguments.

Explanation dataclass

The rules for one tool: allowed is None when it depends on the caller.

GuardRule

Bases: Selector

A content guard on the selected tools' arguments or results (and model calls).

LimitsRule

Bases: _Strict

Run limits: at most max_calls distinct calls per run.

MemoryRule

Bases: _Strict

How long memories are kept, and whether the remember tool may save, with approval.

Policy

A validated policy for one environment, ready to apply to an executor.

Build it with load_policy. Everything it adds is stricter than the code: approvals are only ever added, and the two relaxations need relax: plus allow_relax=True.

Raises:

Type	Description
PolicyError	an unknown environment, an unapproved relaxation, or a bad guard/store.

default property

allow or deny for tools no rule names, in this environment.

access(tool, ctx)

Whether tool may run for ctx, and why; None when it depends on the caller.

apply(executor)

A new executor running every call under this policy; executor is unchanged.

Applying a second policy keeps the first: both must allow a call, either may ask.

apply_memory(memory)

Shorten memory's retention to the policy's (longer only when relaxed); returns it.

Raises:

Type	Description
PolicyError	memory is not one of agent_adapter.memory's backends.

check_sandbox(sandbox)

Refuse a sandbox the policy does not accept; returns it unchanged.

Raises:

Type	Description
PolicyError	not isolated, or network access, where the policy forbids it.

confirm_items(name, spec)

The policy's reasons this tool may need approval (callers checked per call).

describe(spec)

The rules that may apply to spec, one short line each (the viewer's Tools tab).

effective(spec)

spec with the policy's approvals added to its own confirm (never removed).

explain(tool, ctx=None)

Which rules apply to tool for ctx; without a context, caller rules say "some".

hooks()

The hooks this policy adds, the access gate first.

limits(current)

current with the policy's max_calls: lower only, unless relaxed.

tools(registry)

The tools of registry a model may be shown: those not denied to every caller.

PolicyChain

Several policies at once: each rewrites the spec in turn, so all of them apply.

describe(spec)

Every policy's lines for spec.

effective(spec)

spec through every policy in order.

hooks()

Every policy's hooks, in the order they were applied.

limits(current)

The strictest max_calls any policy gives; a relaxation raises only the code's own.

PolicyDenied

Bases: ApprovalDenied

A policy does not allow this tool here; a denial like any other (approval-denied).

PolicyError

Bases: ConfigError

A policy is malformed, unknown, or would relax a code default; nothing is applied.

PolicySpec

Bases: _Strict

A whole policy, as written in the file.

RateRule

Bases: _Strict

A RateLimitHook bucket: at most calls per per seconds for one tool kind (or llm).

SandboxRule

Bases: _Strict

What a code sandbox must be: isolated from the host, and without network access.

ToolRule

Bases: Selector

Allow or deny tools, or ask for approval always (true) or on a condition.

load_policy(source, *, env=None, allow_relax=False, guards=None, stores=None, team_of=None)

A validated Policy from a file path (.yaml, .yml, .toml, .json), a dict or a PolicySpec.

Parameters:

Name	Type	Description	Default
env	str | None	The environment; default AA_ENV (empty when unset).	None
allow_relax	bool	Accept the relaxations the policy lists under relax.	False
guards	Mapping[str, ContentGuard] | None	Content guards built in code, named by guard: entries.	None
stores	Mapping[str, BudgetStore] | None	Budget stores built in code (Redis, SQL), named by store: entries.	None
team_of	TeamOf | None	The caller's team; default ctx.extras[team_key], then principal claims.	None

Raises:

Type	Description
PolicyError	a malformed, unknown or relaxing setting, with the file, line and key.
MissingDependency	a YAML file without pyyaml.

team_from(key)

ctx.extras[key], else the principal's claims[key]; "" when neither is a string.