AI Agents

When you want to centrally manage agent routing, control access, and gain observability over agent traffic, use the AI Agent entity to expose upstream agents through AI Gateway. AI Gateway:

• Acts as a central point of contact for A2A clients
• Rewrites agent-card URLs so clients route through the gateway (not directly to agents)
• Enforces access controls via Access Control Lists (ACLs)
• Emits structured telemetry tied to agent operations.

The AI Agent entity supports two types: a2a for AI Agents that speak the Agent-to-Agent protocol, and http for standard HTTP AI Agents. See the AI Agent types section for protocol-specific behavior and configuration guidance.

AI Agents can be created and managed through:

• Konnect UI
• AI Gateway API: /v1/ai-gateways/{aiGatewayId}/agents
• kongctl

For configuration examples and step-by-step setup instructions, see the following Set up an AI Agent section.

Choose an AI Agent type based on your upstream and observability needs. The type controls how requests are processed:

Common use cases for exposing agents through AI Gateway:

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). This starts an OpenTelemetry span, and records the request body for payload logging if that’s enabled.
2. Header filter. Detects streaming responses (Content-Type: text/event-stream) and records time to first byte. Buffers agent-card responses for URL rewriting.
3. 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.
4. Log. Finalizes the OpenTelemetry span with task state, task ID, and any error information.

Non-A2A traffic, and traffic to http Agents, is proxied without these steps.

Beyond the url field, AI Agents can define HTTP routing rules through config.route. This allows you to match requests by method, path, host, and other HTTP patterns. Use route when you need fine-grained control over which traffic reaches the AI Agent. If only a URL is needed, the url field is simpler.

 
sequenceDiagram
    autonumber
    participant Client as A2A Client
    participant Gateway as AI Gateway
(Agent)
    participant Agent as Upstream A2A Agent

    Client->>Gateway: A2A request (JSON-RPC or REST)
    Note over Gateway: Detect A2A binding and method
Start OTel span (if logging enabled)

    Gateway->>Agent: Proxied request
(Accept-Encoding removed if logging enabled)

    alt Streaming response (SSE)
        Agent-->>Gateway: text/event-stream chunks
        Note over Gateway: Pass through each chunk
Count SSE events, track TTFB
        Gateway-->>Client: SSE chunks (unchanged)
        Note over Gateway: On final chunk:
Extract task state, set analytics
    else Non-streaming response
        Agent->>Gateway: JSON response
        Note over Gateway: Buffer response
Extract task metadata
        Gateway->>Client: Response (unchanged)
    end

    Note over Gateway: Finish OTel span
Emit ai.a2a metrics to log plugins
  

A2A defines the communication elements between agents. The AI Gateway runtime surfaces data tied to these elements in log output and OpenTelemetry spans for a2a Agents.

Protocol detection

A2A traffic is auto-detected per request and non-A2A traffic passes through without overhead.

REST binding

Detection anchors to the end of the request path, so any prefix added by the route is ignored. For example, both /v1/message:send and /api/agents/v1/message:send match SendMessage:

The canonical method name is what appears in OpenTelemetry span attributes and log output.

JSON-RPC binding

Detected by the "jsonrpc" field in the request body, combined with a recognized A2A method name or an A2A-Version request header. Recognized methods include message/send, message/stream, tasks/get, tasks/list, tasks/cancel, tasks/resubscribe, the tasks/pushNotificationConfig/* family, and agent/getExtendedAgentCard.

A request carrying an A2A-Version header is treated as JSON-RPC even if the method isn’t in the recognized list. When an unknown method is accepted this way, the method field in log output is recorded as "unknown" to bound metric cardinality. The OpenTelemetry span’s kong.a2a.operation attribute still receives the actual method name.

Agent-card URL rewriting

When an upstream agent returns an agent card, the runtime rewrites the url field, and any additionalInterfaces[].url fields, to the AI Gateway address. A2A clients then discover the gateway as the canonical endpoint instead of contacting the upstream directly. The rewrite uses X-Forwarded-* headers to construct the correct scheme, host, and port when the gateway is deployed behind a load balancer or reverse proxy.

For a2a type AI Agents, AI Gateway automatically emits structured A2A telemetry to track agent performance, debug issues, and monitor A2A traffic patterns. This telemetry flows to Konnect 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 Konnect analytics and logging AI Policies) and creates a kong.a2a child span when you’ve configured Kong Gateway tracing. For the canonical metric and attribute list, see A2A metrics.

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.

Payload logging may expose sensitive data. Only enable it when you’re prepared to handle request and response bodies in your logging pipeline.

You can view A2A analytics in Konnect Explorer and Dashboards through the Agentic usage analytics view.

Log output fields

When config.logging.log_statistics is enabled, it writes the following fields to the ai.a2a.rpc[] array:

OpenTelemetry span attributes

For a2a type Agents, when Kong Gateway tracing is configured, the runtime creates a kong.a2a child span with the following attributes:

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 currently accepts up to one AI Auth Strategy reference. ACLs are evaluated only after the AI Consumer’s identity is resolved through this authentication step.

Access control and AI Auth Strategies govern who can reach the AI Agent. Separately, config.upstream.auth controls how AI Gateway authenticates itself to the upstream agent. By default, AI Gateway proxies requests without adding credentials.

Some upstream agents don’t accept bearer tokens or API keys at all, and only accept requests signed with AWS IAM (SigV4), such as an agent hosted on Amazon Bedrock AgentCore Runtime or fronted by an IAM-protected Amazon API Gateway. For these, set config.upstream.auth.type to aws.

AI Gateway signs each proxied request using the credentials you provide:

• Static IAM user credentials, access_key_id and secret_access_key, optionally paired with a session_token for temporary credentials. Environment auto-detection when you omit access_key_id and secret_access_key, for example, an EC2 instance profile or environment variables.
• Role assumption through assume_role_arn and role_session_name, layered on top of either credential source. Recommended for production use and cross-account access.

Set region to override the region. Otherwise, AI Gateway infers from the environment, and sts_endpoint_url to use a custom AWS STS endpoint when assuming a role.

secret_access_key and session_token are write-only and referenceable fields. Store them in a vault instead of in plaintext.

config:
  url: https://agent.execute-api.us-east-1.amazonaws.com/prod
  upstream:
    auth:
      type: aws
      region: us-east-1
      assume_role_arn: arn:aws:iam::123456789012:role/agent-access
      role_session_name: kong-ai-gateway

config.upstream is available regardless of the AI Agent’s type; it applies to a2a and http Agents alike.

To enforce security, transformation, or governance controls on agent traffic (for example, request validation, PII detection, request logging), attach AI Policies to the agent. Add policy names or IDs to the AI Agent’s policies field. Multiple AI Policies can attach to one AI Agent; each runs independently in the request lifecycle.

For available policy types and configuration, see the AI Policy entity reference.

Before creating an AI Agent with access restrictions, create an AI Consumer Group to reference in access.acls. This example references a group named internal-teams. See 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 access restricted to the internal-teams Consumer Group.

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. 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 AI Gateway.

curl -X POST https://{region}.api.konghq.com/v1/ai-gateways/{AIGatewayId}/agents \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $KONNECT_TOKEN" \
    --data '
    {
      "display_name": "KongAir Flight Booking Agent",
      "name": "kongair-flight-booking-agent",
      "type": "a2a",
      "access": {
        "acls": {
          "allow": [
            "internal-teams"
          ]
        }
      },
      "policies": [],
      "config": {
        "url": "https://booking-agent.internal.kongair.com",
        "route": {
          "paths": [
            "/kongair-flight-booking"
          ]
        },
        "logging": {
          "payloads": false,
          "max_payload_size": 1048576
        }
      }
    }
    '

ai_gateway_agents:
  - ref: kongair-flight-booking-agent
    ai_gateway: !lookup {id: !env AI_GATEWAY_ID}
    display_name: KongAir Flight Booking Agent
    name: kongair-flight-booking-agent
    type: a2a
    access:
      acls:
        allow:
        - internal-teams
    policies: []
    config:
      url: https://booking-agent.internal.kongair.com
      route:
        paths:
        - "/kongair-flight-booking"
      logging:
        payloads: false
        max_payload_size: 1048576