AgentCore Gateway vers Agent

Le générateur connection peut enregistrer un agent (soit TypeScript ou Python) comme cible d’exécution AgentCore Runtime d’une AgentCore Gateway générée avec protocol: http.

Une fois connectée, la Gateway proxifie les requêtes pour l’agent sous <gatewayUrl>/<targetName>/invocations, en signant le trafic sortant vers l’exécution avec IAM SigV4. Cela donne à vos agents un point d’entrée unique et gouverné — et puisque les appelants n’ont besoin que d’atteindre la Gateway, les exécutions d’agents elles-mêmes peuvent être déployées à l’intérieur d’un VPC derrière celle-ci.

Prérequis

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

1. Un projet agentcore-gateway généré avec protocol: http
2. Un composant agent (ts#agent ou py#agent) créé avec infra: agentcore. Soit auth: iam (la Gateway l’invoque avec son propre rôle) ou auth: cognito (la Gateway transfère le JWT de l’appelant — voir Transférer l’identité de l’appelant vers l’exécution) fonctionne.

Agents HTTP TypeScript

Un agent http TypeScript sert tRPC sur WebSocket, et AgentCore Gateway ne prend pas en charge WebSocket ou le streaming bidirectionnel — le générateur rejette cette combinaison. Générez l’agent avec le protocole ag-ui à la place.

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 Gateway comme source et le projet agent comme cible. Si le projet agent contient plusieurs composants, spécifiez targetComponent pour lever l’ambiguïté.

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 relie les projets existants ensemble plutôt que d’émettre de nouveaux fichiers source. Les fichiers suivants sont modifiés :

• Répertoirepackages/<gateway>

  • project.json la cible dev de la Gateway gagne une dépendance sur le <agent>-dev de l’agent
  • local-dev.ts ATTACHED_AGENTS mis à jour pour que la gateway locale proxifie vers l’agent

Ajouter la cible agent à votre stack

Le générateur ne peut pas automatiquement câbler la cible agent dans votre infrastructure car il ne sait pas quelle stack ou quel module instancie la Gateway. Ajoutez vous-même un seul appel à gateway.addAgent(agent).

CDK

Dans la stack où vous instanciez la Gateway, enregistrez l’agent comme cible :

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);

Pour remplacer le nom de cible par défaut, passez gatewayTargetName :

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

Le construct accorde au rôle d’exécution de la Gateway l’accès d’invocation à l’exécution de l’agent et configure la cible avec le fournisseur d’identifiants GATEWAY_IAM_ROLE, de sorte que la Gateway signe les appels sortants avec son propre rôle.

Déployer des agents dans un VPC

Placer une Gateway devant un agent est ce qui rend joignable un agent déployé dans un VPC : les appelants s’adressent au point de terminaison public de la Gateway, et la Gateway atteint l’exécution en interne. Passez une configuration réseau VPC au construct de l’agent :

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 },
    },
  ),
});

Utilisez un sous-réseau privé avec sortie, pas un sous-réseau privé isolé : l’exécution a besoin d’un accès Internet sortant pour atteindre Bedrock et lire sa configuration depuis AWS AppConfig.

Les déploiements VPC d’AgentCore Runtime ne sont pris en charge que dans certaines zones de disponibilité. Si un déploiement échoue avec subnets are in unsupported availability zones, restreignez le VPC (ou la sélection de sous-réseaux) aux zones prises en charge pour votre région.

Terraform

Dans le fichier Terraform où vous instanciez la Gateway, câblez la cible agent :

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 {}
  }
}

Déployer des agents dans un VPC

Placer un agent derrière une Gateway est ce qui rend un agent déployé dans un VPC accessible : les appelants communiquent avec le point de terminaison public de la Gateway, et la Gateway atteint l’exécution en interne. Définissez les variables VPC du module agent :

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]
}

Utilisez des sous-réseaux privés avec sortie (une route vers une passerelle NAT), pas des sous-réseaux privés isolés : l’exécution nécessite un accès Internet sortant pour atteindre Bedrock et lire sa configuration depuis AWS AppConfig.

Invoquer l’agent via la Gateway

Les requêtes vers <gatewayUrl origin>/<targetName>/invocations sont transmises à l’exécution de l’agent sans traduction de protocole, de sorte que les appelants utilisent la même forme de requête qu’ils utiliseraient directement contre l’exécution — les flux SSE (AG-UI), le streaming JSON (Python HTTP) et A2A JSON-RPC passent tous par le proxy. Les appelants s’authentifient auprès de la Gateway (IAM SigV4 ou Cognito JWT selon l’auth de la Gateway) plutôt qu’auprès de l’agent.

Pour connecter un site web aux agents de la Gateway, utilisez le générateur de connexion de site web React vers AgentCore Gateway.

Transférer l’identité de l’appelant vers l’exécution

Par défaut, la Gateway signe les appels sortants avec son propre rôle IAM (le fournisseur d’identifiants GATEWAY_IAM_ROLE), de sorte que l’exécution voit l’identité de la Gateway, et non celle de l’appelant. Si au contraire vous souhaitez que l’agent autorise sur l’appelant — par exemple pour lire les revendications sub ou scope de l’utilisateur — placez un agent Cognito derrière une Gateway Cognito. La Gateway transfère alors le JWT de l’appelant vers l’exécution sans modification (le fournisseur d’identifiants JWT_PASSTHROUGH), et l’exécution le revalide.

Générez les deux extrémités avec auth: cognito et connectez-les comme ci-dessus :

• un agent (ts#agent ou py#agent) créé avec auth: cognito, et
• une Gateway créée avec auth: cognito faisant face au même pool d’utilisateurs Cognito.

Tout le reste est automatique — gateway.addAgent(agent) (CDK) et le module d’exécution Terraform généré gèrent le câblage pour vous en fonction de l’auth de l’agent :

• la cible est créée avec le fournisseur d’identifiants JWT_PASSTHROUGH (plutôt que GATEWAY_IAM_ROLE), et
• l’exécution met en liste blanche l’en-tête Authorization afin que le jeton transféré atteigne votre code d’agent. Sans cette liste blanche, AgentCore valide le jeton mais supprime l’en-tête avant votre conteneur.

Les appelants invoquent la Gateway avec Authorization: Bearer <jwt> (pas de SigV4), et l’agent lit les revendications depuis l’en-tête Authorization — en sautant la validation de signature, puisque l’autorisateur entrant de l’exécution a déjà vérifié le jeton :

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

Le passage JWT convient à un seul fournisseur d’identité dont l’audience de jeton couvre déjà l’exécution. Si une Gateway fait face à des agents sur plusieurs locataires ou audiences, utilisez plutôt l’échange de jetons on-behalf-of OAuth.

Développement local

L’exécution de la Gateway localement avec :

pnpm

pnpm nx dev <gateway-name>

yarn

yarn nx dev <gateway-name>

npm

npx nx dev <gateway-name>

bun

bunx nx dev <gateway-name>

démarre une gateway locale plus chaque agent attaché sur son port local assigné. La gateway locale proxifie les chemins /<targetName>/... vers le serveur local de chaque agent, correspondant au routage basé sur les chemins de la Gateway déployée.