Python Agent to Gateway

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

The generator wires the agent so it authenticates to the Gateway with IAM SigV4 (via httpx request signing) 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 Python 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-gateway modules into your agent_connection Python project, plus a per-Gateway wrapper, and modifies your agent:

• Directorypackages/common/agent_connection

  • Directory<scope>_agent_connection

    • Directorycore/

      • agentcore_endpoints.py Framework-agnostic ARN/URL resolution
      • agentcore_gateway_mcp_transport.py Framework-agnostic Gateway MCP transport
      • agentcore_gateway_mcp_client_<framework>.py Gateway MCP client for your agent’s framework
      • Directoryauth/ Framework-agnostic SigV4 / session-forwarding httpx.Auth

        • …
    • Directoryapp/

      • <gateway_snake>_client_<framework>.py Per-Gateway client wrapper
    • __init__.py Re-exports the Gateway client

The client suffix matches your agent’s framework (_strands or _langchain).

Additionally, the generator:

• Modifies your agent’s agent.py to import the Gateway client and register its tools in tools
• Adds agent_connection as a workspace dependency of the agent
• Wires the agent’s <agent>-dev target to depend on the Gateway’s dev target

Using the connected Gateway

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

Strands

packages/example/example/my_agent/agent.py

from contextlib import contextmanager
from strands import Agent

from my_scope_agent_connection import MyGatewayClientStrands

@contextmanager
def get_agent():
    my_gateway = MyGatewayClientStrands.create()
    with (
        my_gateway,
    ):
        yield Agent(
            system_prompt="...",
            tools=[*my_gateway.list_tools_sync()],
        )

MyGatewayClientStrands.create() returns a single context-manageable MCPClient whose list_tools_sync() yields every tool available through the Gateway.

LangChain

packages/example/example/my_agent/agent.py

from langchain.agents import create_agent
from langchain_aws import ChatBedrockConverse

from my_scope_agent_connection import MyGatewayClientLangChain

def get_agent():
    my_gateway = MyGatewayClientLangChain.create()
    return create_agent(
        model=ChatBedrockConverse(model=MODEL_ID, region_name=REGION),
        system_prompt="...",
        tools=[*my_gateway],
    )

MyGatewayClientLangChain.create() returns a list of tools loaded via langchain-mcp-adapters. Each tool opens a fresh session per call, so no with block is needed.

In both cases the client behaves the same way per mode:

• Deployed mode (LOCAL_DEV unset): tools pointed at the Gateway’s MCP endpoint, SigV4-signed.
• Local mode (LOCAL_DEV=true): plain-HTTP tools pointed at the local gateway started by the Gateway project’s dev target.

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 exposed as <target-name>___<tool-name>, matching what the deployed Gateway emits. This keeps the agent’s system prompt and the Cedar action names you reference consistent across local and deployed runs.