fix(ai-gateway): Update AI Entities docs#5698
Open
tomek-labuk wants to merge 22 commits into
Open
Conversation
✅ Deploy Preview for kongdeveloper ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
tomek-labuk
added
the
ci:manual-approve:link-validation
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates the Kong AI Gateway “AI Entities” documentation to consistently use “AI *” entity naming, clarify entity semantics (notably “Policy” vs plugin language), and add/reuse shared include snippets for AI Gateway v2 entity docs.
Changes:
- Adds AI Gateway v2 minimum version metadata to the AI entities landing page and updates entity card naming/description copy.
- Refactors multiple AI entity reference pages to use “AI *” terminology consistently and to describe AI Policies as reusable configurations.
- Introduces new shared include snippets for Redis cloud auth, A2A log output fields, and A2A OpenTelemetry span attributes, and wires them into entity pages.
Reviewed changes
Copilot reviewed 16 out of 16 changed files in this pull request and generated 9 comments.
Show a summary per file
| File | Description |
|---|---|
| app/_landing_pages/ai-gateway/entities.yaml | Adds min_version and updates entity card titles/descriptions for consistent “AI *” naming. |
| app/_includes/md/ai-gateway/v2/policies/redis-cloud-auth.md | New include for Redis cloud provider auth blurb used by AI Gateway docs. |
| app/_includes/md/ai-gateway/v2/entities/otel-span-attributes.md | New include defining A2A OpenTelemetry span attributes table. |
| app/_includes/md/ai-gateway/v2/entities/log-output-fields.md | New include defining A2A log output fields table. |
| app/_ai_gateway_entities/ai-vault.md | Updates related resource naming and removes decK mention from management methods. |
| app/_ai_gateway_entities/ai-provider.md | Updates FAQs and terminology to “AI Provider/AI Model” and removes decK mention. |
| app/_ai_gateway_entities/ai-policy.md | Reframes AI Policy as reusable configuration; updates scope/lifecycle wording and links. |
| app/_ai_gateway_entities/ai-model.md | Updates related resource naming and multiple passages to “AI Model/AI Policy” terminology; removes decK mention. |
| app/_ai_gateway_entities/ai-mcp-server.md | Updates terminology, adds AI-policy-centric wording, swaps Redis auth include, and updates several links. |
| app/_ai_gateway_entities/ai-gateway.md | Updates entity description/related resources and removes decK mention for child entities. |
| app/_ai_gateway_entities/ai-data-plane-node.md | Updates related resource naming and Q/A wording to “AI Data Plane”. |
| app/_ai_gateway_entities/ai-data-plane-certificate.md | Updates related resource naming to “AI *” entities. |
| app/_ai_gateway_entities/ai-consumer.md | Updates terminology and links related to OAuth/OIDC + AI policy references. |
| app/_ai_gateway_entities/ai-consumer-group.md | Updates FAQ wording to “AI Consumer/AI Consumer Group/AI Policy” terminology. |
| app/_ai_gateway_entities/ai-consumer-credential.md | Updates terminology and OAuth/OIDC + AI policy references. |
| app/_ai_gateway_entities/ai-agent.md | Updates terminology, replaces plugin includes with AI Gateway v2 includes, and updates observability wording. |
tomek-labuk
removed
the
ci:manual-approve:link-validation
jbaross
requested changes
Jun 25, 2026
| For `http` type AI Agents, requests are proxied without A2A-specific processing. For `a2a` type AI Agents, {{site.ai_gateway}} adds protocol-aware behavior on top of plain proxying: it detects A2A requests across both JSON-RPC and REST bindings, rewrites agent-card URLs so clients discover the gateway as the canonical endpoint, and emits structured A2A telemetry to {{site.konnect_short_name}} analytics and OpenTelemetry. | ||
|
|
||
| AI Agents can be created and managed through the {{site.konnect_short_name}} UI, the {{site.ai_gateway}} API, or decK: | ||
| AI Agents can be created and managed through the {{site.konnect_short_name}} UI and the {{site.ai_gateway}} API: |
Contributor
There was a problem hiding this comment.
consider being explicit about Admin API
| Because the runtime executes inside {{site.ai_gateway}}, MCP endpoints are provisioned dynamically on demand. You don't host or scale them separately, and the same authentication, traffic control, and observability features available to traditional API traffic apply to MCP traffic at the same scale. | ||
|
|
||
| AI MCP Servers can be created and managed through the {{site.konnect_short_name}} UI, the {{site.ai_gateway}} API, or decK: | ||
| AI MCP Servers can be created and managed through the {{site.konnect_short_name}} UI and the {{site.ai_gateway}} API: |
Contributor
There was a problem hiding this comment.
As above, consider:
Suggested change
| AI MCP Servers can be created and managed through the {{site.konnect_short_name}} UI and the {{site.ai_gateway}} API: | |
| AI MCP Servers can be created and managed through the {{site.konnect_short_name}} UI and the {{site.ai_gateway}} admin API: |
| For the complete set of behaviors available as an AI Policy `type`, see the [AI policies hub](/ai-gateway/policies/). | ||
|
|
||
| **AI Policies are not shared.** Each AI Policy is an independent plugin instance tied to its parent entity's lifecycle. To apply identical configuration to two AI Models, create two separate AI Policies with matching `config`. This design ensures that deleting an AI Model deletes only its own AI Policies, not configurations used by other entities. | ||
| **AI Policies are not shared.** Each AI Policy is an independent configuration tied to its parent entity's lifecycle. To apply identical configuration to two AI Models, create two separate AI Policies with matching `config`. This design ensures that deleting an AI Model deletes only its own AI Policies, not configurations used by other entities. |
Contributor
There was a problem hiding this comment.
There's some redundancy here, you could merge this into the AI Policy scopes section
Contributor
There was a problem hiding this comment.
also, are race conditions possible if a policy is referenced by more than one entity?
| > | ||
| > {{site.ai_gateway}} does not define plugin configuration schemas under the AI Policy entity. | ||
| > For each plugin you intend to use as an AI Policy `type`, look up that plugin's reference page for its `config` shape. | ||
| > {{site.ai_gateway}} does not define policy configuration schemas under the AI Policy entity. |
| config: | ||
| title: AI Policy | ||
| description: An AI Gateway plugin instance scoped globally or to a specific AI entity. Policy instances are independent. | ||
| description: A reusable policy configuration scoped globally or to a specific AI entity. Policy instances are independent. |
Contributor
There was a problem hiding this comment.
If it can only be attached to exactly one entity it is not reusable
| ### AI Policy execution order | ||
|
|
||
| A Policy attached to a Model runs on the Service of the Model's derived primitives. That Policy runs at the [priority](/gateway/entities/plugin/#plugin-priority) determined by its type, which affects when it executes relative to other Policies on the request. | ||
| An AI Policy attached to a Model runs on the Service of the Model's derived primitives. That AI Policy runs at the [priority](/gateway/entities/plugin/#plugin-priority) determined by its type, which affects when it executes relative to other AI Policies on the request. |
Contributor
There was a problem hiding this comment.
Add ticket or spreadsheet entry to migrate priority info
Co-authored-by: jbaross <james.baross@konghq.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Fixes #issue
Preview Links
Checklist
descriptionentry in frontmatter.