Python Agent a Gateway

El generador connection puede conectar tu Python Agent a un AgentCore Gateway.

El generador configura el agente para que se autentique en el Gateway con IAM SigV4 (mediante la firma de solicitudes httpx) cuando se despliega, y se conecte al gateway local iniciado por el proyecto Gateway cuando se ejecuta localmente.

Requisitos previos

Antes de usar este generador, asegúrate de tener:

1. Un proyecto Python con un componente Agent (infra: agentcore)
2. Un proyecto agentcore-gateway con protocol: mcp y auth: iam

El Gateway debe servir el protocolo mcp — el agente lo alcanza como un cliente MCP, por lo que sus targets se exponen como herramientas. El Gateway también debe usar autenticación IAM: el agente firma sus solicitudes con SigV4 usando su propio rol de ejecución. El generador rechaza gateways autenticados con Cognito.

Una dirección por Gateway

Un solo Gateway no puede ser llamado por un agente y frontar uno al mismo tiempo. Frontar runtimes de agente necesita protocol: http (ver Gateway a Agent), mientras que ser llamado por un agente necesita protocol: mcp. Usa un Gateway separado para cada dirección.

Uso

Ejecutar el generador

Ejecute este generador@aws/nx-plugin:connection

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

VSCode

1. Instale el Nx Console VSCode Plugin si aún no lo ha hecho
2. Abra la consola Nx en VSCode
3. Haga clic en Generate (UI) en la sección "Common Nx Commands"
4. Busque @aws/nx-plugin - connection
5. Complete los parámetros requeridos
6. Haga clic en Generate

Construya su comando5

sourceProjectRequerido

targetProjectRequerido

sourceComponent

targetComponent

preferInstallDependencies

true

--dry-runTambién puede realizar una ejecución en seco para ver qué archivos se cambiarían

Selecciona el proyecto del agente como origen y el proyecto Gateway como destino.

Opciones

Opciones del generador5 opciones

sourceProjectRequeridostring

El proyecto de origen

targetProjectRequeridostring

El proyecto de destino al que conectar

sourceComponentstring

El componente de origen desde el cual conectar (nombre del componente, ruta relativa a la raíz del proyecto de origen, o id del generador). Usa '.' para seleccionar explícitamente el proyecto como origen.

targetComponentstring

El componente de destino al cual conectar (nombre del componente, ruta relativa a la raíz del proyecto de destino, o id del generador). Usa '.' para seleccionar explícitamente el proyecto como destino.

preferInstallDependenciesbooleanPredeterminado: true

Si se prefiere instalar las dependencias después de que se ejecute el generador. Establecer en false para diferir la instalación al ejecutar múltiples generadores en lote (la instalación aún se ejecuta si es necesario para que los generadores subsiguientes puedan calcular el grafo de proyectos de Nx); instalar una vez al final.

Salida del generador

El generador emite módulos compartidos de core-gateway en tu proyecto Python agent_connection, además de un wrapper por Gateway, y modifica tu agente:

• Directoriopackages/common/agent_connection

  • Directorio<scope>_agent_connection

    • Directoriocore/

      • __init__.py Inicialización del paquete Python
      • agentcore_endpoints.py Resolución de ARN/URL independiente del framework
      • agentcore_transport.py Plomería de transporte AgentCore compartida
      • agentcore_gateway_mcp_transport.py Transporte MCP de Gateway independiente del framework
      • agentcore_gateway_mcp_client_<framework>.py Cliente MCP de Gateway para el framework de tu agente
      • Directorioauth/ httpx.Auth de SigV4 / reenvío de sesión independiente del framework

        • …
    • Directorioapp/

      • __init__.py Inicialización del paquete Python
      • <gateway_snake>_client_<framework>.py Wrapper de cliente por Gateway
    • __init__.py Re-exporta el cliente Gateway

El sufijo del cliente coincide con el framework de tu agente (_strands o _langchain).

Además, el generador:

• Modifica el agent.py de tu agente para importar el cliente Gateway y registrar sus herramientas en tools
• Agrega agent_connection como dependencia de workspace del agente
• Conecta el target <agent>-dev del agente para que dependa del target dev del Gateway

Usar el Gateway conectado

El generador transforma el agent.py de tu agente para usar el cliente Gateway:

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() devuelve un único MCPClient gestionable por contexto cuyo list_tools_sync() produce cada herramienta disponible a través del 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() devuelve una lista de herramientas cargadas mediante langchain-mcp-adapters. Cada herramienta abre una sesión nueva por llamada, por lo que no se necesita un bloque with.

En ambos casos, el cliente se comporta de la misma manera según el modo:

• Modo desplegado (LOCAL_DEV no establecido): herramientas apuntando al endpoint MCP del Gateway, firmadas con SigV4.
• Modo local (LOCAL_DEV=true): herramientas HTTP simples apuntando al gateway local iniciado por el target dev del proyecto Gateway.

El ID de sesión se propaga automáticamente a los servidores MCP descendentes mediante el encabezado X-Amzn-Bedrock-AgentCore-Runtime-Session-Id.

Infraestructura

Después de ejecutar el generador, debes otorgar al agente permiso para invocar el 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);

La URL del Gateway se registra automáticamente en el namespace agentcore.gateways.<ClassName> de Runtime Configuration por el constructo CDK generado, para que el agente pueda descubrirla en tiempo de ejecución.

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
  additional_iam_policy_statements = [{
    Effect   = "Allow"
    Action   = ["bedrock-agentcore:InvokeGateway"]
    Resource = [module.my_gateway.gateway_arn]
  }]
}

La URL del Gateway se registra automáticamente en el namespace agentcore.gateways.<ClassName> de Runtime Configuration por el módulo Terraform generado, para que el agente pueda descubrirla en tiempo de ejecución.

Desarrollo local

El generador configura el target dev del agente para:

1. Iniciar el gateway local del Gateway conectado y cada servidor MCP adjunto
2. Establecer LOCAL_DEV=true para que el cliente generado apunte al gateway local en lugar del Gateway desplegado

Ejecuta el agente localmente con:

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>

Para ejecutar el agente localmente contra el Gateway desplegado en su lugar (por ejemplo, para ejercitar políticas Cedar), usa el target serve del agente. Sin LOCAL_DEV establecido, el cliente resuelve la URL del Gateway desplegado desde la configuración de tiempo de ejecución y firma las solicitudes con SigV4 usando tus credenciales locales de AWS:

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>

Fidelidad local

El gateway local sustituye al Gateway desplegado, por lo que:

• Sin evaluación de políticas Cedar. Cada herramienta es visible para el agente independientemente de las políticas. Usa el target serve para ejercitar políticas contra el Gateway desplegado.
• Se preserva el prefijo de nombres de herramientas. Las herramientas de cada servidor MCP local se exponen como <target-name>___<tool-name>, coincidiendo con lo que emite el Gateway desplegado. Esto mantiene el prompt del sistema del agente y los nombres de acción Cedar que referencias consistentes entre ejecuciones locales y desplegadas.