Skip to content

feat(ai-gateway): Align docs with 0.7.0 API spec #6554

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
tomek-labuk wants to merge 1 commit into
base: release/ai-gateway-2.0
Choose a base branch
from
Open

feat(ai-gateway): Align docs with 0.7.0 API spec #6554

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 19 additions & 9 deletions app/_ai_gateway_entities/ai-agent.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,8 @@ related_resources:
url: /ai-gateway/entities/
- text: AI Policy entity
url: /ai-gateway/entities/ai-policy/
- text: AI Identity Provider entity
url: /ai-gateway/entities/ai-identity-provider/
- text: AI Consumer Group entity
url: /ai-gateway/entities/ai-consumer-group/
- text: A2A protocol specification
Expand Down Expand Up @@ -65,6 +67,13 @@ faqs:
Set the [`access.acls`](#schema-aigateway-agent-access) field on the AI Agent with an allow list or a deny list. Each entry is a string that
references an AI Consumer, AI Consumer Group, or Authenticated Group by name.

- q: How do I authenticate requests to an AI Agent?
a: |
Reference an [AI Identity Provider](/ai-gateway/entities/ai-identity-provider/) by name or id in the AI Agent's
[`access.identity_providers`](#schema-aigateway-agent-access) array, the same field used on AI Models. An AI Agent
currently accepts up to one AI Identity Provider reference. Attaching an authentication AI Policy directly to an
AI Agent's `policies` field isn't supported.

- q: How do I attach AI Policies to an AI Agent?
a: |
Configuration that applies to the AI Agent goes through the [AI Policy entity](/ai-gateway/entities/ai-policy/).
Expand Down Expand Up @@ -140,7 +149,7 @@ rows:

When an Agent has type `a2a`, proxied traffic is processed in four phases:

1. **Access**. Detects whether the request is an A2A operation (JSON-RPC or REST binding). When statistics logging is enabled, this starts an OpenTelemetry span and records the request body for payload logging if that's also enabled.
1. **Access**. Detects whether the request is an A2A operation (JSON-RPC or REST binding). This starts an OpenTelemetry span, and records the request body for payload logging if that's enabled.
1. **Header filter**. Detects streaming responses (`Content-Type: text/event-stream`) and records time to first byte. Buffers agent-card responses for URL rewriting.
1. **Body filter**. Streams SSE chunks through to the client without buffering. Buffers non-streaming responses to extract task metadata. Rewrites agent-card URLs to the gateway address. Emits analytics at end of response.
1. **Log**. Finalizes the OpenTelemetry span with task state, task ID, and any error information.
Expand Down Expand Up @@ -282,14 +291,14 @@ When an upstream agent returns an agent card, the runtime rewrites the [`url`](#

## Logging and observability

To track agent performance, debug issues, and monitor A2A traffic patterns, enable statistics logging. {{site.ai_gateway}} emits structured A2A telemetry that flows to {{site.konnect_short_name}} analytics, logging plugins, and OpenTelemetry for full visibility into agent operations.
For `a2a` type Agents, {{site.ai_gateway}} automatically emits structured A2A telemetry to track agent performance, debug issues, and monitor A2A traffic patterns. This telemetry flows to {{site.konnect_short_name}} analytics, logging plugins, and OpenTelemetry for full visibility into agent operations, with no separate toggle required.

The telemetry data is emitted into the `ai.a2a` namespace (consumed by {{site.konnect_short_name}} analytics and logging AI Policies) and creates a `kong.a2a` child span when you've configured [{{site.base_gateway}} tracing](/gateway/tracing/). For the canonical metric and attribute list, see [A2A metrics](/ai-gateway/ai-otel-metrics/#a2a-metrics).

{:.info}
> When statistics logging is enabled, the runtime removes the `Accept-Encoding` request header
> before forwarding to the upstream. This prevents compressed responses that the runtime can't
> parse for metadata extraction.
> For `a2a` type Agents, the runtime removes the `Accept-Encoding` request header before forwarding
> to the upstream. This prevents compressed responses that the runtime can't parse for metadata
> extraction.

Payload logging additionally captures request and response bodies. Payloads are truncated at the configured payload size limit.

Expand All @@ -305,15 +314,17 @@ You can view A2A analytics in {{site.konnect_short_name}} Explorer and Dashboard

### OpenTelemetry span attributes

When statistics logging is enabled and {{site.base_gateway}} tracing is configured, the runtime creates a `kong.a2a` child span with the following attributes:
For `a2a` type Agents, when {{site.base_gateway}} tracing is configured, the runtime creates a `kong.a2a` child span with the following attributes:

{% include md/ai-gateway/v2/otel-span-attributes.md %}

## Access control

To restrict which AI Consumers or teams can reach a specific agent, use ACLs. The [`access.acls`](#schema-aigateway-agent-access) field defines either an `allow` or a `deny` list of identities that can access the agent. Each entry references an [AI Consumer](/ai-gateway/entities/ai-consumer/), [AI Consumer Group](/ai-gateway/entities/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, attach an authentication AI Policy to the AI Agent.
For per-request authentication and identity validation, reference an [AI Identity Provider](/ai-gateway/entities/ai-identity-provider/) in the [`access.identity_providers`](#schema-aigateway-agent-access) array, the same way you would for an [AI Model](/ai-gateway/entities/ai-model/#access-control). Attaching an authentication AI Policy directly to the AI Agent's `policies` field isn't supported; authentication for AI Agents is configured exclusively through AI Identity Providers.

An AI Agent currently accepts up to one AI Identity Provider reference. ACLs are evaluated only after the AI Consumer's identity is resolved through this authentication step.

## Attach AI Policies

Expand All @@ -326,7 +337,7 @@ For available policy types and configuration, see the [AI Policy entity](/ai-gat
Before creating an AI Agent with access restrictions, create an AI Consumer Group to reference in [`access.acls`](#schema-aigateway-agent-access).
This example references a group named `internal-teams`. See [Set up an AI Consumer Group](/ai-gateway/entities/ai-consumer-group/#set-up-an-ai-consumer-group) to create it, or substitute the name of your own AI Consumer, AI Consumer Group, or Authenticated Group in `access.acls.allow`.

The following example creates an `a2a` Agent that proxies traffic to an upstream A2A agent at `https://booking-agent.internal.kongair.com`, with statistics logging enabled and access restricted to the `internal-teams` Consumer Group.
The following example creates an `a2a` Agent that proxies traffic to an upstream A2A agent at `https://booking-agent.internal.kongair.com`, with access restricted to the `internal-teams` Consumer Group.

{:.info}
> This example proxies to a placeholder upstream at `https://booking-agent.internal.kongair.com`. Substitute the URL of your own running A2A agent in [`config.url`](#schema-aigateway-agent-config-url). Because this Agent has `type: a2a`, requests must use the A2A JSON-RPC envelope (`jsonrpc: "2.0"`, `id`, `method: "message/send"`, `params.message` with `kind` and `messageId`). A flat `{"message": {...}}` body without that envelope is rejected by the upstream agent itself (for example, `"Invalid Request: jsonrpc must be 2.0"`), not by {{site.ai_gateway}}.
Expand All @@ -348,7 +359,6 @@ data:
paths:
- /kongair-flight-booking
logging:
statistics: true
payloads: false
max_payload_size: 1048576
{% endentity_example %}
Expand Down
35 changes: 24 additions & 11 deletions app/_ai_gateway_entities/ai-identity-provider.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ permalink: /ai-gateway/entities/ai-identity-provider/
breadcrumbs:
- /ai-gateway/
- /ai-gateway/entities/
description: Configure inbound AI Consumer authentication for AI Models in {{site.ai_gateway}}.
description: Configure inbound AI Consumer authentication for AI Models and AI Agents in {{site.ai_gateway}}.
schema:
api: konnect/ai-gateway
path: /schemas/AIGatewayIdentityProvider
Expand All @@ -27,6 +27,8 @@ related_resources:
url: /ai-gateway/entities/ai-model/
- text: AI Model Provider entity
url: /ai-gateway/entities/ai-model-provider/
- text: AI Agent entity
url: /ai-gateway/entities/ai-agent/
- text: AI Consumer entity
url: /ai-gateway/entities/ai-consumer/
- text: AI Consumer Group entity
Expand All @@ -48,16 +50,23 @@ faqs:
AI Identity Provider simultaneously. An AI Consumer's request is authenticated
if it satisfies either provider.

- q: Can an AI Agent use an AI Identity Provider too?
a: |
Yes. Reference an AI Identity Provider by `name` or `id` in the AI Agent's `access.identity_providers`
array, the same field used on AI Models. An AI Agent currently accepts up to one AI Identity Provider
reference. Attaching an authentication AI Policy directly to an AI Agent's `policies` field isn't
supported; AI Identity Providers are the only supported way to authenticate AI Agent traffic.

- q: What happens when a request carries no valid credentials?
a: |
{{site.ai_gateway}} treats the request as an anonymous AI Consumer. A request-termination
policy on that anonymous AI Consumer returns `401 Unauthorized` before the request reaches
the AI Model.
the AI Model or AI Agent.

- q: Can I reuse the same AI Identity Provider across multiple AI Models?
- q: Can I reuse the same AI Identity Provider across multiple AI Models or AI Agents?
a: |
Yes. Create an AI Identity Provider once and reference it by `name` or `id` in the
`access.identity_providers` array of any AI Model in the same gateway.
`access.identity_providers` array of any AI Model or AI Agent in the same gateway.

- q: Which OIDC flows does the openid-connect type support?
a: |
Expand All @@ -69,14 +78,14 @@ faqs:

## What is an AI Identity Provider?

Your [AI Models](/ai-gateway/entities/ai-model/) often need access control: some teams should reach certain AI Models and others should not, and you need a way to verify who is calling before a request consumes tokens or touches sensitive data. An AI Identity Provider lets you declare an inbound authentication mechanism at the gateway level and attach it to specific AI Models.
Your [AI Models](/ai-gateway/entities/ai-model/) and [AI Agents](/ai-gateway/entities/ai-agent/) often need access control: some teams should reach certain AI Models or AI Agents and others should not, and you need a way to verify who is calling before a request consumes tokens or touches sensitive data. An AI Identity Provider lets you declare an inbound authentication mechanism at the gateway level and attach it to specific AI Models or AI Agents.

Use AI Identity Providers to:
* Authenticate API keys and map them to [AI Consumers](/ai-gateway/entities/ai-consumer/)
* Authenticate enterprise users through an existing identity provider (Okta, Azure AD, Google, or any OIDC-compliant IdP) without managing keys manually
* Apply different authentication to different models. For example, API keys for internal automation and OIDC bearer tokens for user-facing applications.
* Apply different authentication to different models or agents. For example, API keys for internal automation and OIDC bearer tokens for user-facing applications.

An AI Identity Provider manages inbound authentication, which is distinct from the outbound credentials managed by an [AI Model Provider](/ai-gateway/entities/ai-model-provider/). When an AI Consumer calls an AI Model, the AI Identity Provider checks who they are. The AI Model then uses the AI Model Provider's credentials to forward the request upstream.
An AI Identity Provider manages inbound authentication, which is distinct from the outbound credentials managed by an [AI Model Provider](/ai-gateway/entities/ai-model-provider/). When an AI Consumer calls an AI Model or AI Agent, the AI Identity Provider checks who they are. The AI Model then uses the AI Model Provider's credentials to forward the request upstream; an AI Agent proxies the now-authenticated request directly to its upstream agent.

The following diagram shows where authentication fits in the request pipeline:

Expand Down Expand Up @@ -178,12 +187,14 @@ The default `config.auth_methods` are `bearer` and `client_credentials`. If your

To map the token to an existing AI Consumer, set `config.consumer_claims` to an array of path segments locating the claim in the token that carries the AI Consumer identifier (for example, `[["user", "info", "id"]]` to map to a nested `user.info.id` claim). If no mapping is needed, set `config.consumer_optional: true` to allow unauthenticated token holders through ACL checks.

`config.cache_tokens_salt` is required for `openid-connect` AI Identity Providers. It's a string used to generate the cache key for token endpoint request caching; set it to any unique value for this provider instance.

{:.warning}
> All AI Models in the same {{site.ai_gateway}} that use OIDC authentication must reference the same `openid-connect` AI Identity Provider. Using different OIDC providers across models in the same {{site.ai_gateway}} is not supported.

## Assigning an AI Identity Provider to an AI Model
## Assigning an AI Identity Provider

An AI Identity Provider takes effect only when assigned to an [AI Model](/ai-gateway/entities/ai-model/). Reference the provider by `name` or `id` in the `access.identity_providers` array on the AI Model:
An AI Identity Provider takes effect only when assigned to an [AI Model](/ai-gateway/entities/ai-model/) or [AI Agent](/ai-gateway/entities/ai-agent/). Reference the provider by `name` or `id` in the entity's `access.identity_providers` array:

```yaml
access:
Expand All @@ -196,8 +207,9 @@ access:

{:.info}
> **Assignment rules**
> * Each AI Model supports one `key-auth` identity provider and one `openid-connect` identity provider.
> * You can assign both types to the same AI Model. A request is authenticated if it satisfies either provider.
> * Each AI Model supports one `key-auth` identity provider and one `openid-connect` identity provider. You can assign both types to the same AI Model; a request is authenticated if it satisfies either provider.
> * Each AI Agent currently supports up to one AI Identity Provider reference.
> * Attaching an authentication AI Policy directly to an AI Agent's `policies` field isn't supported. AI Identity Providers are the only supported way to authenticate AI Agent traffic.

If you plan to rename the AI Identity Provider later, reference it by `id` rather than name. The ID is stable across renames.

Expand Down Expand Up @@ -241,6 +253,7 @@ data:
- bearer
scopes:
- openid
cache_tokens_salt: okta-ai-se-cache-salt
{% endentity_example %}

## Schema
Expand Down
Loading
Loading