AWS Lambda Policy

The AWS Lambda AI Policy invokes an AWS Lambda function from AI Gateway. Instead of forwarding a request to an upstream, the policy sends the request to your Lambda function and returns the function’s response to the client. Use it to expose an existing Lambda function through a AI Gateway endpoint, so clients call one address and the function stays behind the gateway.

When a request reaches an entity that has the policy attached, the policy calls the Lambda Invoke API for the function in config.function_name. The policy accepts a function name or an ARN, including a partial ARN. Use config.qualifier to invoke a specific function version or alias.

The policy returns the function’s response to the client. The entity that the policy is attached to sends no request to its upstream.

The following example invokes a Lambda function and waits for the response:

curl -X POST https://{region}.api.konghq.com/v1/ai-gateways/{AIGatewayId}/policies \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $KONNECT_TOKEN" \
    --data '
    {
      "name": "aws-lambda-invoke",
      "display_name": "Invoke AWS Lambda Function",
      "type": "aws-lambda",
      "config": {
        "aws_key": "'$AWS_KEY'",
        "aws_secret": "'$AWS_SECRET'",
        "aws_region": "'$AWS_REGION'",
        "function_name": "'$LAMBDA_FUNCTION'",
        "invocation_type": "RequestResponse"
      }
    }
    '

Choose what the function receives

By default, the policy sends the function a flat JSON object that merges the query string arguments and the parsed request body arguments.

When you set any of the forward_request_* parameters to true, the policy sends a structured JSON object that contains only the fields you enable:

The following example sends the function the request method, the request URI, and the request body:

curl -X POST https://{region}.api.konghq.com/v1/ai-gateways/{AIGatewayId}/policies \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $KONNECT_TOKEN" \
    --data '
    {
      "name": "aws-lambda-structured-payload",
      "display_name": "Invoke AWS Lambda Function with a structured payload",
      "type": "aws-lambda",
      "config": {
        "aws_key": "'$AWS_KEY'",
        "aws_secret": "'$AWS_SECRET'",
        "aws_region": "'$AWS_REGION'",
        "function_name": "'$LAMBDA_FUNCTION'",
        "forward_request_method": true,
        "forward_request_uri": true,
        "forward_request_body": true
      }
    }
    '

ai_gateway_policies:
  - ref: aws-lambda-structured-payload
    ai_gateway: !lookup {id: !env AI_GATEWAY_ID}
    name: aws-lambda-structured-payload
    display_name: Invoke AWS Lambda Function with a structured payload
    type: aws-lambda
    config:
      aws_key: !env AWS_KEY
      aws_secret: !env AWS_SECRET
      aws_region: !env AWS_REGION
      function_name: !env LAMBDA_FUNCTION
      forward_request_method: true
      forward_request_uri: true
      forward_request_body: true

With this configuration, the policy is attached to an AI Model that has the route path /support and the model name support-model. A POST request to /support/chat/completions?status=open with the following body reaches the function as the payload that follows:

{
  "model": "support-model",
  "messages": [
    {
      "role": "user",
      "content": "order 42"
    }
  ]
}

{
  "request_method": "POST",
  "request_uri": "/support/chat/completions?status=open",
  "request_uri_args": {
    "status": "open"
  },
  "request_body": "{\"messages\":[{\"content\":\"order 42\",\"role\":\"user\"}],\"stream\":false,\"model\":\"<provider-model-name>\"}",
  "request_body_args": {
    "stream": false,
    "messages": [
      {
        "content": "order 42",
        "role": "user"
      }
    ],
    "model": "<provider-model-name>"
  }
}

The model field holds the provider model name from the AI Model target, not support-model, because AI Gateway rewrites the body before the policy runs. AI Gateway also adds stream. The payload has no request_headers field, because config.forward_request_headers isn’t enabled.

Set config.awsgateway_compatible to true to send an Amazon API Gateway payload instead. This setting takes precedence over the forward_request_* parameters, and config.awsgateway_compatible_payload_version selects version 1.0 or 2.0.

Set config.is_proxy_integration to true when your function returns a Lambda proxy integration response. The policy reads statusCode, headers, and body from the function’s JSON response and returns them to the client. When the response isn’t valid JSON, clients receive a 502 response.

Choose an invocation type

Set config.invocation_type to RequestResponse when the client needs the function’s result. Set it to Event to run the function asynchronously and return without its result. Set it to DryRun to validate the call and the caller’s permissions without running the function.

The AWS Lambda Policy fetches the AWS credentials in the following order:

1. The credentials in the config.aws_key and config.aws_secret parameters.
2. The AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY environment variables on the data plane.
3. The profile and credential file defined by AWS_PROFILE and AWS_SHARED_CREDENTIALS_FILE.
4. The ECS container credential provider.
5. The EKS IAM roles for the service account.
6. The EC2 instance metadata service (IMDS). The policy supports v1 and v2, and config.aws_imds_protocol_version selects the version.

The policy doesn’t support the IAM Identity Center credential provider or the Process credential provider.

If you also set config.aws_assume_role_arn, the policy performs an additional AssumeRole action. The data plane makes an HTTPS request to the AWS STS API with the configured or fetched credentials. The policy then invokes the Lambda function with the temporary credentials of the assumed role.

Store config.aws_key, config.aws_secret, and config.aws_assume_role_arn as secret references to an AI Vault. If you set a literal value instead, Konnect returns it as plain text in API responses.

If you don’t set config.aws_region, the policy reads the region from the AWS_REGION environment variable, and then from AWS_DEFAULT_REGION. If neither variable is set, the policy fails with the error no region or host specified.

The AWS Lambda Policy attaches to an AI Model, AI Agent, or AI MCP Server, because AI Gateway has no Gateway Services or Routes. The entity provides the route that clients call, and the policy answers the request. For details about how scopes work, see AI Policy scopes.

• The upstream receives no traffic: The policy answers the request itself. An AI Model still requires an AI Model Provider target, and clients must still send the model field that the AI Model route matches on. AI Gateway doesn’t send the request to the provider.
• AI Gateway changes the request body first: Before the policy runs, AI Gateway processes the request for the AI Model. For example, the model field in the body becomes the provider model name configured on the target, so the function receives that value instead of the AI Model name.
• Scope: Attach the policy to an AI Model, AI Agent, or AI MCP Server. The policy doesn’t support AI Consumer Group scope.
• Errors: When the Lambda Invoke API rejects a call, for example because the function doesn’t exist or the credentials are invalid, clients receive a 500 response with the message An unexpected error occurred. The cause appears in the data plane log.

Don’t apply the AWS Lambda Policy globally. A global policy answers every request on the data plane, so no other AI Model, AI Agent, or AI MCP Server receives traffic.