Concepts

Execution Gate

The Execution Gate is AgentCop's enforcement layer — a programmable checkpoint that runs before every tool call.

The Problem It Solves

Without a gate, the moment an agent decides to call a tool, that tool executes immediately. The agent's decision is the only check. If the agent has been manipulated — by a prompt injection, a malicious tool description, or a compromised upstream agent — the tool call proceeds regardless.

The Execution Gate inserts a mandatory evaluation step between the agent's decision and the tool's execution.

text

Without Gate:
  Agent → [tool call] → executes immediately → consequences

With Gate:
  Agent → [tool call] → ExecutionGate.evaluate()
                              ↓
                    ┌─────────────────┐
                    │  ALLOW          │ → tool executes
                    │  BLOCK          │ → raises AgentCopBlockError
                    │  REQUIRE APPROVAL│ → pauses, notifies human
                    └─────────────────┘

Basic Usage

python

from agentcop import ExecutionGate, GatePolicy

gate = ExecutionGate(
    policy=GatePolicy(
        allow=["web_search", "read_file"],
        block=["shell_execute", "delete_file"],
        require_approval=["send_email", "write_file", "api_post"]
    )
)

# Wrap a LangChain tool
from langchain.tools import ShellTool
safe_shell = gate.wrap(ShellTool(), name="shell_execute")

# Now shell commands require gate approval

Policy Configuration

Gate policies are defined as code, which means they can be version-controlled alongside your agent.

python

# Policy as code — version-control your agent's permissions
policy = GatePolicy.from_yaml("""
agent_id: customer-support-bot
version: "1.2"

allow:
  - web_search
  - read_knowledge_base
  - send_slack_notification

require_approval:
  - send_email
  - create_ticket
  - update_customer_record

block:
  - shell_execute
  - delete_record
  - access_payment_system

on_block: raise  # Options: raise, log, alert
on_violation_notify: security@company.com
""")

Handling Blocked Calls

python

from agentcop.exceptions import AgentCopBlockError, ApprovalRequiredError

try:
    result = gated_agent.run(task)
except AgentCopBlockError as e:
    print(f"Blocked: {e.tool_name} — {e.reason}")
    # Log, alert, escalate
except ApprovalRequiredError as e:
    approval = request_human_approval(e.tool_name, e.parameters)
    if approval.granted:
        result = e.retry_with_approval(approval.token)

Warning

The Gate does not guarantee security. A sufficiently sophisticated prompt injection may convince an allow-listed tool to take harmful actions within its permitted scope. Defense in depth requires all three layers.