How to Secure AI Agent Tool Calls
Least privilege, Gatekeeper allow/deny/require-approval, hazeld secrets, and audit timelines — without unsupported security claims.
Securing tool calls means deciding who may run which tool with which credentials, and recording what happened. HazelJS focuses on fail-closed authorization — not marketing claims of “prompt injection proof.”
Agents are powerful because tools mutate the world. Security for agents is therefore mostly tool-path security, not “a smarter system prompt.”
Threat model (practical)
Assume the model can be steered. Design so that:
- Dangerous capabilities are not registered unless needed (Skillgate).
- Registered tools still need authorization per call (Gatekeeper).
- High-impact tools need a human (
require-approval+ durable HITL). - Credentials live in a node-scoped secret store, not in prompts.
- Every decision leaves an audit trail (timelines /
hazel logs).
This page does not claim prompt-injection immunity, a hosted compliance product, or OS-level sandboxing. Agents share your Node process by default — design isolation accordingly.
Practical controls
1. Curate capabilities with Skillgate
Do not dump every OpenAPI path into the agent. Skillgate classifies skills (read / write / approval) so the model only sees a governed set.
2. Authorize with Gatekeeper
import { AgentGatekeeper, fromFunction } from '@hazeljs/agent-gatekeeper';
const gatekeeper = new AgentGatekeeper({
policies: [
fromFunction('refunds.create', async (ctx) =>
ctx.amount > 50 ? 'require-approval' : 'allow',
),
],
});
Outcomes are allow, deny, or require-approval. Confidence from Decision Runtime informs policy — it never grants permission by itself.
3. Approve sensitive ops via durable HITL
hazel approvals
hazel approve <id>
hazel deny <id>
Approvals must survive process restart when durable suspend is enabled. Chat DMs are not a control plane.
4. Store secrets on hazeld
hazel secret set OPENAI_API_KEY
hazel secret has OPENAI_API_KEY
Secrets target hazeld’s encrypted file store — local-first, not a cloud vault by default.
5. Audit with run timelines
Use hazel logs / inspector timelines to see which tools ran and which policies fired. Pair with app-level HTTP controls in the security guide and optional @hazeljs/guardrails for content/PII filters.
Inspect before you ship
hazel gatekeeper validate
hazel gatekeeper simulate
hazel gatekeeper explain
These commands help you reason about policy without executing tools — useful in CI and incident reviews.
Cross-agent calls
Multi-agent setups do not get a free pass. @Delegate, supervisors, and A2A paths still go through Gatekeeper. “The other agent asked” is not authorization.