AI agents need tools. But giving an agent direct access to production systems is like handing root credentials to an intern. The problem is not the agent’s intent. The problem is that tool authorization is binary: allowed or denied. No context. No approval flow. No audit trail.
Agent-ToolTrust sits between the agent and the tool. It intercepts every tool call, applies policy, and either executes, denies, or escalates to a human. The project shipped with 83 real agents tested across 10 frameworks, zero mocks, and a field test report that documents 2,490 passing tests and 7 instructive failures.
Where the Gatekeeper Sits
The gatekeeper does not wrap the LLM. It wraps the tool. The agent still decides which tool to call. The gatekeeper decides whether that call reaches the system.
Execution flow:
- Agent selects a tool and generates parameters.
- Gatekeeper intercepts the call before execution.
- Policy engine evaluates context: environment, tool name, parameters, caller identity.
- Decision: approve, deny, or escalate to human review.
- If approved, the tool executes and returns results to the agent.
- All decisions log to an audit trail.
This placement matters. If you intercept before tool selection, you lose the agent’s reasoning. If you intercept after execution, you are auditing damage instead of preventing it.
Policy Schema and Context Awareness
Agent-ToolTrust policies are not allow-lists. They are conditional rules that evaluate context.
Policy structure:
from agent_tooltrust import Policy, ToolContext
policy = Policy(
name="production_delete_requires_approval",
condition=lambda ctx: (
ctx.environment == "production" and
ctx.tool_name.startswith("delete_")
),
action="require_approval",
approvers=["ops-team@example.com"]
)
# Context passed to every policy evaluation
context = ToolContext(
environment="production",
tool_name="delete_database",
parameters={"db_id": "customer-prod-001"},
caller="agent-workflow-runner",
timestamp="2026-08-13T20:01:53Z"
)The same tool call behaves differently in staging and production. A read on public documentation auto-approves. A read on customer data triggers review. This is authorization, not reachability.
Approval Workflow Without Blocking the Agent
Human-in-the-loop approval introduces latency. The agent cannot wait synchronously without losing context or timing out.
Async approval pattern:
- Gatekeeper pauses the tool call and emits an approval request.
- Agent receives a pending token and continues other work or enters a wait state.
- Human reviewer sees the request in a queue (Slack, email, web UI).
- Reviewer approves or denies with optional justification.
- Gatekeeper resumes the tool call or returns a denial to the agent.
The agent’s state must persist across the approval window. If the agent is stateless or ephemeral, the gatekeeper needs to serialize the call context and restore it after approval. This is where most implementations break. Agent-ToolTrust uses a callback registry that maps pending tokens to resumable execution contexts.
Audit Trail Schema and Query Patterns
Every tool call decision logs to a structured audit trail. This is not optional. If you cannot query denied calls, you cannot debug policy gaps. If you cannot query approved calls, you cannot detect abuse.
Audit record schema:
| Field | Type | Purpose |
|---|---|---|
call_id | UUID | Unique identifier for this tool invocation |
timestamp | ISO 8601 | When the call was intercepted |
agent_id | String | Which agent requested the tool |
tool_name | String | Tool being called |
parameters | JSON | Serialized tool arguments |
environment | String | Execution context (prod, staging, dev) |
decision | Enum | approved, denied, escalated |
policy_matched | String | Which policy triggered the decision |
approver | String (optional) | Human who approved (if escalated) |
justification | String (optional) | Why the decision was made |
Query patterns for post-incident analysis:
# Find all denied delete calls in production last week
denied_deletes = audit_trail.query(
decision="denied",
tool_name__startswith="delete_",
environment="production",
timestamp__gte="2026-08-06T00:00:00Z"
)
# Find all escalated calls that took longer than 5 minutes to approve
slow_approvals = audit_trail.query(
decision="escalated",
approval_latency__gt=300
)The audit trail is append-only. No deletions. No updates. This is forensic evidence, not application state.
Field Test Results and Failure Modes
The project tested 83 real agents across 10 frameworks: LangChain, LlamaIndex, AutoGPT, CrewAI, Semantic Kernel, and others. No mocks. No stubs. Real LLM calls, real tool execution, real policy evaluation.
Test matrix:
- 2,490 total tests
- 83/83 agents passed
- 7 failures (all resolved before release)
Instructive failures:
- State loss on approval timeout: Agent context expired before human approved. Fixed by extending TTL on pending tokens.
- Policy race condition: Two agents called the same tool simultaneously. One approval applied to both. Fixed by scoping approvals to
call_id, nottool_name. - Audit log overflow: High-frequency tool calls filled disk in 48 hours. Fixed by adding log rotation and compression.
- Parameter serialization failure: Tool with binary blob parameter crashed the audit logger. Fixed by base64-encoding non-JSON-serializable parameters.
- Approval notification delay: Slack webhook retries caused duplicate approval requests. Fixed by deduplicating on
call_id. - Policy evaluation latency: Complex policy with 12 conditions added 800ms per call. Fixed by caching policy compilation.
- Callback registry leak: Denied calls never removed from registry. Fixed by adding TTL-based eviction.
These failures only surfaced under real agent load. Unit tests passed. Mocks passed. Real agents broke.
Deployment Shape and Integration Points
Agent-ToolTrust is a Python library, not a service. It runs in-process with the agent. This reduces latency but couples the gatekeeper to the agent’s runtime.
Integration options:
| Pattern | Latency | Isolation | Best For |
|---|---|---|---|
| In-process library | <10ms | None | Single-tenant agents, low-risk tools |
| Sidecar proxy | 20-50ms | Process boundary | Multi-tenant agents, shared policy |
| Remote service | 100-300ms | Network boundary | Centralized audit, cross-agent policy |
The pip package (agent-tooltrust) defaults to in-process. For multi-agent deployments, wrap it in a gRPC service and deploy as a sidecar.
Example integration with LangChain:
from langchain.agents import initialize_agent
from langchain.tools import Tool
from agent_tooltrust import GatekeeperTool, Policy
# Wrap existing tool with gatekeeper
raw_tool = Tool(
name="delete_database",
func=delete_database_impl,
description="Delete a database by ID"
)
gatekeeper_tool = GatekeeperTool(
tool=raw_tool,
policies=[production_delete_policy],
audit_logger=audit_trail
)
# Agent uses gatekeeper-wrapped tool
agent = initialize_agent(
tools=[gatekeeper_tool],
llm=llm,
agent="zero-shot-react-description"
)The agent sees the same tool interface. The gatekeeper intercepts before execution.
Observability and Policy Tuning
You cannot tune policies without observability. The gatekeeper exposes metrics for policy evaluation, approval latency, and denial rates.
Key metrics:
- Approval rate by tool: Which tools trigger the most human reviews?
- Denial rate by policy: Which policies are too strict or too loose?
- Approval latency: How long do humans take to respond?
- Policy evaluation time: Which policies slow down tool calls?
If approval latency exceeds 5 minutes, your policy is too strict or your approval queue is understaffed. If denial rate is below 1%, your policy is too loose or your agents are not testing boundaries.
Security Boundaries and Threat Model
The gatekeeper assumes the agent is not malicious but is unreliable. It does not defend against a compromised agent runtime. If an attacker controls the agent process, they can bypass the gatekeeper by calling tools directly.
Threat model:
| Threat | Mitigated | Not Mitigated |
|---|---|---|
| Agent calls wrong tool by mistake | Yes | No |
| Agent calls correct tool with wrong parameters | Yes | No |
| Agent calls tool in wrong environment | Yes | No |
| Compromised agent bypasses gatekeeper | No | Yes |
| Compromised gatekeeper approves all calls | No | Yes |
For defense against compromised agents, deploy the gatekeeper as a remote service with network-level isolation. The agent cannot bypass what it cannot reach.
Technical Verdict
Use Agent-ToolTrust when:
- You are deploying agents with access to production systems.
- You need context-aware authorization, not just allow-lists.
- You need an audit trail for compliance or post-incident analysis.
- You can tolerate 10-50ms latency per tool call.
Avoid it when:
- Your tools are read-only or sandboxed.
- Your agents run in ephemeral, stateless environments where approval workflows cannot resume.
- You need sub-millisecond tool execution.
- You are defending against malicious agents (use network isolation instead).
The project proves that real-agent field testing catches failures that mocks hide. The 7 failures documented in the field test report are worth more than 2,490 passing tests. If you are building agent infrastructure, test with real agents or do not ship.