Agent Python vers Gateway

Le générateur connection peut connecter votre Agent Python à une Gateway AgentCore.

Le générateur configure l’agent pour qu’il s’authentifie auprès de la Gateway avec IAM SigV4 (via la signature de requêtes httpx) lors du déploiement, et se connecte à la gateway locale démarrée par le projet Gateway lors de l’exécution locale.

Prérequis

Avant d’utiliser ce générateur, assurez-vous d’avoir :

1. Un projet Python avec un composant Agent (infra: agentcore)
2. Un projet agentcore-gateway

Utilisation

Exécuter le générateur

VSCode

1. Installez le Nx Console VSCode Plugin si ce n'est pas déjà fait
2. Ouvrez la console Nx dans VSCode
3. Cliquez sur Generate (UI) dans la section "Common Nx Commands"
4. Recherchez @aws/nx-plugin - connection
5. Remplissez les paramètres requis
6. Cliquez sur 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

Vous pouvez également effectuer une simulation pour voir quels fichiers seraient modifiés

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

Sélectionnez le projet agent comme source et le projet Gateway comme cible.

Options

Paramètre	Type	Par défaut	Description
sourceProject Requis	string	-	Le projet source
targetProject Requis	string	-	Le projet cible auquel se connecter
sourceComponent	string	-	Le composant source depuis lequel se connecter (nom du composant, chemin relatif à la racine du projet source, ou identifiant du générateur). Utilisez '.' pour sélectionner explicitement le projet comme source.
targetComponent	string	-	Le composant cible auquel se connecter (nom du composant, chemin relatif à la racine du projet cible, ou identifiant du générateur). Utilisez '.' pour sélectionner explicitement le projet comme cible.
preferInstallDependencies	boolean	true	Indique s'il faut privilégier l'installation des dépendances après l'exécution du générateur. Définir à false pour différer l'installation lors de l'exécution de plusieurs générateurs en lot (une installation s'exécute quand même si nécessaire pour que les générateurs suivants puissent calculer le graphe de projet Nx) ; installer une seule fois à la fin.

Sortie du générateur

Le générateur émet des modules core-gateway partagés dans votre projet Python agent_connection, plus un wrapper par Gateway, et modifie votre agent :

• Répertoirepackages/common/agent_connection

  • Répertoire<scope>_agent_connection

    • Répertoirecore/

      • agentcore_endpoints.py Résolution ARN/URL indépendante du framework
      • agentcore_gateway_mcp_transport.py Transport MCP Gateway indépendant du framework
      • agentcore_gateway_mcp_client_<framework>.py Client MCP Gateway pour le framework de votre agent
      • Répertoireauth/ httpx.Auth SigV4 / transfert de session indépendant du framework

        • …
    • Répertoireapp/

      • <gateway_snake>_client_<framework>.py Wrapper client par Gateway
    • __init__.py Ré-exporte le client Gateway

Le suffixe du client correspond au framework de votre agent (_strands ou _langchain).

De plus, le générateur :

• Modifie le fichier agent.py de votre agent pour importer le client Gateway et enregistrer ses outils dans tools
• Ajoute agent_connection comme dépendance de workspace de l’agent
• Configure la cible <agent>-dev de l’agent pour dépendre de la cible dev de la Gateway

Utiliser la Gateway connectée

Le générateur transforme le fichier agent.py de votre agent pour utiliser le client 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() retourne un MCPClient unique gérable par contexte dont list_tools_sync() fournit tous les outils disponibles via la 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() retourne une liste d’outils chargés via langchain-mcp-adapters. Chaque outil ouvre une nouvelle session par appel, donc aucun bloc with n’est nécessaire.

Dans les deux cas, le client se comporte de la même manière selon le mode :

• Mode déployé (SERVE_LOCAL non défini) : outils pointant vers le point de terminaison MCP de la Gateway, signé SigV4.
• Mode local (SERVE_LOCAL=true) : outils HTTP simples pointant vers la gateway locale démarrée par la cible serve-local du projet Gateway.

L’ID de session est propagé automatiquement aux serveurs MCP en aval via l’en-tête X-Amzn-Bedrock-AgentCore-Runtime-Session-Id.

Infrastructure

Après avoir exécuté le générateur, vous devez accorder à l’agent la permission d’invoquer la 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);

L’URL de la Gateway est automatiquement enregistrée dans l’espace de noms agentcore.gateways.<ClassName> de la Configuration d’exécution par le construct CDK généré, afin que l’agent puisse la découvrir au moment de l’exécution.

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
}

L’URL de la Gateway est automatiquement enregistrée dans l’espace de noms agentcore.gateways.<ClassName> de la Configuration d’exécution par le module Terraform généré, afin que l’agent puisse la découvrir au moment de l’exécution.

Développement local

Le générateur configure la cible dev de l’agent pour :

1. Démarrer la gateway locale de la Gateway connectée et chaque serveur MCP attaché
2. Définir LOCAL_DEV=true afin que le client généré pointe vers la gateway locale au lieu de la Gateway déployée

Exécutez l’agent localement avec :

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>

Pour exécuter l’agent localement contre la Gateway déployée (par exemple, pour tester les politiques Cedar), utilisez la cible serve de l’agent. Sans LOCAL_DEV défini, le client résout l’URL de la Gateway déployée depuis la configuration d’exécution et signe les requêtes avec SigV4 en utilisant vos identifiants AWS locaux :

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>

Fidélité locale

La gateway locale remplace la Gateway déployée, donc :

• Aucune évaluation de politique Cedar. Tous les outils sont visibles par l’agent indépendamment des politiques. Utilisez la cible serve pour tester les politiques contre la Gateway déployée.
• Le préfixage des noms d’outils est préservé. Les outils de chaque serveur MCP local sont exposés comme <target-name>___<tool-name>, correspondant à ce que la Gateway déployée émet. Cela maintient la cohérence du prompt système de l’agent et des noms d’actions Cedar que vous référencez entre les exécutions locales et déployées.