Gate API
Manage execution gates — the enforcement layer that runs before every tool call.
The Gate API is the runtime enforcement core of AgentCop. Every time an agent attempts to call a tool, your integration calls POST /api/gate/evaluate first. The gate checks the tool call against the agent's policy and returns a decision: allow it, block it, or pause and wait for human approval.
POST /api/gate/evaluate
/api/gate/evaluate
Evaluate whether a tool call should be allowed, blocked, or routed to a human approver. Called by the AgentCop runtime module before every tool execution. Typically responds in under 10ms.
Request body
{
"agent_id": "customer-support-bot",
"tool_name": "send_email",
"parameters": {
"to": "customer@example.com",
"subject": "Your order update"
},
"context": {
"run_id": "run_xyz789",
"triggered_by": "user: update customer on order status"
}
}| Field | Type | Required | Description |
|---|---|---|---|
agent_id | string | Yes | Identifier matching the agent's registered policy |
tool_name | string | Yes | Name of the tool the agent intends to call |
parameters | object | Yes | Tool call parameters, used for parameter-level policy evaluation |
context.run_id | string | No | Current run identifier, included in gate logs |
context.triggered_by | string | No | Human-readable description of what triggered the tool call |
Response
{
"decision": "require_approval",
"reason": "send_email requires human approval per policy v1.2",
"approval_request_id": "apr_abc123",
"policy_version": "1.2",
"evaluated_at": "2026-04-06T14:23:11Z"
}| Decision value | Meaning |
|---|---|
allow | Tool call is permitted. Proceed immediately. |
block | Tool call is denied. Do not execute. Surface reason to the agent. |
require_approval | Pause execution and wait. Poll GET /api/approvals/{approval_request_id} for the human decision. |
When the decision is require_approval, approval_request_id is set and can be passed directly to the Approvals API.
GET /api/gate/policy/{agent_id}
/api/gate/policy/{agent_id}
Returns the current gate policy for a specific agent. The policy defines which tools are always allowed, which are always blocked, which require approval, and what parameter-level constraints apply.
Path parameters
| Parameter | Type | Description |
|---|---|---|
agent_id | string | The agent identifier |
PUT /api/gate/policy/{agent_id}
/api/gate/policy/{agent_id}
Replace the gate policy for an agent. Accepts the same YAML or JSON policy format. The new policy takes effect immediately — in-flight evaluations already under way complete against the previous policy version.
Policy updates are versioned and the prior version is retained in audit history. Use GET /api/gate/policy/{agent_id} to confirm the update was applied.
GET /api/gate/log/{agent_id}
/api/gate/log/{agent_id}
Returns recent gate decisions for an agent, newest first. Useful for auditing tool call patterns and diagnosing unexpected blocks or approvals. Supports ?page= and ?limit= query parameters (default limit: 50, max: 500).
Response
{
"agent_id": "customer-support-bot",
"decisions": [
{
"tool_name": "send_email",
"decision": "require_approval",
"timestamp": "2026-04-06T14:23:11Z",
"run_id": "run_xyz789"
},
{
"tool_name": "shell_execute",
"decision": "block",
"timestamp": "2026-04-06T14:22:55Z",
"run_id": "run_xyz789"
}
],
"total": 47,
"page": 1
}