Agent Firewall

The agent-firewall policy evaluates tool actions and returns a tool-phase decision. It controls tool access, action counts, transactions, and suspicious patterns. It can also examine tool arguments for PII.

Phase and verdicts

• Phase: tool
• Possible verdicts: allow, block, escalate

Configuration

Use one config shape in each policy block. The schema defines a simple shape and an expanded shape. Do not mix them.

pack:
  name: agent-firewall-example
  version: 1.0.0
  enabled: true
policies:
  chain:
    - agent-firewall
policy:
  agent-firewall:
    tools:
      roles:
        analyst:
          allowed:
            - read_database
            - export_csv
          denied:
            - delete_database
    rate_limits:
      export_csv: 1
    transaction_limits:
      max_single_transaction: 5000.0
      max_daily_total: 20000.0
      require_approval_above: 1000.0
    kill_switches:
      halt_on_suspicious_pattern: true
      halt_on_pii_in_action: true

Supported fields

Field	Type	Default	Notes
allowed_tools	string[]	[*]	Simple shape only. Supports * glob matching.
blocked_tools	string[]	[]	Simple shape only. Supports * glob matching and overrides allows.
max_actions_per_session	integer	disabled when not specified	Available in the simple and expanded shapes. Uses the assistant message count as a session proxy.
rate_limits.default	integer	—	Expanded shape only. Gives the default action limit for the active evaluation.
rate_limits.<action>	integer	—	Expanded shape only. Blocks when a specified action occurs more than the configured count.
transaction_limits.max_single_transaction	number	0.0	Expanded shape only.
transaction_limits.max_daily_total	number	0.0	Expanded shape only. Compared against total detected dollar amounts in one message string.
transaction_limits.require_approval_above	number	0.0	Expanded shape only. Returns escalate when a detected amount is equal to or more than the threshold.
tools.roles.<role>.allowed	string[]	[]	Expanded shape only. Supports * glob matching.
tools.roles.<role>.denied	string[]	[]	Expanded shape only. Supports * glob matching.
kill_switches.halt_on_suspicious_pattern	boolean	false	Expanded shape only. Blocks only when enabled and a suspicious tool pattern is detected.
kill_switches.halt_on_pii_in_action	boolean	false	Expanded shape only. Examines tool-call message content for PII.

How it works

1. The gateway gets tool actions from the message set.
2. It gets roles from the authenticated request identity when tools.roles is configured.
3. It blocks if kill_switches.halt_on_suspicious_pattern is enabled and a suspicious tool pattern is detected.
4. It enforces session or per-action limits using max_actions_per_session in the simple shape, or rate_limits in the expanded shape.
5. It checks detected dollar amounts against transaction_limits.
6. It can return escalate when an amount is equal to an approval limit.
7. It checks tool-call arguments for PII when kill_switches.halt_on_pii_in_action is enabled.
8. It applies blocked_tools, role deny, role allow, and allowed_tools glob checks.

Important behavior notes

• Tool patterns support * wildcards, including prefix, suffix, and infix patterns such as report_* or *_delete_*.
• rate_limits apply to actions in the active request. They do not use a stored RPM counter.
• The policy returns escalate only for transaction_limits.require_approval_above.
• Role rules must use an authoritative role. The policy blocks when role rules are configured and the authenticated identity has no role.
• Raw role headers do not directly select a production role.

Example scenarios

Block a dangerous tool

policy:
  agent-firewall:
    blocked_tools:
      - rm_rf

Get approval for large transfers

policy:
  agent-firewall:
    transaction_limits:
      require_approval_above: 1000.0

Examine tool arguments for PII

policy:
  agent-firewall:
    kill_switches:
      halt_on_pii_in_action: true

Best practices

• Use specified action names when possible. Use narrow * patterns only for a tool family with stable names.
• Prefer blocked_tools for dangerous actions that must stop at this time. Use tools.roles when role-aware controls are necessary.
• Use max_actions_per_session and rate_limits as runtime safety limits. They are not durable rate limits.
• Use require_approval_above for high-value transactions where human review is mandatory.

Next steps

• Prompt Injection policy — block malicious prompts before tool evaluation
• RBAC policy — identity and role controls alongside tool checks
• Policies overview — policy chain architecture