AgentCore Gateway to Agent

The connection generator can register an agent (either TypeScript or Python) as an AgentCore Runtime target of an AgentCore Gateway generated with protocol: http.

Once connected, the Gateway proxies requests for the agent under <gatewayUrl>/<targetName>/invocations, signing outbound traffic to the runtime with IAM SigV4. This gives your agents a single governed entry point — and since callers only need to reach the Gateway, the agent runtimes themselves can be deployed inside a VPC behind it.

Prerequisites

Before using this generator, ensure you have:

1. An agentcore-gateway project generated with protocol: http
2. An agent component (ts#agent or py#agent) created with infra: agentcore. Either auth: iam (the Gateway invokes it with its own role) or auth: cognito (the Gateway forwards the caller’s JWT — see Forwarding caller identity) works.

TypeScript HTTP agents

A TypeScript http agent serves tRPC over WebSocket, and AgentCore Gateway does not support WebSocket or bidirectional streaming — the generator rejects this combination. Generate the agent with the ag-ui protocol instead.

Usage

Run the Generator

VSCode

1. Install the Nx Console VSCode Plugin if you haven't already
2. Open the Nx Console in VSCode
3. Click Generate (UI) in the "Common Nx Commands" section
4. Search for @aws/nx-plugin - connection
5. Fill in the required parameters
6. Click Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:connection

yarn

yarn nx g @aws/nx-plugin:connection

npm

npx nx g @aws/nx-plugin:connection

bun

bunx nx g @aws/nx-plugin:connection

You can also perform a dry-run to see what files would be changed

pnpm

pnpm nx g @aws/nx-plugin:connection --dry-run

yarn

yarn nx g @aws/nx-plugin:connection --dry-run

npm

npx nx g @aws/nx-plugin:connection --dry-run

bun

bunx nx g @aws/nx-plugin:connection --dry-run

Select the Gateway project as the source and the agent project as the target. If the agent project contains multiple components, specify targetComponent to disambiguate.

Options

Parameter	Type	Default	Description
sourceProject Required	string	-	The source project
targetProject Required	string	-	The target project to connect to
sourceComponent	string	-	The source component to connect from (component name, path relative to source project root, or generator id). Use '.' to explicitly select the project as the source.
targetComponent	string	-	The target component to connect to (component name, path relative to target project root, or generator id). Use '.' to explicitly select the project as the target.
preferInstallDependencies	boolean	true	Whether to prefer installing dependencies after the generator runs. Set to false to defer installing when batching multiple generators (an install still runs if needed so subsequent generators can compute the Nx project graph); install once at the end.

Generator Output

The generator wires existing projects together rather than emitting new source files. The following files are modified:

• Directorypackages/<gateway>

  • project.json the Gateway’s dev target gains a dependency on the agent’s <agent>-dev
  • local-dev.ts ATTACHED_AGENTS updated so the local gateway proxies to the agent

Adding the agent target to your stack

The generator cannot automatically wire the agent target into your infrastructure because it doesn’t know which stack or module instantiates the Gateway. Add a single call to gateway.addAgent(agent) yourself.

CDK

In the stack where you instantiate the Gateway, register the agent as a target:

packages/infra/src/stacks/application-stack.ts

const myAgent = new MyAgent(this, 'MyAgent');
const myGateway = new MyGateway(this, 'MyGateway');

// Register the agent as a runtime target of the Gateway. The target name
// defaults to the agent's `agentName` (its class name in kebab-case,
// e.g. `MyAgent` -> `my-agent`), and forms the target's invocation path:
// <gatewayUrl>/my-agent/invocations
myGateway.addAgent(myAgent);

To override the default target name, pass gatewayTargetName:

myGateway.addAgent(myAgent, { gatewayTargetName: 'my-target' });

The construct grants the Gateway’s execution role invoke access to the agent runtime and configures the target with the GATEWAY_IAM_ROLE credential provider, so the Gateway signs outbound calls with its own role.

Deploying agents into a VPC

Fronting an agent with a Gateway is what makes a VPC-deployed agent reachable: callers talk to the Gateway’s public endpoint, and the Gateway reaches the runtime internally. Pass a VPC network configuration to the agent construct:

import { RuntimeNetworkConfiguration } from 'aws-cdk-lib/aws-bedrockagentcore';

const myAgent = new MyAgent(this, 'MyAgent', {
  // Give each agent its own scope for the network configuration — usingVpc
  // creates a security group named `SecurityGroup` under the scope you pass,
  // so passing `this` for more than one agent collides on the construct id.
  networkConfiguration: RuntimeNetworkConfiguration.usingVpc(
    new Construct(this, 'MyAgentNetwork'),
    {
      vpc,
      vpcSubnets: { subnetType: ec2.SubnetType.PRIVATE_WITH_EGRESS },
    },
  ),
});

Use a private subnet with egress, not a private isolated subnet: the runtime needs outbound internet access to reach Bedrock and read its configuration from AWS AppConfig.

AgentCore Runtime VPC deployments are only supported in certain availability zones. If a deploy fails with subnets are in unsupported availability zones, restrict the VPC (or the subnet selection) to the supported zones for your region.

Terraform

In the Terraform file where you instantiate the Gateway, wire the agent target in:

packages/infra/src/main.tf

module "my_agent" {
  source = "../../common/terraform/src/app/agents/my-agent"
  # ...
}

module "my_gateway" {
  source = "../../common/terraform/src/app/gateways/my-gateway"

  # The Gateway signs outbound calls to the runtime with its own role and
  # validates access at target creation, so it needs invoke access first.
  additional_iam_policy_statements = [
    {
      Effect = "Allow"
      Action = [
        "bedrock-agentcore:InvokeAgentRuntime",
        "bedrock-agentcore:InvokeAgentRuntimeWithWebSocketStream",
        # A2A targets additionally serve their agent card via the gateway
        "bedrock-agentcore:GetAgentCard",
      ]
      Resource = [
        module.my_agent.agent_core_runtime_arn,
        "${module.my_agent.agent_core_runtime_arn}/*",
      ]
    }
  ]
}

# Register the agent as a runtime target of the Gateway. The target name
# forms the invocation path: <gatewayUrl>/my-agent/invocations
resource "aws_bedrockagentcore_gateway_target" "my_agent" {
  gateway_identifier = module.my_gateway.gateway_id
  name               = "my-agent"
  # AgentCore fills in a description when none is set, which the provider
  # reports as an inconsistent result after apply — so always set one.
  description = "Agent runtime target my-agent"

  target_configuration {
    http {
      agentcore_runtime {
        arn = module.my_agent.agent_core_runtime_arn
      }
    }
  }

  credential_provider_configuration {
    gateway_iam_role {}
  }
}

Deploying agents into a VPC

Fronting an agent with a Gateway is what makes a VPC-deployed agent reachable: callers talk to the Gateway’s public endpoint, and the Gateway reaches the runtime internally. Set the agent module’s VPC variables:

module "my_agent" {
  source = "../../common/terraform/src/app/agents/my-agent"

  enable_vpc = true
  vpc_id     = aws_vpc.my_vpc.id
  subnet_ids = [aws_subnet.private_a.id, aws_subnet.private_b.id]
}

Use private subnets with egress (a route to a NAT gateway), not private isolated subnets: the runtime needs outbound internet access to reach Bedrock and read its configuration from AWS AppConfig.

Invoking the agent through the Gateway

Requests to <gatewayUrl origin>/<targetName>/invocations are forwarded to the agent runtime without protocol translation, so callers use the same request shape they’d use against the runtime directly — SSE streams (AG-UI), JSON streaming (Python HTTP) and A2A JSON-RPC all proxy through. Callers authenticate with the Gateway (IAM SigV4 or Cognito JWT depending on the Gateway’s auth) rather than with the agent.

To connect a website to the Gateway’s agents, use the connection generator.

Forwarding caller identity to the runtime

By default the Gateway signs outbound calls with its own IAM role (the GATEWAY_IAM_ROLE credential provider), so the runtime sees the Gateway’s identity, not the caller’s. If instead you want the agent to authorize on the caller — for example to read the user’s sub or scope claims — front a Cognito agent with a Cognito Gateway. The Gateway then forwards the caller’s JWT to the runtime unchanged (the JWT_PASSTHROUGH credential provider), and the runtime revalidates it.

Generate both ends with auth: cognito and connect them as above:

• an agent (ts#agent or py#agent) created with auth: cognito, and
• a Gateway created with auth: cognito fronting the same Cognito user pool.

Everything else is automatic — gateway.addAgent(agent) (CDK) and the generated Terraform runtime module handle the wiring for you based on the agent’s auth:

• the target is created with the JWT_PASSTHROUGH credential provider (rather than GATEWAY_IAM_ROLE), and
• the runtime allowlists the Authorization header so the forwarded token reaches your agent code. Without this allowlist AgentCore validates the token but strips the header before your container.

Callers invoke the Gateway with Authorization: Bearer <jwt> (no SigV4), and the agent reads the claims from the Authorization header — skipping signature validation, since the runtime’s inbound authorizer has already verified the token:

packages/py_project/.../my_agent/main.py

import jwt  # PyJWT

@app.post('/invocations')
async def invoke(input: InvokeInput, request: Request):
    token = request.headers['authorization'].removeprefix('Bearer ')
    claims = jwt.decode(token, options={'verify_signature': False})
    # authorize on claims['sub'], claims['scope'], ...

Note

JWT passthrough suits a single identity provider whose token audience already covers the runtime. If one Gateway fronts agents across multiple tenants or audiences, use OAuth on-behalf-of token exchange instead.

Local Development

Running the Gateway locally with:

pnpm

pnpm nx dev <gateway-name>

yarn

yarn nx dev <gateway-name>

npm

npx nx dev <gateway-name>

bun

bunx nx dev <gateway-name>

starts a local gateway plus every attached agent on its assigned local port. The local gateway proxies /<targetName>/... paths to each agent’s local server, matching the deployed Gateway’s path-based routing.