To restrict which AI Consumers or teams can reach a specific agent, use ACLs. The access.acls field defines either an allow or a deny list of identities that can access the agent. Each entry references an AI Consumer, AI Consumer Group, or Authenticated Group by name. An Authenticated Group is a dynamic group representing all consumers authenticated via a specific OAuth2 scope or claim. Access is enforced before traffic reaches the upstream agent.
For per-request authentication and identity validation, reference an AI Auth Strategy in the access.auth_strategies array, the same way you would for an AI Model. The AI Agent has its own top-level authentication mechanism: you configure the authentication through AI Auth Strategies. See AI Policy scopes for details.
An AI Agent accepts up to one AI Auth Strategy reference. ACLs are evaluated only after the AI Consumer’s identity is resolved through this authentication step.
CEL-based ACLs control access with CEL boolean expressions instead of a static list of names.
Use them when access depends on Consumer attributes or request context, not only on fixed names.
To use them, set allow_when or deny_when on the access.acls object.
Each field is an array of expressions, 1 to 1024 characters each.
The data plane evaluates the expressions on each request, against the authenticated AI Consumer and the request. They use the same field vocabulary as plugin conditions.
Configure exactly one of allow, deny, allow_when, or deny_when per access.acls object.
The following example allows requests from AI Consumers in the internal-teams AI Consumer Group, and from the AI Consumer alice:
access:
acls:
allow_when:
- 'consumer_group.names != null && "internal-teams" in consumer_group.names'
- 'consumer.username == "alice"'
Konnect compiles and type-checks each expression when you create or update the AI Agent.
Konnect rejects an entry that doesn’t compile or doesn’t evaluate to a boolean with HTTP 400.
The error message describes the problem, for example expression must evaluate to a boolean. It doesn’t identify which array entry caused it.
At runtime, entries are evaluated in order with OR semantics.
Failures to evaluate create the following responses:
- If an entry fails to evaluate and no other entry evaluates to true: The request is denied with HTTP 403.
- If an earlier entry failed but the entry evaluates to true: The request is allowed, unless you set
deny_when.
- If an entry fails to evaluate before an entry that evaluates to true: The request fails closed with HTTP 500.
- If an entry that evaluates to true comes first:** The request is denied with HTTP 403 and later entries aren’t evaluated.
When you set allow_when or deny_when, AI Gateway ignores include_consumer_groups.
It also doesn’t send the X-Consumer-Groups and X-Authenticated-Groups headers upstream.
CEL-based ACLs need Kong Gateway 3.16 or later data planes.
Data planes on earlier versions report the skipped configuration in their compatibility status.