Agent Firewall

The agent-firewall policy controls which tools an AI agent can invoke, enforces per-tool rate limits, caps financial transactions, and provides kill-switch safety nets for agentic workflows. It supports two configuration formats — a simple format for quick allow/block lists and an expanded format for enterprise-grade role-based access control, transaction limits, and monitoring.

Use this page when

• You need the exact command, config, API, or integration details for Agent Firewall.
• You are wiring automation or AI retrieval and need canonical names, examples, and constraints.
• If you want a guided rollout instead of a reference page, use the linked workflow pages in Next steps.

Primary audience

• Primary: AI Agents, Technical Engineers
• Secondary: Technical Leaders

Configuration

The policy accepts one of two mutually exclusive formats. Keeptrusts validates against both schemas and uses the first match.

Format 1: Simple (AgentFirewallSimple)

policy:
  agent-firewall:
    allowed_tools:
    - file_read
    - web_search
    - code_*
    blocked_tools:
    - code_execute_unsafe
    max_actions_per_session: 200
pack:
  name: agent-firewall-example-1
  version: 1.0.0
  enabled: true
policies:
  chain:
  - agent-firewall

Format 2: Expanded (AgentFirewallExpanded)

policy:
  agent-firewall:
    tools:
      roles:
        analyst:
          allowed:
          - read_database
          - run_query
          - export_csv
          denied:
          - drop_table
          - truncate_*
        operator:
          allowed:
          - deploy_*
          - restart_service
          denied:
          - delete_production_*
        auditor:
          allowed:
          - read_*
          denied: []
    rate_limits:
      default: 60
      run_query: 30
      deploy_prod: 5
      export_csv: 10
    max_actions_per_session: 500
    transaction_limits:
      max_single_transaction: 10000.0
      max_daily_total: 50000.0
      require_approval_above: 5000.0
    kill_switches:
      max_errors_before_halt: 5
      halt_on_pii_in_action: true
      halt_on_suspicious_pattern: true
    monitoring:
      alert_on_denied_action: true
      alert_on_rate_limit: true
      alert_threshold_percent: 80
pack:
  name: agent-firewall-example-2
  version: 1.0.0
  enabled: true
policies:
  chain:
  - agent-firewall

Fields

Simple Format — Top-Level

Property	Type	Default	Description
allowed_tools	string[]	["*"]	Glob patterns for permitted tools. "*" permits all tools not explicitly blocked.
blocked_tools	string[]	[]	Glob patterns for denied tools. Takes precedence over allowed_tools when both match.
max_actions_per_session	integer	500	Maximum total tool invocations per agent session. Range: 1–1000000.

Expanded Format — Top-Level

Property	Type	Default	Description
tools	object	—	Role-based tool access control. See tools below.
rate_limits	object	{"default": 60}	Per-tool rate limits in requests per minute. Keys are tool names or "default". Values are integers.
max_actions_per_session	integer	500	Maximum total tool invocations per agent session. Range: 1–1000000.
transaction_limits	object	—	Financial transaction constraints. See transaction_limits below.
kill_switches	object	—	Automatic halt conditions. See kill_switches below.
monitoring	object	—	Alerting and observability controls. See monitoring below.

tools

Property	Type	Default	Description
roles	object	—	Map of role names to RoleToolPolicy objects. Each key is a role name string.

tools.roles.<role> (RoleToolPolicy)

Property	Type	Default	Required	Description
allowed	string[]	—	Yes	Glob patterns for tools this role may call. minItems: 1.
denied	string[]	[]	No	Glob patterns for tools this role may not call. Takes precedence over allowed.

rate_limits

A key-value map where each key is a tool name (or "default") and each value is an integer representing the maximum requests per minute for that tool.

Key	Type	Default	Description
default	integer	60	Fallback RPM applied to tools without an explicit entry.
<tool_name>	integer	—	RPM limit for a specific tool.

transaction_limits

Property	Type	Default	Description
max_single_transaction	number	10000.0	Maximum USD per single transaction. Must be >= 0.
max_daily_total	number	50000.0	Maximum cumulative USD across all transactions per day. Must be >= 0.
require_approval_above	number	5000.0	USD threshold above which a transaction requires human approval before proceeding. Must be >= 0.

kill_switches

Property	Type	Default	Description
max_errors_before_halt	integer	5	Number of consecutive errors that trigger an automatic session halt. Range: 1–1000000.
halt_on_pii_in_action	boolean	true	Halt the session immediately if PII is detected in a tool action payload.
halt_on_suspicious_pattern	boolean	true	Halt the session if the gateway detects a suspicious behavioral pattern (e.g., rapid privilege escalation, looping).

monitoring

Property	Type	Default	Description
alert_on_denied_action	boolean	true	Emit an alert event when a tool call is denied.
alert_on_rate_limit	boolean	true	Emit an alert event when a rate limit is hit.
alert_threshold_percent	integer	80	Percentage of a rate limit at which a warning alert is emitted (before the hard limit). Range: 1–100.

Use Cases

1. Developer Sandbox — Simple Allow/Block

Restrict an agent to safe read-only tools while blocking anything destructive.

policy:
  agent-firewall:
    allowed_tools:
    - file_read
    - web_search
    - code_lint
    - code_format
    blocked_tools:
    - file_write
    - file_delete
    - shell_*
    max_actions_per_session: 100
pack:
  name: agent-firewall-example-3
  version: 1.0.0
  enabled: true
policies:
  chain:
  - agent-firewall

2. Enterprise Multi-Team — Role-Based Access

Different teams get different tool permissions through the expanded role-based format.

policy:
  agent-firewall:
    tools:
      roles:
        data_scientist:
          allowed:
          - read_database
          - run_query
          - create_visualization
          - export_csv
          denied:
          - drop_*
          - alter_*
          - delete_*
        devops:
          allowed:
          - deploy_staging
          - deploy_production
          - restart_service
          - view_logs
          denied:
          - delete_infrastructure
        intern:
          allowed:
          - read_*
          - view_*
          denied:
          - write_*
          - deploy_*
          - delete_*
    rate_limits:
      default: 60
      run_query: 20
      deploy_production: 2
    max_actions_per_session: 300
pack:
  name: agent-firewall-example-4
  version: 1.0.0
  enabled: true
policies:
  chain:
  - agent-firewall

3. Fintech Agent — Transaction Limits

An agent that processes financial operations needs strict monetary controls.

policy:
  agent-firewall:
    tools:
      roles:
        payment_processor:
          allowed:
          - initiate_transfer
          - check_balance
          - verify_identity
          - generate_receipt
          denied:
          - modify_account_*
          - override_compliance_*
    rate_limits:
      default: 30
      initiate_transfer: 10
    max_actions_per_session: 200
    transaction_limits:
      max_single_transaction: 5000.0
      max_daily_total: 25000.0
      require_approval_above: 1000.0
    monitoring:
      alert_on_denied_action: true
      alert_on_rate_limit: true
      alert_threshold_percent: 70
pack:
  name: agent-firewall-example-5
  version: 1.0.0
  enabled: true
policies:
  chain:
  - agent-firewall

4. Safety-Critical Operations — Kill Switches

For healthcare or infrastructure agents where errors must halt execution immediately.

policy:
  agent-firewall:
    tools:
      roles:
        medical_assistant:
          allowed:
          - lookup_patient_record
          - suggest_diagnosis
          - schedule_appointment
          denied:
          - prescribe_*
          - modify_dosage
    rate_limits:
      default: 20
    max_actions_per_session: 50
    kill_switches:
      max_errors_before_halt: 2
      halt_on_pii_in_action: true
      halt_on_suspicious_pattern: true
    monitoring:
      alert_on_denied_action: true
      alert_on_rate_limit: true
      alert_threshold_percent: 50
pack:
  name: agent-firewall-example-6
  version: 1.0.0
  enabled: true
policies:
  chain:
  - agent-firewall

5. Full Enterprise Configuration

A comprehensive configuration combining all sections for a production deployment.

policy:
  agent-firewall:
    tools:
      roles:
        engineer:
          allowed:
          - code_*
          - test_*
          - deploy_staging
          - read_*
          denied:
          - deploy_production
          - delete_*
        manager:
          allowed:
          - deploy_production
          - approve_*
          - read_*
          - export_*
          denied:
          - code_*
        security:
          allowed:
          - scan_*
          - audit_*
          - read_*
          - revoke_*
          denied: []
    rate_limits:
      default: 60
      deploy_production: 3
      deploy_staging: 15
      scan_vulnerability: 5
      export_report: 10
    max_actions_per_session: 500
    transaction_limits:
      max_single_transaction: 10000.0
      max_daily_total: 50000.0
      require_approval_above: 5000.0
    kill_switches:
      max_errors_before_halt: 5
      halt_on_pii_in_action: true
      halt_on_suspicious_pattern: true
    monitoring:
      alert_on_denied_action: true
      alert_on_rate_limit: true
      alert_threshold_percent: 80
pack:
  name: agent-firewall-example-7
  version: 1.0.0
  enabled: true
policies:
  chain:
  - agent-firewall

How It Works

1. Format detection — When the gateway loads the policy configuration, it validates against both the simple (AgentFirewallSimple) and expanded (AgentFirewallExpanded) schemas using a oneOf match. The first valid schema wins.

2. Tool resolution — On each agent tool call, the gateway resolves which tools are permitted:

   • Simple format: The tool name is matched against allowed_tools globs first, then blocked_tools globs. A match in blocked_tools always denies the call, even if allowed_tools also matches.
   • Expanded format: The agent's current role is looked up in tools.roles. The tool is checked against the role's allowed globs, then denied globs. Denied takes precedence.

3. Rate limiting — Each tool call increments a per-tool counter. If a tool-specific limit exists in rate_limits, that value is used; otherwise the default RPM applies. When alert_threshold_percent is exceeded, a warning event is emitted before the hard block.

4. Session cap — A running counter tracks total actions in the session. When max_actions_per_session is reached, all further tool calls are denied.

5. Transaction enforcement — For tools that carry a monetary value (detected via structured action metadata), the gateway enforces max_single_transaction, max_daily_total, and require_approval_above. Transactions above the approval threshold are paused and an approval event is emitted.

6. Kill switches — The gateway maintains a consecutive error counter. When max_errors_before_halt is reached, or PII / suspicious patterns are detected (if enabled), the entire agent session is halted and a critical alert event is emitted.

7. Event emission — All denied actions, rate-limit hits, transaction blocks, and kill-switch activations are emitted as structured events to POST /v1/events for audit and observability.

Combining With Other Policies

Policy	Interaction
prompt-injection	Runs before the agent firewall. If a prompt injection is detected, the request is blocked before tool-call evaluation begins.
pii-filter	Complementary. The PII filter redacts sensitive data from inputs/outputs, while halt_on_pii_in_action in the firewall halts the session if PII appears in tool action payloads.
quality-scorer	Runs after the agent firewall. Quality scoring evaluates the agent's final response, not individual tool calls.
content-filter	Content filtering applies to the LLM's text output. The agent firewall applies to tool invocations. Both can be active simultaneously.
rate-limiter	The top-level rate-limiter policy controls request-level throughput. The agent firewall's rate_limits control per-tool RPM within a session. Both are enforced independently.

Best Practices

• Start with the simple format for prototyping, then migrate to the expanded format when you need role-based access or transaction controls.
• Always define blocked_tools even when using allowed_tools: ["*"]. Explicit deny lists prevent accidental exposure of dangerous tools added later.
• Set max_actions_per_session conservatively. A runaway agent loop can exhaust resources quickly. Start low (50–200) and increase based on observed usage.
• Use the require_approval_above threshold for any agent that can initiate financial transactions. Human-in-the-loop approval is a critical safety net.
• Set max_errors_before_halt to 2–3 for safety-critical domains (healthcare, infrastructure). Higher values (5–10) are acceptable for developer tooling.
• Enable halt_on_pii_in_action unless you have a specific reason not to. PII in tool payloads often indicates a data-handling bug.
• Monitor alert_threshold_percent warnings in your event dashboard. Frequent 80% warnings suggest your rate limits need adjustment.
• Define roles that mirror your organizational structure. Avoid generic role names like "user" — use descriptive names like "data_scientist" or "payment_processor".
• Combine with prompt-injection to create defense-in-depth. The injection filter catches malicious prompts; the firewall catches malicious tool usage.

For AI systems

• Canonical terms: Keeptrusts, agent-firewall, policy-config.yaml, allowed_tools, blocked_tools, tools.roles, rate_limits, transaction_limits, kill_switches, monitoring, max_actions_per_session.
• Configuration formats: AgentFirewallSimple (allow/block lists) and AgentFirewallExpanded (role-based access, transaction limits, kill switches).
• Best next pages: Agent Firewall template, Prompt Injection policy, Per-Policy Configuration Catalog.

For engineers

• Start with the simple format (allowed_tools / blocked_tools) for prototyping; migrate to expanded format when you need RBAC or transaction controls.
• Validate with kt policy lint --file policy-config.yaml. Test by invoking a blocked tool and confirming a deny event in POST /v1/events.
• blocked_tools always takes precedence over allowed_tools when both match a glob pattern.
• Set max_actions_per_session conservatively (50–200) initially; increase based on observed agent behavior.
• Monitor alert_threshold_percent warnings in the events dashboard to tune rate limits before hard blocks.

For leaders

• The agent firewall provides tool-level access control for AI agents, preventing unauthorized actions (data writes, shell execution, financial transactions) without manual review.
• Transaction limits with require_approval_above inject human-in-the-loop gates for high-value operations.
• Kill switches halt runaway agents automatically, reducing blast radius of agent failures in production.
• Role-based expanded format aligns agent permissions with existing organizational roles and clearance levels.

Next steps

• Agent Firewall template — ready-to-deploy starter config
• Prompt Injection policy — block malicious inputs before tool evaluation
• Per-Policy Configuration Catalog — all 39 policy kinds
• Policies overview — policy chain architecture