Connect to AWS Bedrock AgentCore

Route requests to an Amazon Bedrock AgentCore agent runtime through agentgateway.

With agentgateway, you can route requests directly to an Amazon Bedrock AgentCore agent runtime by using an AgentgatewayBackend resource. You do not need a separate proxy, custom code, or the AWS SDK.

About AWS Bedrock AgentCore

Amazon Bedrock AgentCore is a runtime that hosts deployed agents, each with its own invocation endpoint. To reach an AgentCore runtime, you supply its Amazon Resource Name (ARN) to an AgentgatewayBackend of type aws. agentgateway uses the ARN to determine where to send each request. It connects over TLS to the bedrock-agentcore endpoint in the runtime’s AWS region, then rewrites the request path to target the specific runtime. You do not construct the endpoint or encode the ARN yourself.

Authentication

AgentCore runtimes support two authentication modes, which you choose when you deploy the runtime in AWS. The aws.agentCore backend supports both IAM (SigV4) and JWT authorization.

IAM (SigV4) is the default. agentgateway signs each request with AWS Signature Version 4 (SigV4) by using the standard AWS credential lookup from the proxy’s environment, such as IRSA on Amazon EKS. You do not store long-lived credentials in the gateway configuration, and IRSA credentials rotate automatically.

Amazon Cognito is an example tool to use for JWT authorization. The AgentCore runtime validates an OIDC bearer token on each request. To use this mode, attach a backend authentication policy that sends the token in the Authorization header. This overrides the default SigV4 signing. Unlike SigV4 credentials, a JWT expires, so you must refresh the token in the backing Kubernetes Secret before it expires.

This mode works only if the AgentCore runtime was deployed with Inbound Auth configured to accept JSON Web Tokens (a customJWTAuthorizer). The authorizer’s discoveryUrl and allowedClients list must match the token you send: the token’s issuer (iss) must match the discovery URL’s user pool, and the token’s client ID must be in allowedClients. If the runtime uses the default IAM authorization instead, it rejects bearer tokens with an authorization-method mismatch. You configure Inbound Auth when you deploy the runtime in AWS, not on the gateway. For more information, see the AgentCore Identity documentation.

Before you begin

Install and set up an agentgateway proxy.

Additionally, make sure that you have the following:

An Amazon Bedrock AgentCore agent runtime that is deployed in your AWS account. For steps to build and deploy a runtime, see the Amazon Bedrock AgentCore documentation. You also need the runtime’s ARN, in the format arn:aws:bedrock-agentcore:<region>:<account-id>:runtime/<runtime-id>.
Credentials for the runtime’s authentication mode.
For IAM (SigV4), AWS credentials that are available to the agentgateway proxy and that are allowed to invoke the runtime. The proxy uses the standard AWS credential chain, such as an IAM role, environment variables, or an instance profile. On Amazon EKS, the recommended approach is IAM Roles for Service Accounts (IRSA): associate an IAM role with the proxy’s Kubernetes service account.
For a JWT authorizer such as Amazon Cognito, the AgentCore runtime must be deployed with Inbound Auth configured to accept JSON Web Tokens, including the correct discovery URL and allowed client ID for the identity provider that issues your tokens. You also need a valid OIDC bearer token that the runtime’s authorizer accepts, such as an Amazon Cognito access token. AgentCore validates the token’s client_id claim, which is present in Cognito access tokens but not ID tokens, so use the access token.

Step 1: Create a backend for the AgentCore runtime

Create an AgentgatewayBackend resource that represents the AgentCore runtime. The aws.agentCore settings point agentgateway to the runtime that you want to invoke. The configuration depends on the runtime’s authentication mode.

Create the backend with only the aws.agentCore settings. Agentgateway signs each request with SigV4 by using the proxy’s environment credentials. You do not add an authentication policy.

kubectl apply -f- <<EOF
apiVersion: agentgateway.dev/v1alpha1
kind: AgentgatewayBackend
metadata:
  name: agentcore-backend
  namespace: agentgateway-system
spec:
  aws:
    agentCore:
      agentRuntimeArn: arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/my-agent-runtime
      # qualifier: production
EOF

Get a bearer token that the runtime’s authorizer accepts. The following example authenticates a user against an Amazon Cognito user pool and captures the resulting access token. The app client must have the USER_PASSWORD_AUTH flow enabled. For browser-based sign-in or machine-to-machine access, use the Cognito Hosted UI or an OAuth flow instead. Which command you run depends on whether the app client has a client secret.
Important
Capture the access token (AuthenticationResult.AccessToken), not the ID token. AgentCore validates the token’s client_id claim against the runtime’s allowedClients. Cognito puts the client ID in the client_id claim of access tokens, but in the aud claim of ID tokens, so an ID token fails with a client_id mismatch. The user pool that issues the token must also be the one in the runtime’s discovery URL, or the token fails with an iss mismatch.
- No client secret: Replace the app client ID, username, password, and region with your own values.
  export AGENTCORE_JWT=$(aws cognito-idp initiate-auth \ --auth-flow USER_PASSWORD_AUTH \ --client-id <app-client-id> \ --auth-parameters USERNAME=<username>,PASSWORD=<password> \ --region <region> \ --query 'AuthenticationResult.AccessToken' --output text)
- With client secret: If the app client has a secret, Cognito requires a SECRET_HASH parameter, which is a Base64-encoded HMAC-SHA256 of the username and client ID keyed by the client secret. Replace the placeholder values with your own. The USERNAME value must be identical in both the hash and the initiate-auth call. To find the client secret, run aws cognito-idp describe-user-pool-client --user-pool-id <user-pool-id> --client-id <app-client-id> --query 'UserPoolClient.ClientSecret' --output text. A client secret is set when the app client is created and cannot be removed afterward.
  CLIENT_ID=<app-client-id> CLIENT_SECRET=<client-secret> USERNAME=<username> SECRET_HASH=$(printf "%s" "${USERNAME}${CLIENT_ID}" \ | openssl dgst -sha256 -hmac "$CLIENT_SECRET" -binary \ | openssl base64) export AGENTCORE_JWT=$(aws cognito-idp initiate-auth \ --auth-flow USER_PASSWORD_AUTH \ --client-id "$CLIENT_ID" \ --auth-parameters USERNAME="$USERNAME",PASSWORD='<password>',SECRET_HASH="$SECRET_HASH" \ --region <region> \ --query 'AuthenticationResult.AccessToken' --output text)
Note
Cognito tokens expire (one hour by default). When the token expires, get a new one and update the Secret. You can use the refresh token from the initial response with the REFRESH_TOKEN_AUTH flow to avoid re-entering credentials.
Store the bearer token that the runtime’s authorizer accepts in a Kubernetes Secret. When you use the default Secret resolver, the token must be stored under the Authorization key.
```
kubectl create secret generic agentcore-jwt \
  --namespace agentgateway-system \
  --from-literal=Authorization="$AGENTCORE_JWT"
```

Create the backend and reference the Secret with a policies.auth.secretRef setting. Agentgateway sends the token in the Authorization header with a Bearer prefix, which overrides the default SigV4 signing. The endpoint, region, and invocation path are still derived from the ARN.

kubectl apply -f- <<EOF
apiVersion: agentgateway.dev/v1alpha1
kind: AgentgatewayBackend
metadata:
  name: agentcore-backend
  namespace: agentgateway-system
spec:
  aws:
    agentCore:
      agentRuntimeArn: arn:aws:bedrock-agentcore:us-west-2:111122223333:runtime/my-agent-runtime
      # qualifier: production
  policies:
    auth:
      secretRef:
        name: agentcore-jwt
EOF

Setting	Description
`aws.agentCore.agentRuntimeArn`	The ARN of the AgentCore agent runtime to invoke, in the format `arn:aws:bedrock-agentcore:<region>:<account-id>:runtime/<runtime-id>`. agentgateway derives the endpoint, region, and invocation path from this value.
`aws.agentCore.qualifier`	Optional. The runtime version or endpoint qualifier to invoke. If you omit this setting, the default endpoint is used.
`policies.auth`	Optional. Overrides the default authentication for the backend. Omit this setting to sign requests with SigV4 (IAM). To authenticate to a runtime that uses a JWT authorizer, set `policies.auth.secretRef` (or `policies.auth.key`) to a bearer token. By default, the token is sent in the `Authorization` header with a `Bearer` prefix. When you use `secretRef` with the default resolver, store the token under the Secret’s `Authorization` key.

Step 2: Route to the AgentCore backend

Create an HTTPRoute that routes incoming traffic to the AgentgatewayBackend. The following route matches the /agentcore path so that the runtime has a unique address on the gateway. You do not need to rewrite the path, because agentgateway replaces the entire request path with the runtime’s invocation endpoint before the request is sent upstream. As a result, any subpath that a client appends after /agentcore is not forwarded to the runtime.
Note
AgentCore identifies a runtime entirely by its ARN, not by a URL subpath, so a path such as /agentcore/my-agent does not select a different agent. The my-agent subpath is dropped, and the request still reaches the ARN in the backend. To route to more than one runtime, create a separate AgentgatewayBackend (each with its own agentRuntimeArn) and a separate route for each one. To target a different version or endpoint of the same runtime, set aws.agentCore.qualifier instead.
```
kubectl apply -f- <<EOF
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
  name: agentcore
  namespace: agentgateway-system
spec:
  parentRefs:
  - name: agentgateway-proxy
    namespace: agentgateway-system
  rules:
  - matches:
    - path:
        type: PathPrefix
        value: /agentcore
    backendRefs:
      - name: agentcore-backend
        group: agentgateway.dev
        kind: AgentgatewayBackend
EOF
```
Optional: Add a RequestHeaderModifier filter to the route rule to identify the calling user to the AgentCore runtime. AgentCore uses the X-Amzn-Bedrock-AgentCore-Runtime-User-Id header to associate requests with a user session.
```
    filters:
    - type: RequestHeaderModifier
      requestHeaderModifier:
        set:
        - name: X-Amzn-Bedrock-AgentCore-Runtime-User-Id
          value: user-123
```

Step 3: Verify the connection

Get the agentgateway address.

export INGRESS_GW_ADDRESS=$(kubectl get gateway agentgateway-proxy -n agentgateway-system -o=jsonpath="{.status.addresses[0].value}")
echo $INGRESS_GW_ADDRESS

Send a request to the AgentCore runtime through the gateway. The request body depends on the agent that you deployed to the runtime. The following example sends a simple prompt.
```
curl -X POST http://$INGRESS_GW_ADDRESS/agentcore \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Hello from agentgateway!"}'
```
Example output:
```
{"result": {"role": "assistant", "content": [{"text": "Hello! 👋 \n\nNice to meet you! I'm Claude, an AI assistant made by Anthropic. I'm here to help with a wide variety of tasks—whether that's answering questions, helping with writing, coding, analysis, creative projects, math, or just having a conversation.\n\nWhat can I help you with today?"}]}}
```
If the runtime is reachable and the request is authenticated, you get a response from your agent. A 403 error indicates an authentication problem:
- For IAM, verify that the proxy’s AWS credentials are allowed to invoke the runtime.
- For a JWT authorizer, verify that the token in the Secret is valid and not expired. Also make sure that the AgentCore runtime is set up with the Inbound Auth details that match the IdP, such as the discovery URL and client ID.

Cleanup

You can remove the resources that you created in this guide.

kubectl delete HTTPRoute agentcore -n agentgateway-system --ignore-not-found
kubectl delete AgentgatewayBackend agentcore-backend -n agentgateway-system --ignore-not-found
kubectl delete secret agentcore-jwt -n agentgateway-system --ignore-not-found

Connect to an agent

Was this page helpful?