agent-action-policy

한국어 문서

Declarative action policies for AI agents — approve, deny, or escalate any tool call before execution.

Install

pip install agent-action-policy
pip install agent-action-policy[yaml]  # for YAML policy files

Quick Start

from action_policy import PolicyEngine, Action

engine = PolicyEngine.from_dict({
    "policies": [{
        "name": "no-force-push",
        "match": {"tool": "bash", "args_pattern": "git push --force"},
        "action": "deny",
        "reason": "Force push requires human approval",
    }]
})

decision = engine.evaluate(tool="bash", args={"command": "git push --force origin main"})
print(decision.denied)  # True
print(decision.reason)  # "Force push requires human approval"

Sandboxing vs Policy

Sandboxing and policies are complementary. Use both.

Policy Definition (YAML)

policies:
  - name: no-destructive-git
    match:
      tool: bash
      args_pattern: "git (push --force|reset --hard|branch -D)"
    action: deny
    reason: "Destructive git operations require human approval"

  - name: escalate-system-files
    match:
      tool: "~(file_write|write_file)"
      path_patterns:
        - "/etc/*"
        - "/usr/*"
    action: escalate
    reason: "System file modification needs confirmation"

  - name: approve-reads
    match:
      tool: "~(read|search|grep)"
    action: approve
    priority: 10  # lower = higher priority

Built-in Templates

engine = PolicyEngine.from_template("safe_coding")

Python API

# From YAML file
engine = PolicyEngine.from_yaml("policies.yaml")

# From dict
engine = PolicyEngine.from_dict({"policies": [...]})

# From template
engine = PolicyEngine.from_template("safe_coding")

# Evaluate
decision = engine.evaluate(tool="bash", args={"command": "rm -rf /"})
decision.action     # Action.DENY
decision.denied     # True
decision.reason     # "..."
decision.policy_name  # "no-rm-rf"

# Fail-closed mode (deny by default)
engine = PolicyEngine.from_template("strict", default_action=Action.DENY)

# Decorator
@engine.guard
def execute_tool(tool: str, args: dict = None):
    ...  # raises PolicyDenied or PolicyEscalated

Pattern Matching

License

MIT