Showcase: kong-plugin-agent-guard — Independent policy governance and offline Ed25519 verification for AI agents

[kenneth-schoultz]

Hi Kong community! 👋

We have published an open-source Kong Gateway plugin, kong-plugin-agent-guard, designed for engineering teams running AI agents, LangChain/CrewAI/LlamaIndex workflows, or MCP tool servers through Kong.

• LuaRocks package: https://luarocks.org/modules/complyee/kong-plugin-agent-guard
• Source repository & tests: https://github.com/complyee/kong-plugin-agent-guard
• Docs hub issue: feat(hub): add community plugin kong-plugin-agent-guard (AI agent policy gate) developer.konghq.com#7935
• Architecture & integration guide: https://agent-cr.com/plugins#kong-gateway

The Problem It Solves

When autonomous AI agents propose API calls (initiating payments, database exports, infrastructure changes), LLMs should not self-authorize their own tool executions.

kong-plugin-agent-guard turns Kong into an independent Enforcement Point. Every sensitive tool call is gated before Kong forwards it to your upstream API, verifying who is asking, what action is requested, and whether an authentic cryptographic grant or human approval exists.

Three Operating Modes

• decide (Online mode, default): Intercepts the request in Kong's access phase, calculates a SHA-256 fingerprint of the request body (the payload never leaves your network), queries your Agent Control Room (ACR) workspace, and fails closed (403 refused, 202 held for human approval, 503 if no answer) unless explicitly authorized.
• verify (Offline zero-trust mode): Verifies caller-provided acr-grant-v3 signed grants locally inside Kong using Ed25519 public-key cryptography, against the published key set. No call to the policy engine per request.
• verify_jwt (Standard JWT mode): After a JWT plugin has verified a grant JWT against the published JWK Set, binds it to this agent, route and request body.

In decide mode, the plugin attempts best-effort, non-blocking outcome reporting in the log phase (ngx.timer.at). This is audit evidence, not durable delivery.

Quick Start

1. Install via LuaRocks:

luarocks install kong-plugin-agent-guard

2. Load the plugin in kong.conf and restart Kong:

plugins = bundled,agent-guard

3. Enable on a route (declarative kong.yml):

_format_version: "3.0"
services:
  - name: payments
    url: http://payments.internal:8080
    routes:
      - name: transfers
        paths: ["/payments/transfers"]
        plugins:
          - name: agent-guard
            config:
              gateway_url: https://<workspace>.agent-cr.com/api/public/v1/gateway
              api_key: "{vault://env/acr-api-key}"
              action_map:
                "POST /payments/transfers": payments.transfer.create

Or via the Admin API:

curl -X POST http://localhost:8001/services/payments/routes/transfers/plugins \
  --data name=agent-guard \
  --data config.gateway_url=https://<workspace>.agent-cr.com/api/public/v1/gateway \
  --data config.api_key='{vault://env/acr-api-key}' \
  --data 'config.action_map.POST /payments/transfers=payments.transfer.create'

See the README for prerequisites (workspace, registered agents, rules per mapped action, vault references) and retry/idempotency guidance.

We would love to hear feedback, feature requests, or questions from the Kong community!

[Sadrak2017]

A pending approval isn't proof that the action completed. If the upstream performs it but the caller times out, could a retry with the same grant execute it again?

We use Sinaps Studio from SinapsData to orchestrate agents and monitor their activity. In that workflow, separating authorization, execution attempts and confirmed outcomes helps when investigating retries or missing results. A missing outcome report should stay unknown until there's evidence of what happened.

How does the plugin handle an outcome report lost during a Kong worker restart?

[kenneth-schoultz]

Hi @Sadrak, thank you for the sharp questions and the concrete orchestration context — both hit real boundaries.

1. Could a retry with the same grant execute upstream again after a timeout?

Yes, it could. An Agent Control Room grant is a cryptographically signed authorization permit bound to the agent, action and payload fingerprint. It is not a distributed transaction lock and not an exactly-once execution guarantee.

• In verify mode, if the upstream performs the work and the caller times out before reading the response, a retry carrying the same unexpired grant token passes signature and payload-hash verification and is forwarded again.
• In decide mode, a caller retry triggers a fresh decision request. If the rules and velocity limits still permit it, a new grant is issued and the request is forwarded again.
• The plugin's idempotency header applies only to its own API calls to Agent Control Room; it does not deduplicate upstream mutations.

So the guard belongs at the service performing the side effect: an Idempotency-Key header or a unique business-operation reference (e.g. refund-<payment_id>), kept stable across retries and across approval resumption even when a new decision is issued. The decision id should be recorded alongside it for governance provenance, but never used as the sole business-operation key. After a timeout, reconcile against the upstream operation record before retrying — the side effect may have happened even when its response was lost.

2. What happens to an outcome report lost during a Kong worker restart?

In decide mode the log phase schedules one non-blocking ngx.timer.at(0, ...) callback. There is no retry queue, durable spool or delivery guarantee.

If a worker exits or restarts while the callback is queued or running:

1. OpenResty marks the callback premature = true.
2. The plugin logs a warning and returns immediately without attempting network I/O.
3. The report is not retried and not spooled — it is dropped.

In that case the outcome simply stays unknown in Agent Control Room: the authorization decision was already recorded during the decision call, independently of the timer, but no terminal execution evidence arrives. Nothing is inferred from silence — it is not marked executed, refused, pending or unexecuted. verify and verify_jwt do not schedule this report at all.

Your three-way distinction is exactly the model we document: authorization (did policy permit it), execution attempt (was it forwarded, and how many times), and confirmed outcome (did the business operation complete). For critical workflows orchestrated through a platform like Sinaps Studio, the gateway timer should be treated as a lightweight convenience; authoritative outcome confirmation should come from the service executing the work or from a reconciliation pipeline posting evidence back to the decision record.

We have added dedicated sections on execution idempotency boundaries and outcome-reporting limitations to the repository README, plus tests covering the premature-callback and failed-delivery paths.

Thanks again for taking the time to dig into these edge cases — this is exactly the review the plugin needed.