AI Agent API Guardrails: Deterministic Policy vs LLM Checks

AI agent guardrails for API writes should be layered: use deterministic policy for boundaries that must never vary, an LLM check only for business context that cannot be expressed reliably in code, and human approval for whether this exact consequential change should happen now.

None of those controls can replace the others. A model-based check can interpret nuance, but it is probabilistic. A path allowlist is reproducible, but it cannot decide whether a plausible payload is appropriate. A person can understand the situation, but review quality falls when every request looks the same or hides important fields.

The safe rule is simple:

A model may recommend or reject a write inside a hard boundary. It must never expand that boundary, approve its own request, or turn an earlier human decision into permission for a changed request.

The short answer: assign each guardrail one job

“Guardrail” is an overloaded term. It may refer to prompt instructions, content filters, API authorization, tool permissions, human confirmation, or monitoring. Treating them as one interchangeable layer creates gaps.

The ordering matters. A deterministic denial is final. An LLM “allow” is only an additional condition inside the hard policy. Human approval must bind to the same request that will be executed. Provider-side permissions remain the last independent limit if an upstream control fails.

Why model-only guardrails are not an authorization system

In August 2026, NIST wrote that model-only guardrails are “not yet fully equipped” to solve agentic AI’s novel security challenges and emphasized identity, entitlements, delegation, policy, and governance. The point is not that models are useless for security. It is that a probabilistic component should not be the only component deciding whether its own proposed action can reach a real system.

OpenAI’s prompt-injection guidance makes the same architectural distinction: defense cannot rely only on filtering inputs, so deterministic systems should limit the impact even when an agent is misled.

That matters for API writes because the apparently harmless request is often the dangerous one. PATCH /accounts/42 is syntactically valid. Its JSON may match a schema. The model may offer a convincing explanation. The real questions are whether account 42 is in scope, whether the changed fields are permitted, whether the source context is trustworthy, and whether the owner intended this update now.

OWASP’s Excessive Agency guidance separates excessive functionality, permissions, and autonomy. It recommends minimizing all three, enforcing authorization outside the LLM, and requiring human approval for high-impact actions. A single “is this safe?” model prompt does not provide complete mediation because the same class of system is interpreting both the request and the rule.

Put crisp rules in deterministic policy

If a rule can be evaluated reliably in code, keep it out of the model’s discretion. Typical hard controls for an agent-facing API gateway include:

1. Submission and release-channel separation. A workspace API key can submit a write, but only a signed-in dashboard session can release it.
2. Fixed destination. Resolve the request against an owner-configured HTTPS origin, then reject private, loopback, or unexpected network routes.
3. Allowed methods. Permit only the verbs required by the workflow; do not expose DELETE because a neighboring use case needs PATCH.
4. Normalized paths. Check a canonical path against narrow prefixes or exact routes and reject malformed encoding, decoded dot-segment escapes, and redirects.
5. Bounded input and output. Enforce body, response, and time limits before a tool can become an open proxy or resource-exhaustion path.
6. Version-bound approval. Include the connection version, resolved target, method, path, query, and body in the reviewed snapshot.
7. Provider-side least privilege. Use a credential restricted to the smallest tenant, resource family, and permission set the target API supports.

The OpenID Authorization API 1.0, approved as a Final Specification in January 2026, provides useful vocabulary for this separation: a Policy Enforcement Point asks a Policy Decision Point whether a subject may perform an action on a resource in a context. It does not prescribe the policy language or prove that a policy is correct, and ActionDock does not claim to implement AuthZEN. The relevant design lesson is smaller: convert “let the agent use the API” into a concrete decision about one caller, one operation, one target, and one request context.

Hard rules should go deeper than method and path where the infrastructure permits it. If a provider can issue a field-scoped credential, enforce an optimistic-concurrency precondition, or validate an exact request schema, use that facility. ActionDock’s current deterministic connection policy does not provide field-level JSON authorization, so a path allowlist must not be described as one.

Use an LLM check for narrow semantic questions

A model check earns its place when an important rule depends on relationships in the request that would be costly or brittle to encode, yet the request is already constrained by hard policy.

For example, an owner might write:

Allow a case review update only when the request sets reviewStatus to approved, includes a non-empty evidenceReference, and changes no ownership, access, billing, deletion, or retention fields. Deny when the request does not contain enough information to verify those conditions.

That is better than “allow sensible case updates.” It names the operation, required evidence, forbidden fields, and insufficient-context outcome. The model can compare that policy with one structured method, path, query, and body. It does not need access to the provider credential, unrelated workspace history, or a general chat channel.

Even a well-written policy remains probabilistic. Similar requests can receive different classifications after a model or provider change. A malicious string can appear inside a path or body. A model can overlook a forbidden field or deny a legitimate request. Therefore:

• Treat request content as untrusted data, never as instructions.
• Require one strict machine-validated verdict rather than free-form advice.
• Deny on timeout, malformed output, uncertainty, or missing context.
• Redact likely secrets before sending the request context to the model.
• Retain a secret-free result and the evaluator version needed to understand it.
• Never let an allow verdict override a deterministic denial.
• Bind the assessment to the exact request and consume it only for that execution attempt.

If a semantic rule becomes stable enough to express as code or provider policy, promote it out of the LLM layer. Deterministic enforcement is easier to test, audit, and reason about during an incident.

How ActionDock orders the write checks today

ActionDock is a human-in-the-loop approval gateway for AI-agent API writes: an MCP server and HTTP API that puts deterministic policy, owner approval of the exact request, and server-held credentials between an agent’s tool call and a real API write. For its current integration.execute path, the external agent remains the orchestrator while ActionDock controls only the request routed through its MCP or HTTP boundary.

The current sequence is:

1. A signed-in workspace owner configures a compatible public HTTPS API connection, authentication method, allowed HTTP methods, and write-policy mode.
2. The agent submits an exact write using a non-secret connection ID. It never receives the stored target credential.
3. ActionDock applies deterministic destination, public-network, allowed-method, configured path-prefix, request-envelope, and configured unsupported-provider-domain checks.
4. The job becomes awaiting_approval. The owner reviews a preview bound to the connection version, resolved target, method, path, query, and body.
5. After the owner releases that exact snapshot, an optional reasonableness check runs for either AI policy mode. A denial, inconclusive verdict, malformed response, provider error, or timeout blocks dispatch.
6. ActionDock reloads the connection and re-creates the preview. Any change makes the approval stale. Only then does it decrypt the server-held credential and dispatch the approved request.
7. The durable job records the terminal state and the response ActionDock observed. If delivery is ambiguous, execution_unknown stops blind automatic retry.

The model check deliberately cannot release a write on its own. It runs against the owner-approved snapshot, returns only a strict allow-or-deny result, and produces a single-use proof bound to that request. It does not search the web at runtime. Enabling an AI policy mode also requires explicit acknowledgement that the approved request context and owner-authored policy will be processed by the configured AI provider.

This sequence does not make ActionDock a universal agent firewall. A direct provider key, authenticated browser, native connector, or shell path can bypass it. The gateway is an enforceable boundary only for writes routed through it.

Choosing between the three ActionDock policy modes

Every mode keeps the public-HTTPS destination, allowed-method, SSRF, approval-binding, response-size, timeout, owner-approval, and server-side handling of any configured target credential. They differ in how write paths and business reasonableness are evaluated.

manual_and_ai is the recommended combined mode because the LLM is intended to flag semantic mismatches without becoming the primary perimeter. manual_only is often the stronger choice when the target API already exposes a purpose-built endpoint and narrow provider credential.

ai_only should not be read as “the model controls everything.” It still restricts the configured destination and allowed write methods, rejects GET, requires exact owner approval, and keeps the target credential server-side. But it removes manual path scopes, so a model false allow combined with a missed human review can expose more of the configured API. That tradeoff should be explicit in threat modeling and testing.

Review the exact connection-mode contract before choosing a broader policy boundary.

Worked example: one reviewed case update

Assume an operations agent needs to propose a status change through an approved connection. Its MCP run_action arguments could contain:

{
  "action": "integration.execute",
  "workflow_id": "case-4821-review",
  "workflow_name": "Reviewed case update",
  "idempotency_key": "case-4821-review-v1",
  "input": {
    "connectionId": "<approved connection UUID>",
    "method": "PATCH",
    "path": "/cases/4821",
    "body": {
      "reviewStatus": "approved",
      "evidenceReference": "review-2026-0915"
    }
  }
}

Suppose the connection permits PATCH under /cases/ and uses manual_and_ai with the policy from the previous section.

The example shows why one control is not enough. The deterministic layer eliminates obvious out-of-bound operations. The model examines meaning inside the allowed route. The owner decides whether this concrete change is appropriate now. The provider credential should still be unable to perform unrelated administrative actions.

Test the guardrail stack as a denial system

Happy-path tests prove that a write can happen. Guardrail tests must prove that every layer refuses the wrong request and that a refusal cannot silently fall through to another mode.

Before production, test at least these cases:

1. A method absent from the connection policy.
2. A sibling path, encoded traversal, double slash, redirect, and private-network destination.
3. A valid path with a forbidden field or business operation in the body.
4. A request that omits the evidence required by the reasonableness policy.
5. Prompt-like instructions embedded in path, query, body, or owner policy.
6. Empty, malformed, oversized, slow, unavailable, and contradictory model responses.
7. A connection or payload change after the human preview is created.
8. Reuse of an assessment or approval against a different request.
9. An ambiguous provider response that must not trigger blind retry.
10. A direct browser, native connector, or leaked credential that bypasses the gateway entirely.

The final case is architectural, not a unit test. If the agent retains another write path, document that residual risk or remove the path. No policy inside ActionDock can govern traffic that never reaches ActionDock.

For the evidence to retain from these checks, use the AI agent audit trail guide. For uncertain delivery, follow the retry and reconciliation guide.

What this guardrail stack cannot prove

Layered controls reduce the chance and blast radius of a bad API write. They do not prove that:

• the agent’s overall plan is correct;
• the owner noticed every consequence in the preview;
• the provider applied the request exactly once;
• the provider’s current state still matches its response;
• a model verdict is free of false allows or false denials;
• a workflow satisfies a legal, regulatory, or organizational requirement; or
• the agent lacks a bypass outside the supervised route.

An execution record is evidence of what ActionDock observed, not independent attestation of the target system. Read back important state where the provider supports it, reconcile execution_unknown, and keep recovery procedures outside the agent’s discretion.

Frequently asked questions

Are LLM guardrails safe enough to authorize API writes?

Not as the only authorization layer. Use them to assess a narrow semantic policy after deterministic destination, method, network, and path controls where configured. Deny on uncertainty, bind the result to one exact request, and require a separate human decision for consequential writes.

When should I use deterministic policy without an LLM check?

Use it when the required operation can be expressed with a purpose-built provider credential, one destination, a small method set, and narrow paths. Fewer probabilistic dependencies make the boundary easier to test. Add a model check only when a material rule genuinely depends on request semantics that hard controls do not cover.

Does human approval replace API policy?

No. Reviewers should see only requests that already passed hard policy, and their approval must bind to the exact version that will execute. Otherwise fatigue, hidden fields, or a post-review change can turn “approve” into a broader capability.

Does MCP provide these downstream guardrails automatically?

No. The current MCP tools specification describes tools as designed for model-controlled discovery and invocation while explicitly not mandating a particular interaction model. It recommends confirmation for sensitive operations and requires servers to validate inputs and implement access controls. The MCP authorization specification covers authorization at the HTTP transport layer. The MCP server still needs application-specific controls for the downstream API request.

Which ActionDock mode should I start with?

Start with manual_only for a narrowly scoped route. Move to manual_and_ai when you can state a specific semantic rule, have tested both false allows and false denials, and accept AI-provider processing of the approved request context. Treat ai_only as an advanced, broader boundary rather than an easier default.

Build the smallest enforceable write boundary

Start with one target API, one required method, one narrow route, one accountable owner, and one reconciliation procedure. Keep rules deterministic until a real business condition requires semantic interpretation; then add a fail-closed LLM check without letting it widen the perimeter.

Describe the API write you need to supervise. To evaluate the implementation first, review the connection modes and first safe write workflow.