TypeScript Agent to Gateway

The connection generator can connect your TypeScript Agent to an AgentCore Gateway.

The generator wires the agent so it authenticates to the Gateway with IAM SigV4 when deployed, and connects to the local gateway started by the Gateway project when running locally.

Prerequisites

Before using this generator, ensure you have:

1. A TypeScript project with a Agent component (infra: agentcore)
2. A agentcore-gateway project

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 agent project as the source and the Gateway project as the target.

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 emits shared core client files into your agent-connection package, plus a per-Gateway wrapper, and modifies your agent:

• Directorypackages/common/agent-connection

  • Directorysrc

    • Directorycore/

      • agentcore-endpoints.ts Framework-agnostic ARN/URL resolution
      • agentcore-gateway-mcp-transport.ts Framework-agnostic Gateway MCP transport
      • agentcore-gateway-mcp-client-strands.ts Strands MCP client for the deployed Gateway
    • Directoryapp/

      • <gateway-kebab>-client-strands.ts Per-Gateway Strands client wrapper
    • index.ts Re-exports the Gateway client

Additionally, the generator:

• Modifies your agent’s agent.ts to import the Gateway client class, call <Gateway>ClientStrands.create(), and register the returned client in the tools array
• Wires the agent’s <agent>-dev target to depend on the Gateway’s dev target
• Installs the required SigV4 / MCP dependencies

Using the connected Gateway

The generator transforms your agent’s agent.ts to use the Gateway client:

packages/example/src/my-agent/agent.ts

import { Agent } from '@strands-agents/sdk';
import { MyGatewayClientStrands } from ':my-scope/agent-connection';

export const getAgent = async () => {
  const myGateway = await MyGatewayClientStrands.create();
  return new Agent({
    systemPrompt: '...',
    tools: [myGateway],
  });
};

When deployed (LOCAL_DEV unset), the client points at the Gateway’s MCP endpoint and authenticates with SigV4. When LOCAL_DEV=true, it points at the local gateway started by the Gateway project’s dev target, so the same agent.ts works uniformly in both modes.

The session ID is propagated to downstream MCP servers automatically via the X-Amzn-Bedrock-AgentCore-Runtime-Session-Id header.

Infrastructure

After running the generator you must grant the agent permission to invoke the Gateway.

CDK

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

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

// Grant the agent permissions to invoke the Gateway
gateway.grantInvokeAccess(myAgent);

The Gateway URL is automatically registered in the agentcore.gateways.<ClassName> namespace of Runtime Configuration by the generated CDK construct, so the agent can discover it at runtime.

Terraform

packages/infra/src/main.tf

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

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

# Grant the agent permission to invoke the Gateway
resource "aws_iam_policy" "agent_invoke_gateway" {
  name = "AgentInvokeGatewayPolicy"
  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect   = "Allow"
      Action   = "bedrock-agentcore:InvokeGateway"
      Resource = module.my_gateway.gateway_arn
    }]
  })
}

resource "aws_iam_role_policy_attachment" "agent_invoke_gateway" {
  role       = module.my_agent.agent_core_runtime_role_arn
  policy_arn = aws_iam_policy.agent_invoke_gateway.arn
}

The Gateway URL is automatically registered in the agentcore.gateways.<ClassName> namespace of Runtime Configuration by the generated Terraform module, so the agent can discover it at runtime.

Local Development

The generator configures the agent’s dev target to:

1. Start the connected Gateway’s local gateway and every attached MCP server
2. Set LOCAL_DEV=true so the generated client points at the local gateway instead of the deployed Gateway

Run the agent locally with:

pnpm

pnpm nx <agent-name>-dev <project-name>

yarn

yarn nx <agent-name>-dev <project-name>

npm

npx nx <agent-name>-dev <project-name>

bun

bunx nx <agent-name>-dev <project-name>

To run the agent locally against the deployed Gateway instead (for example, to exercise Cedar policies), use the agent’s serve target. Without LOCAL_DEV set, the client resolves the deployed Gateway URL from runtime configuration and SigV4-signs requests with your local AWS credentials:

pnpm

pnpm nx <agent-name>-serve <project-name>

yarn

yarn nx <agent-name>-serve <project-name>

npm

npx nx <agent-name>-serve <project-name>

bun

bunx nx <agent-name>-serve <project-name>

Local fidelity

The local gateway stands in for the deployed Gateway, so:

• No Cedar policy evaluation. Every tool is visible to the agent regardless of policies. Use the serve target to exercise policies against the deployed Gateway.
• Tool-name prefixing is preserved. Each local MCP server’s tools are wrapped to expose names of the form <target-name>___<tool-name>, matching what the deployed Gateway emits. This keeps an agent’s system prompt and the Cedar action names you reference consistent across local and deployed runs.