---
title: "Create an AI Gateway Agent"
method: POST
path: "/v1/ai-gateways/{gatewayId}/agents"
tags: ["AI Gateway Agents"]
---

# Create an AI Gateway Agent

`POST /v1/ai-gateways/{gatewayId}/agents`

**Pre-release Endpoint**
This endpoint is currently in beta and is subject to change.

Creates a new agent for the AI Gateway.

## Request body

- CreateAIGatewayAgentRequest — **Pre-release Feature** This feature is currently in beta and is subject to change.
  - `display_name` string, required — The display name for this agent.
  - `name` string, required — Identifier for an AI Gateway entity. In some cases, this may be the entity name or ID.
  - `enabled` boolean — Whether the Agent is enabled.
  - `type` 'a2a' | 'http', required — The type of the agent.
  - `policies` string[] — List of policy references.
  - `access` AIGatewayAgentAccess — **Pre-release Feature** This feature is currently in beta and is subject to change. Access control configuration for an agent.
    - `acls` union — **Pre-release Feature** This feature is currently in beta and is subject to change. Access control rules. Configure exactly one of `allow` or `deny`.
      - AIGatewayAllowACL — **Pre-release Feature** This feature is currently in beta and is subject to change.
        - `allow` string[], required — List of Consumer Groups Names, or Authenticated Groups Names that are permitted access.
      - AIGatewayDenyACL — **Pre-release Feature** This feature is currently in beta and is subject to change.
        - `deny` string[], required — List of Consumer Groups Names, or Authenticated Groups Names that are denied access.
    - `identity_providers` AIGatewayIdentityProviderReference[] — List of identity providers for granting access to the agent. At most 1 identity provider of each identity provider type can be referenced.
  - `config` object, required — Configuration for the agent. The structure varies depending on the agent type.
    - `url` string, uri, required — Helper field to set protocol, host, port and path of the upstream A2A Agent using a URL. This is the same as a Kong Gateway Service URL: ${scheme}://${host}:${port}/${path}
    - `route` AIGatewayRouteConfig — **Pre-release Feature** This feature is currently in beta and is subject to change. Configuration for an AI Gateway route.
      - `headers` object — One or more lists of values indexed by header name that will cause this route to match if present in the request. The `Host` header cannot be used with this attribute: hosts should be specified using the `hosts` attribute. When `headers` contains only one value and that value starts with the special prefix `~*`, the value is interpreted as a regular expression.
      - `hosts` string[] — A list of domain names that match this route. Note that the hosts value is case sensitive.
      - `https_redirect_status_code` integer — The status code Kong responds with when all properties of a route match except the protocol i.e. if the protocol of the request is `HTTP` instead of `HTTPS`. `Location` header is injected by Kong if the field is set to 301, 302, 307 or 308. Note: This config applies only if the route is configured to only accept the `https` protocol.
      - `methods` string[] — A list of HTTP methods that match this route.
      - `paths` string[] — A list of paths that match this route.
      - `preserve_host` boolean — When matching a route via one of the `hosts` domain names, use the request `Host` header in the upstream request headers. If set to `false`, the upstream `Host` header will be that of the service's `host`.
      - `protocols` string[] — An array of the protocols this route should allow. See the [route Object](#route-object) section for a list of accepted protocols. When set to only `https`, HTTP requests are answered with an upgrade error. When set to only `http`, HTTPS requests are answered with an error.
      - `regex_priority` integer — A number used to choose which route resolves a given request when several routes match it using regexes simultaneously. When two routes match the path and have the same `regex_priority`, the older one (lowest `created_at`) is used. Note that the priority for non-regex routes is different (longer non-regex routes are matched before shorter ones).
      - `request_buffering` boolean — Whether to enable request body buffering or not. With HTTP 1.1, it may make sense to turn this off on services that receive data with chunked transfer encoding.
      - `response_buffering` boolean — Whether to enable response body buffering or not. With HTTP 1.1, it may make sense to turn this off on services that send data with chunked transfer encoding.
      - `strip_path` boolean — When matching a route via one of the `paths`, strip the matching prefix from the upstream request URL.
      - `tags` string[] — An optional set of strings associated with the route for grouping and filtering.
    - `max_request_body_size` integer — Maximum size of request body to parse. Set to 0 for unlimited.
    - `logging` object — **Pre-release Feature** This feature is currently in beta and is subject to change. Configuration for AI Gateway logging.
      - `payloads` boolean
      - `max_payload_size` integer — Maximum size in bytes for logged request/response payloads. Payloads exceeding this size will be truncated.
  - `labels` PublicLabels — Public labels store information about an entity that can be used for filtering a list of objects. Public labels are intended to store **PUBLIC** metadata. Keys must be of length 1-63 characters, and cannot start with "kong", "konnect", "mesh", "kic", or "_".
  - `managed_by` ManagedBy — Stores information about what manages this entity, such as the tool or system responsible for its lifecycle (for example, `terraform`). Keys must be 1–63 characters long and start with an alphanumeric character.

## Response `201`

AI Agent created successfully.

- AIGatewayAgent — **Pre-release Feature** This feature is currently in beta and is subject to change.
  - `display_name` string, required — The display name for this agent.
  - `name` string, required — Identifier for an AI Gateway entity. In some cases, this may be the entity name or ID.
  - `enabled` boolean — Whether the Agent is enabled.
  - `type` 'a2a' | 'http', required — The type of the agent.
  - `policies` string[] — List of policy references.
  - `access` AIGatewayAgentAccess — **Pre-release Feature** This feature is currently in beta and is subject to change. Access control configuration for an agent.
    - `acls` union — **Pre-release Feature** This feature is currently in beta and is subject to change. Access control rules. Configure exactly one of `allow` or `deny`.
      - AIGatewayAllowACL — **Pre-release Feature** This feature is currently in beta and is subject to change.
        - `allow` string[], required — List of Consumer Groups Names, or Authenticated Groups Names that are permitted access.
      - AIGatewayDenyACL — **Pre-release Feature** This feature is currently in beta and is subject to change.
        - `deny` string[], required — List of Consumer Groups Names, or Authenticated Groups Names that are denied access.
    - `identity_providers` AIGatewayIdentityProviderReference[] — List of identity providers for granting access to the agent. At most 1 identity provider of each identity provider type can be referenced.
  - `config` object, required — Configuration for the agent. The structure varies depending on the agent type.
    - `url` string, uri, required — Helper field to set protocol, host, port and path of the upstream A2A Agent using a URL. This is the same as a Kong Gateway Service URL: ${scheme}://${host}:${port}/${path}
    - `route` AIGatewayRouteConfig — **Pre-release Feature** This feature is currently in beta and is subject to change. Configuration for an AI Gateway route.
      - `headers` object — One or more lists of values indexed by header name that will cause this route to match if present in the request. The `Host` header cannot be used with this attribute: hosts should be specified using the `hosts` attribute. When `headers` contains only one value and that value starts with the special prefix `~*`, the value is interpreted as a regular expression.
      - `hosts` string[] — A list of domain names that match this route. Note that the hosts value is case sensitive.
      - `https_redirect_status_code` integer — The status code Kong responds with when all properties of a route match except the protocol i.e. if the protocol of the request is `HTTP` instead of `HTTPS`. `Location` header is injected by Kong if the field is set to 301, 302, 307 or 308. Note: This config applies only if the route is configured to only accept the `https` protocol.
      - `methods` string[] — A list of HTTP methods that match this route.
      - `paths` string[] — A list of paths that match this route.
      - `preserve_host` boolean — When matching a route via one of the `hosts` domain names, use the request `Host` header in the upstream request headers. If set to `false`, the upstream `Host` header will be that of the service's `host`.
      - `protocols` string[] — An array of the protocols this route should allow. See the [route Object](#route-object) section for a list of accepted protocols. When set to only `https`, HTTP requests are answered with an upgrade error. When set to only `http`, HTTPS requests are answered with an error.
      - `regex_priority` integer — A number used to choose which route resolves a given request when several routes match it using regexes simultaneously. When two routes match the path and have the same `regex_priority`, the older one (lowest `created_at`) is used. Note that the priority for non-regex routes is different (longer non-regex routes are matched before shorter ones).
      - `request_buffering` boolean — Whether to enable request body buffering or not. With HTTP 1.1, it may make sense to turn this off on services that receive data with chunked transfer encoding.
      - `response_buffering` boolean — Whether to enable response body buffering or not. With HTTP 1.1, it may make sense to turn this off on services that send data with chunked transfer encoding.
      - `strip_path` boolean — When matching a route via one of the `paths`, strip the matching prefix from the upstream request URL.
      - `tags` string[] — An optional set of strings associated with the route for grouping and filtering.
    - `max_request_body_size` integer — Maximum size of request body to parse. Set to 0 for unlimited.
    - `logging` object — **Pre-release Feature** This feature is currently in beta and is subject to change. Configuration for AI Gateway logging.
      - `payloads` boolean
      - `max_payload_size` integer — Maximum size in bytes for logged request/response payloads. Payloads exceeding this size will be truncated.
  - `labels` PublicLabels — Public labels store information about an entity that can be used for filtering a list of objects. Public labels are intended to store **PUBLIC** metadata. Keys must be of length 1-63 characters, and cannot start with "kong", "konnect", "mesh", "kic", or "_".
  - `managed_by` ManagedBy — Stores information about what manages this entity, such as the tool or system responsible for its lifecycle (for example, `terraform`). Keys must be 1–63 characters long and start with an alphanumeric character.
  - `id` string, uuid, required — Contains a unique identifier used for this resource.
  - `created_at` string, date-time, required — An ISO-8601 timestamp representation of entity creation date.
  - `updated_at` string, date-time, required — An ISO-8601 timestamp representation of entity update date.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `409` — Conflict
- `429` — Too Many Requests

---

[API](https://skmtc.net/kong/apis/konnect-api-go-sdk.md) · [All operations](https://skmtc.net/kong/apis/konnect-api-go-sdk/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/kong/konnect-api-go-sdk/versions/f920f418f552/schema)