Agent Python

Générer un agent IA Python pour créer des agents avec des outils, et optionnellement le déployer sur Amazon Bedrock AgentCore Runtime. Choisissez le framework d’agent avec l’option framework : Strands (par défaut) ou LangChain (basé sur LangGraph).

Le générateur expose votre agent via un protocol de serveur. Les deux frameworks supportent HTTP (par défaut), le protocole Agent-to-Agent (A2A) pour l’interopérabilité avec d’autres agents compatibles A2A, et le protocole AG-UI pour une intégration frontend directe via CopilotKit.

Utilisation

Générer un agent

Vous pouvez générer un agent Python de deux manières :

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 - py#agent
5. Remplissez les paramètres requis
6. Cliquez sur Generate

CLI

pnpm

pnpm nx g @aws/nx-plugin:py#agent

yarn

yarn nx g @aws/nx-plugin:py#agent

npm

npx nx g @aws/nx-plugin:py#agent

bun

bunx nx g @aws/nx-plugin:py#agent

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

pnpm

pnpm nx g @aws/nx-plugin:py#agent --dry-run

yarn

yarn nx g @aws/nx-plugin:py#agent --dry-run

npm

npx nx g @aws/nx-plugin:py#agent --dry-run

bun

bunx nx g @aws/nx-plugin:py#agent --dry-run

Prérequis du projet

Utilisez d’abord le générateur py#project pour créer un projet auquel ajouter votre agent.

Options

Paramètre	Type	Par défaut	Description
project Requis	string	-	Le projet auquel ajouter l'Agent
framework	strands | langchain	strands	Le SDK d'agent à utiliser.
name	string	-	Le nom de votre Agent (par défaut : agent)
auth	iam | cognito	iam	La méthode utilisée pour s'authentifier auprès de votre Agent. Applicable uniquement lorsque infra est défini (ignoré lorsque infra est none).
protocol	http | a2a | ag-ui	http	Le protocole serveur pour votre Agent. HTTP expose un serveur HTTP FastAPI. A2A expose un serveur de protocole Agent-to-Agent. AG-UI expose un serveur de protocole Agent-User Interaction pour l'intégration directe avec le frontend.
iac	inherit | cdk | terraform	inherit	Le fournisseur IaC préféré. Par défaut, ceci est hérité de votre sélection initiale.
infra	agentcore | none	agentcore	Le type d'infrastructure pour héberger votre Agent.
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 sur 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.

Résultat du générateur

Le générateur ajoutera les fichiers suivants à votre projet Python existant. Les fichiers générés dépendent du protocol choisi :

protocol = http

Protocole HTTP (par défaut)

• Répertoireyour-project/

  • Répertoireyour_module/

    • Répertoireagent/ (ou nom personnalisé si spécifié)

      • __init__.py Initialisation du package Python
      • init.py Configuration de l’application FastAPI avec middleware CORS et gestion des erreurs
      • agent.py Définition principale de l’agent avec des outils exemples
      • main.py Point d’entrée FastAPI pour Bedrock AgentCore Runtime
      • Dockerfile Point d’entrée pour héberger votre agent (exclu si infra est None)
  • pyproject.toml Mis à jour avec les dépendances Strands
  • project.json Mis à jour avec les cibles de service de l’agent

protocol = a2a

Protocole A2A

Le point d’entrée expose votre agent via le protocole A2A (Strands utilise le Strands A2A Server ; LangChain enveloppe le graphe dans un exécuteur a2a-sdk), monté sur une application FastAPI :

• Répertoireyour-project/

  • Répertoireyour_module/

    • Répertoireagent/ (ou nom personnalisé si spécifié)

      • __init__.py Initialisation du package Python
      • agent.py Définition principale de l’agent avec des outils exemples
      • main.py Point d’entrée du serveur A2A
      • Dockerfile Point d’entrée pour héberger votre agent (exclu si infra est None)
  • pyproject.toml Mis à jour avec les dépendances du framework et A2A
  • project.json Mis à jour avec les cibles de service de l’agent

protocol = ag-ui

Protocole AG-UI

Le point d’entrée expose votre agent via le protocole AG-UI pour une intégration frontend directe avec CopilotKit. Les agents Strands utilisent l’intégration ag-ui-strands ; les agents LangChain utilisent ag-ui-langgraph :

• Répertoireyour-project/

  • Répertoireyour_module/

    • Répertoireagent/ (ou nom personnalisé si spécifié)

      • __init__.py Initialisation du package Python
      • agent.py Définition principale de l’agent avec des outils exemples
      • main.py Point d’entrée du serveur AG-UI
      • Dockerfile Point d’entrée pour héberger votre agent (exclu si infra est None)
  • pyproject.toml Mis à jour avec les dépendances du framework et AG-UI
  • project.json Mis à jour avec les cibles de service de l’agent

Connexion à un site web React

Les agents AG-UI peuvent être connectés à un frontend React en utilisant le générateur connection, qui configurera les composants CopilotKit pour une expérience de chat enrichie.

Infrastructure

infra = agentcore

Ce générateur fournit de l’infrastructure as code basée sur votre iacProvider choisi. Il créera un projet dans packages/common qui inclut les constructions CDK ou modules Terraform pertinents.

Le projet commun d’infrastructure as code est structuré comme suit :

CDK

• Répertoirepackages/common/constructs

  • Répertoiresrc

    • Répertoireapp/ Constructions pour l’infrastructure spécifique à un projet/générateur

      • …
    • Répertoirecore/ Constructions génériques réutilisées par celles dans app

      • …
    • index.ts Point d’entrée exportant les constructions depuis app
  • project.json Cibles de build et configuration du projet

Projet généré

Ce projet est généré avec le générateur ts#project et configure donc les mêmes cibles de build.

Terraform

• Répertoirepackages/common/terraform

  • Répertoiresrc

    • Répertoireapp/ Modules Terraform pour l’infrastructure spécifique à un projet/générateur

      • …
    • Répertoirecore/ Modules génériques réutilisés par ceux dans app

      • …
  • project.json Cibles de build et configuration du projet

Projet généré

Ce projet est généré avec le générateur terraform#project et configure donc les mêmes cibles de build.

Pour le déploiement de votre agent, les fichiers suivants sont générés :

CDK

• Répertoirepackages/common/constructs/src

  • Répertoireapp

    • Répertoireagents

      • Répertoire<project-name>

        • <project-name>.ts Construct CDK pour déployer votre agent

Terraform

• Répertoirepackages/common/terraform/src

  • Répertoireapp

    • Répertoireagents

      • Répertoire<project-name>

        • <project-name>.tf Module pour déployer votre agent
  • Répertoirecore

    • Répertoireagent-core

      • runtime.tf Module générique pour le déploiement sur Bedrock AgentCore Runtime

infra = none

Si vous avez sélectionné none pour infra, aucun construct CDK ou module Terraform n’est généré — l’agent ne peut être exécuté que localement. L’option auth est ignorée dans ce mode car il n’y a pas de point de terminaison hébergé à authentifier.

Architecture

Bedrock AgentCore Runtime

Lorsqu’il est déployé sur Bedrock AgentCore Runtime, l’agent est construit dans une image de conteneur, poussé vers Amazon ECR et exécuté dans AgentCore Runtime. Les clients invoquent le point de terminaison du plan de données AgentCore Runtime, qui transmet les requêtes à votre agent. L’agent appelle Amazon Bedrock pour l’inférence de modèle et peut invoquer des outils, des serveurs MCP ou des API en aval.

None (local only)

Avec infra: None, aucune infrastructure AWS n’est générée. L’agent s’exécute en tant que processus local et appelle Amazon Bedrock pour l’inférence de modèle.

Utilisation de votre agent

Vous pouvez éditer agent.py pour ajouter des outils, configurer le modèle et personnaliser le prompt système. L’API dépend du framework que vous avez choisi.

Ajout d’outils

Les outils sont des fonctions que l’agent IA peut appeler pour effectuer des actions. Les deux frameworks utilisent une approche basée sur des décorateurs pour définir les outils, dérivent le nom et la description de l’outil du nom de la fonction et de la docstring, et génèrent le schéma d’entrée à partir de vos annotations de type.

Strands

from strands import Agent, tool

@tool
def calculate_sum(numbers: list[int]) -> int:
    """Calcule la somme d'une liste de nombres"""
    return sum(numbers)

@tool
def get_weather(city: str) -> str:
    """Obtient les informations météo d'une ville"""
    # Votre intégration d'API météo ici
    return f"Weather in {city}: Sunny, 25°C"

# Ajoutez les outils à votre agent
agent = Agent(
    system_prompt="You are a helpful assistant with access to various tools.",
    tools=[calculate_sum, get_weather],
)

LangChain

from langchain.agents import create_agent
from langchain_aws import ChatBedrockConverse
from langchain_core.tools import tool

@tool
def calculate_sum(numbers: list[int]) -> int:
    """Calcule la somme d'une liste de nombres"""
    return sum(numbers)

@tool
def get_weather(city: str) -> str:
    """Obtient les informations météo d'une ville"""
    # Votre intégration d'API météo ici
    return f"Weather in {city}: Sunny, 25°C"

# Ajoutez les outils à votre agent
agent = create_agent(
    model=ChatBedrockConverse(model=MODEL_ID, region_name=REGION),
    tools=[calculate_sum, get_weather],
    system_prompt="You are a helpful assistant with access to various tools.",
)

Utilisation d’outils pré-définis

Strands

Strands fournit une collection d’outils prêts à l’emploi via le package strands-tools :

from strands_tools import current_time, http_request, file_read

agent = Agent(
    system_prompt="You are a helpful assistant.",
    tools=[current_time, http_request, file_read],
)

LangChain

LangChain fournit un large écosystème d’outils et intégrations. Installez le package d’intégration approprié, puis passez les outils à create_agent :

from langchain_community.tools import DuckDuckGoSearchRun

agent = create_agent(
    model=ChatBedrockConverse(model=MODEL_ID, region_name=REGION),
    tools=[DuckDuckGoSearchRun()],
    system_prompt="You are a helpful assistant.",
)

Configuration du modèle

Strands

Par défaut, les agents Strands utilisent Claude 4 Sonnet, mais vous pouvez personnaliser le fournisseur de modèle. Consultez la documentation Strands sur les fournisseurs de modèles pour les options de configuration :

from strands import Agent
from strands.models import BedrockModel

# Créez un BedrockModel
bedrock_model = BedrockModel(
    model_id="anthropic.claude-sonnet-4-20250514-v1:0",
    region_name="us-west-2",
    temperature=0.3,
)

agent = Agent(model=bedrock_model)

LangChain

Les agents LangChain utilisent un modèle ChatBedrockConverse. L’agent généré lit l’id du modèle et la région à partir des variables d’environnement MODEL_ID et AWS_REGION, mais vous pouvez configurer le modèle directement dans agent.py :

from langchain_aws import ChatBedrockConverse

model = ChatBedrockConverse(
    model="anthropic.claude-sonnet-4-20250514-v1:0",
    region_name="us-west-2",
    temperature=0.3,
)

Utilisation des serveurs MCP

Pour utiliser des serveurs MCP créés avec les générateurs py#mcp-server ou ts#mcp-server, vous pouvez utiliser le générateur connection, qui intègre les outils du serveur MCP dans votre agent pour les deux frameworks.

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

Consultez le guide du générateur connection pour plus de détails sur la configuration de la connexion.

Pour d’autres serveurs MCP, consultez la documentation MCP de Strands ou LangChain.

Pour aller plus loin

Pour un guide plus détaillé sur l’écriture d’agents, consultez la documentation de Strands ou LangChain.

Protocole

Le protocole serveur de votre agent détermine comment il communique. Toutes les options sont servies par FastAPI — le point d’entrée diffère :

• HTTP (par défaut) : Un serveur FastAPI standard avec un point de terminaison /invocations personnalisé, CORS et streaming. Idéal pour les intégrations client personnalisées.
• A2A : Un serveur Agent-to-Agent monté sur une application FastAPI (Strands utilise le Strands A2A Server ; LangChain utilise le a2a-sdk indépendant du framework). Idéal lorsque votre agent doit être découvrable et invocable par d’autres agents compatibles A2A.
• AG-UI : Le protocole AG-UI via SSE (Strands utilise ag-ui-strands ; LangChain utilise ag-ui-langgraph). Idéal pour une intégration frontend directe avec CopilotKit dans un site web React.

Le point d’entrée du serveur diffère selon le framework (Strands génère un Agent géré par contexte, tandis que LangChain pilote un graphe create_agent compilé), mais le contrat externe pour chaque protocole est le même.

Tous les protocoles exposent /ping pour le contrat de vérification de santé du runtime AgentCore. Les agents A2A écoutent sur le port 9000 ; les agents HTTP et AG-UI écoutent sur le port 8080. Le Dockerfile et l’infrastructure générés sont configurés pour vous.

protocol = http

Serveur FastAPI (protocole HTTP)

Le serveur HTTP généré inclut :

• Configuration de l’application FastAPI avec middleware CORS
• Middleware de gestion des erreurs
• Génération du schéma OpenAPI
• Point de terminaison de vérification de santé (/ping)
• Point de terminaison d’invocation de l’agent (/invocations)

Personnalisation des entrées et sorties d’invocation avec Pydantic

Le point de terminaison d’invocation de l’agent utilise des modèles Pydantic pour définir et valider les schémas de requête et de réponse. Vous pouvez personnaliser ces modèles dans main.py pour correspondre aux besoins de votre agent.

Définition des modèles d’entrée

Le modèle InvokeInput par défaut accepte un message.

from pydantic import BaseModel

class InvokeInput(BaseModel):
    message: str

Vous pouvez étendre ce modèle pour inclure tous les champs supplémentaires dont votre agent a besoin.

L’ID de session est extrait de l’en-tête HTTP x-amzn-bedrock-agentcore-runtime-session-id, conformément au contrat de session Bedrock AgentCore Runtime. Si l’en-tête n’est pas fourni, un UUID aléatoire est généré par défaut.

Organisation du code

Vous voudrez probablement abstraire tout ou partie de l’ID de session de l’appelant si les utilisateurs doivent invoquer votre agent directement. Par exemple, vous pouvez utiliser l’ID utilisateur authentifié comme partie de l’ID de session.

Il est également à noter que selon votre cas d’usage, vous devrez peut-être implémenter une autorisation pour les sessions, par exemple en vous assurant que les utilisateurs ne peuvent accéder qu’à leurs propres sessions et non à celles d’autres utilisateurs.

Définition des modèles de sortie

Pour les réponses en streaming, le générateur fournit JsonStreamingResponse qui sérialise automatiquement les modèles Pydantic au format JSON Lines (application/jsonl). Ce format est compatible avec la spécification de streaming d’OpenAPI 3.2 et fonctionne parfaitement avec le client TypeScript généré.

Par défaut, l’agent génère des objets StreamChunk contenant le texte de réponse de l’agent :

class StreamChunk(BaseModel):
    content: str

Vous pouvez personnaliser le modèle StreamChunk selon vos besoins :

from pydantic import BaseModel

class StreamChunk(BaseModel):
    content: str
    timestamp: str
    token_count: int

Limitation de streaming FastAPI

Notez que puisque FastAPI ne supporte pas actuellement la génération d’une spécification OpenAPI pour les réponses en streaming, nous devons explicitement définir le modèle de réponse pour chaque opération de streaming, c’est-à-dire :

@app.post(
    "/invocations",
    response_class=JsonStreamingResponse,
    responses={200: JsonStreamingResponse.openapi_response(StreamChunk)},
)
async def invoke(input: InvokeInput) -> JsonStreamingResponse:
    return JsonStreamingResponse(handle_invoke(input))

Il existe une demande de fonctionnalité ouverte pour un support natif dans FastAPI.

SDK Python Bedrock AgentCore

Le générateur inclut une dépendance au SDK Python Bedrock AgentCore pour les constantes PingStatus. Si vous le souhaitez, il est simple d’utiliser BedrockAgentCoreApp au lieu de FastAPI, mais notez que la sécurité des types est perdue.

Vous trouverez plus de détails sur les capacités du SDK dans la documentation ici.

Infrastructure as Code

Le générateur fournissant une infrastructure CDK ou Terraform pour déployer votre agent, vous n’avez pas besoin d’utiliser le bedrock-agentcore-starter-toolkit mentionné dans la documentation.

protocol = a2a

Serveur A2A (protocole A2A)

Le fichier main.py généré monte un serveur A2A sur une application FastAPI parente qui expose également /ping. Les agents Strands utilisent le A2AServer de Strands ; les agents LangChain enveloppent le graphe compilé dans un AgentExecutor a2a-sdk. Lorsqu’il est déployé sur AgentCore, le point d’entrée résout l’ARN public du runtime à partir d’AppConfig et l’annonce dans la carte d’agent.

La plupart des utilisateurs n’auront pas besoin de modifier ce fichier ; éditez agent.py pour changer les outils ou le prompt système. Le serveur A2A remplit la carte d’agent (/.well-known/agent-card.json) à partir du name et de la description de l’agent.

protocol = ag-ui

Serveur AG-UI (protocole AG-UI)

Le fichier main.py généré expose un seul point de terminaison POST qui diffuse des événements AG-UI via Server-Sent Events (SSE), ainsi que /ping pour la vérification de santé du runtime AgentCore. Le câblage dépend du framework :

• Strands : enveloppe votre Agent dans un ag_ui_strands.StrandsAgent et crée l’application FastAPI via create_strands_app().
• LangChain : enveloppe le graphe compilé dans un ag_ui_langgraph.LangGraphAgent et le sert depuis une boucle FastAPI /invocations faite à la main.

La plupart des utilisateurs n’auront pas besoin de modifier ce fichier — éditez agent.py pour changer les outils ou le prompt système.

Connexion à un site web React

Les agents AG-UI sont conçus pour être consommés directement par un frontend. Utilisez le générateur connection pour connecter votre site web React à l’agent avec un fournisseur CopilotKit et un client AG-UI HttpAgent.

Exécution de votre agent

Développement local

Pour exécuter votre agent (et tout ce qui y est connecté) localement, utilisez la cible dev du projet :

pnpm

pnpm nx dev your-project

yarn

yarn nx dev your-project

npm

npx nx dev your-project

bun

bunx nx dev your-project

Si vous avez ajouté plusieurs composants à votre projet (agents, serveurs MCP, etc.), cela les démarre tous. Pour exécuter uniquement cet agent, ciblez sa cible <your-agent-name>-dev :

pnpm

pnpm nx agent-dev your-project

yarn

yarn nx agent-dev your-project

npm

npx nx agent-dev your-project

bun

bunx nx agent-dev your-project

Cela utilise uv run pour exécuter votre agent via le SDK Python Bedrock AgentCore.

Discuter avec votre agent

Le générateur configure une cible Nx <your-agent-name>-chat qui vous place dans un chat terminal interactif avec votre agent.

La cible de chat s’exécute de manière autonome. Par défaut, elle se connecte à votre agent en cours d’exécution localement, donc démarrez d’abord la cible <your-agent-name>-dev de l’agent (dans un terminal séparé) :

pnpm

pnpm nx agent-dev your-project

yarn

yarn nx agent-dev your-project

npm

npx nx agent-dev your-project

bun

bunx nx agent-dev your-project

Ensuite, dans un autre terminal, démarrez le chat :

pnpm

pnpm nx run your-project:agent-chat

yarn

yarn nx run your-project:agent-chat

npm

npx nx run your-project:agent-chat

bun

bunx nx run your-project:agent-chat

Le générateur émet un scripts/<your-agent-name>/chat.ts pour chaque protocole. Il se connecte à l’agent local par défaut, ou à votre agent déployé lorsque RUNTIME_CONFIG_APP_ID est défini (voir Discuter avec votre agent déployé ci-dessous).

Pour les agents HTTP, le script de chat utilise un client TypeScript type-safe généré à partir de la spécification OpenAPI de l’agent. Le générateur émet également :

• scripts/<your-agent-name>_openapi.py — un petit script qui exporte la spécification OpenAPI de l’agent
• Une cible Nx <your-agent-name>-openapi qui l’exécute
• Une cible Nx <your-agent-name>-generate-client qui produit un client TypeScript type-safe sous scripts/<your-agent-name>/generated/

Lorsque vous personnalisez la forme d’entrée de l’agent (par exemple, ajoutez de nouveaux champs à InvokeInput), mettez à jour chat.ts pour passer les nouveaux champs lors de l’invocation de l’agent et le reste fonctionne automatiquement.

infra = agentcore

Discuter avec votre agent déployé

Pour discuter avec votre agent déployé sur Bedrock AgentCore, définissez la variable d’environnement RUNTIME_CONFIG_APP_ID sur l’id d’application AppConfig du déploiement (sortie en tant que RuntimeConfigApplicationId par la stack déployée). Le script de chat résout l’ARN d’exécution de votre agent à partir de la configuration d’exécution et se connecte au point de terminaison déployé :

IAM

Pour les agents authentifiés par IAM, les requêtes sont signées avec SigV4 en utilisant vos informations d’identification AWS par défaut. Assurez-vous que l’environnement dispose d’informations d’identification AWS avec la permission d’invoquer le runtime :

pnpm

RUNTIME_CONFIG_APP_ID=<app-id> pnpm nx run your-project:agent-chat

yarn

RUNTIME_CONFIG_APP_ID=<app-id> yarn nx run your-project:agent-chat

npm

RUNTIME_CONFIG_APP_ID=<app-id> npx nx run your-project:agent-chat

bun

RUNTIME_CONFIG_APP_ID=<app-id> bunx nx run your-project:agent-chat

Cognito

Pour les agents authentifiés par Cognito, fournissez un jeton d’accès Cognito via la variable d’environnement AGENT_ACCESS_TOKEN, qui est envoyé en tant que jeton bearer :

pnpm

RUNTIME_CONFIG_APP_ID=<app-id> AGENT_ACCESS_TOKEN=<access-token> pnpm nx run your-project:agent-chat

yarn

RUNTIME_CONFIG_APP_ID=<app-id> AGENT_ACCESS_TOKEN=<access-token> yarn nx run your-project:agent-chat

npm

RUNTIME_CONFIG_APP_ID=<app-id> AGENT_ACCESS_TOKEN=<access-token> npx nx run your-project:agent-chat

bun

RUNTIME_CONFIG_APP_ID=<app-id> AGENT_ACCESS_TOKEN=<access-token> bunx nx run your-project:agent-chat

Vous pouvez obtenir un jeton d’accès en utilisant la commande cognito-idp admin-initiate-auth de l’AWS CLI, par exemple :

aws cognito-idp admin-initiate-auth \
  --user-pool-id <user-pool-id> \
  --client-id <user-pool-client-id> \
  --auth-flow ADMIN_NO_SRP_AUTH \
  --auth-parameters USERNAME=<username>,PASSWORD=<password> \
  --query 'AuthenticationResult.AccessToken' \
  --output text

infra = agentcore

Déploiement de votre agent sur Bedrock AgentCore Runtime

Infrastructure as Code

Si vous avez sélectionné agentcore pour infra, l’infrastructure CDK ou Terraform correspondante est générée, que vous pouvez utiliser pour déployer votre Agent sur Amazon Bedrock AgentCore Runtime.

CDK

Un construct CDK est généré pour votre agent, nommé en fonction du name que vous avez choisi lors de l’exécution du générateur, ou <ProjectName>Agent par défaut.

Vous pouvez utiliser ce construct CDK dans une application CDK :

import { MyProjectAgent } from ':my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    new MyProjectAgent(this, 'MyProjectAgent');
  }
}

Construct CDK

Ce construct utilise le module aws-cdk-lib/aws-bedrockagentcore.

Terraform

Un module Terraform est généré pour vous, nommé en fonction du name que vous avez choisi lors de l’exécution du générateur, ou <ProjectName>-agent par défaut.

Transmettez les sorties du module partagé runtime_config_appconfig au module agent :

module "my_project_agent" {
  source = "../../common/terraform/src/app/agents/my-project-agent"

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn
}

Permissions des modèles Bedrock

Le construct d’agent généré accorde par défaut la permission d’invoquer tous les modèles de fondation et profils d’inférence Bedrock (bedrock:InvokeModel et bedrock:InvokeModelWithResponseStream sur arn:aws:bedrock:*:*:foundation-model/* et arn:aws:bedrock:*:*:inference-profile/*).

Vous pouvez souhaiter restreindre cela aux modèle(s) spécifiques utilisés par votre agent. Vous pouvez trouver le modèle par défaut utilisé par les agents Strands dans la documentation Strands ; consultez le guide des fournisseurs de modèles Strands pour configurer un modèle différent.

Docker requis

Docker est requis pour construire et déployer votre Agent. Assurez-vous d’avoir installé et lancé Docker pour éviter des erreurs telles que :

ERROR: Cannot connect to the Docker daemon at unix://path/to/docker.sock.

Authentification

Le générateur fournit une option auth pour configurer l’authentification de votre Agent. Vous pouvez choisir entre l’authentification IAM (par défaut) ou Cognito lors de la génération de votre agent.

IAM

Par défaut, votre Agent sera sécurisé à l’aide de l’authentification IAM, déployez-le simplement sans aucun argument :

CDK

import { MyProjectAgent } from ':my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    new MyProjectAgent(this, 'MyProjectAgent');
  }
}

Vous pouvez accorder l’accès pour invoquer votre agent sur Bedrock AgentCore Runtime en utilisant la méthode grantInvokeAccess, par exemple :

import { MyProjectAgent } from ':my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    const agent = new MyProjectAgent(this, 'MyProjectAgent');
    const lambdaFunction = new Function(this, ...);

    agent.grantInvokeAccess(lambdaFunction);
  }
}

Terraform

# Agent
module "my_project_agent" {
  # Relative path to the generated module in the common/terraform project
  source = "../../common/terraform/src/app/agents/my-project-agent"

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn
}

Pour accorder l’accès pour invoquer votre agent, vous devrez ajouter une politique telle que la suivante, en référençant la sortie module.my_project_agent.agent_core_runtime_arn :

{
  Effect = "Allow"
  Action = [
    "bedrock-agentcore:InvokeAgentRuntime"
  ]
  Resource = [
    module.my_project_agent.agent_core_runtime_arn,
    "${module.my_project_agent.agent_core_runtime_arn}/*"
  ]
}

Authentification Cognito

Lorsque vous sélectionnez l’authentification Cognito, le générateur configure l’agent pour utiliser Cognito pour l’authentification.

CDK

Le construct généré accepte une prop identity qui configure l’authentification Cognito :

import { MyProjectAgent, UserIdentity } from ':my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    const identity = new UserIdentity(this, 'Identity');

    new MyProjectAgent(this, 'MyProjectAgent', {
      identity,
    });
  }
}

Le construct UserIdentity peut être généré en utilisant le générateur ts#website#auth, ou vous pouvez créer votre propre UserPool et UserPoolClient CDK.

Terraform

Le module généré accepte les variables user_pool_id et user_pool_client_ids pour l’authentification Cognito :

module "user_identity" {
  source = "../../common/terraform/src/core/user-identity"
}

module "my_project_agent" {
  source = "../../common/terraform/src/app/agents/my-project-agent"

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn

  user_pool_id         = module.user_identity.user_pool_id
  user_pool_client_ids = [module.user_identity.user_pool_client_id]
}

Fournisseurs OIDC personnalisés

Si vous avez besoin d’une authentification JWT personnalisée avec un fournisseur OIDC non-Cognito, vous pouvez modifier directement le construct CDK ou le module Terraform généré pour votre agent. Notez que le générateur de connexion ne prendra en charge que l’authentification IAM ou Cognito.

Bonnes pratiques de sécurité

Lors de l’implémentation de la logique métier de votre agent, consultez les bonnes pratiques de sécurité Bedrock AgentCore Runtime.

Cibles Bundle et Docker

Pour construire votre agent pour Bedrock AgentCore Runtime, une cible bundle est ajoutée à votre projet, qui :

• Exporte vos dépendances Python dans un fichier requirements.txt via uv export
• Installe les dépendances pour la plateforme cible (aarch64-manylinux_2_28) via uv pip install

Une cible docker spécifique à votre agent est également ajoutée, qui copie le Dockerfile et les artefacts bundlés dans un répertoire de contexte Docker. Cela co-localise le Dockerfile avec la sortie construite, permettant à CDK de construire l’image Docker directement en utilisant AgentRuntimeArtifact.fromAsset.

Observabilité

Votre agent est automatiquement configuré avec l’observabilité via AWS Distro for Open Telemetry (ADOT), via l’auto-instrumentation dans votre Dockerfile.

Vous pouvez trouver les traces dans la console CloudWatch en sélectionnant “GenAI Observability” dans le menu. Notez que pour voir les traces, vous devez activer Transaction Search.

Pour plus de détails, consultez la documentation AgentCore sur l’observabilité.

Invocation de votre agent

protocol = http

Invoquer le serveur local

Pour invoquer un agent exécuté localement via la cible <your-agent-name>-serve, vous pouvez envoyer une simple requête POST à /invocations sur le port où votre agent local s’exécute. Par exemple, avec curl :

curl -N -X POST http://localhost:8081/invocations \
  -d '{"message": "what is 3 + 5?"}' \
  -H "Content-Type: application/json"

Flag de streaming Curl

L’argument -N donné à curl désactive la mise en mémoire tampon du flux de sortie, vous permettant de voir la réponse en streaming en temps réel.

Invoquer l’agent déployé

Pour invoquer votre Agent déployé sur Bedrock AgentCore Runtime, vous pouvez envoyer une requête POST au point de terminaison du plan de données Bedrock AgentCore Runtime avec votre ARN d’exécution encodé en URL.

Vous pouvez obtenir l’ARN d’exécution depuis votre infrastructure comme suit :

CDK

import { CfnOutput } from 'aws-cdk-lib';
import { MyProjectAgent } from ':my-scope/common-constructs';

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    const agent = new MyProjectAgent(this, 'MyProjectAgent');

    new CfnOutput(this, 'AgentArn', {
      value: agent.agentCoreRuntime.agentRuntimeArn,
    });
  }
}

Terraform

# Agent
module "my_project_agent" {
  # Relative path to the generated module in the common/terraform project
  source = "../../common/terraform/src/app/agents/my-project-agent"

  appconfig_application_id  = module.runtime_config_appconfig.application_id
  appconfig_application_arn = module.runtime_config_appconfig.application_arn
}

output "agent_arn" {
  value = module.my_project_agent.agent_core_runtime_arn
}

L’ARN aura le format suivant : arn:aws:bedrock-agentcore:<region>:<account>:runtime/<agent-runtime-id>.

Vous pouvez ensuite encoder l’ARN en URL en remplaçant : par %3A et / par %2F.

Console du navigateur

Ceci est simple dans une console de navigateur ou un REPL Node en utilisant la méthode intégrée encodeURIComponent :

encodeURIComponent('arn:aws:bedrock-agentcore:<region>:<account>:runtime/<agent-runtime-id>')

L’URL du plan de données Bedrock AgentCore Runtime pour invoquer l’agent est la suivante :

https://bedrock-agentcore.<region>.amazonaws.com/runtimes/<url-encoded-arn>/invocations

La manière exacte d’invoquer cette URL dépend de la méthode d’authentification utilisée.

IAM

Authentification IAM

Pour l’authentification IAM, la requête doit être signée avec AWS Signature Version 4 (SigV4).

acurl <region> bedrock-agentcore -N -X POST \
'https://bedrock-agentcore.<region>.amazonaws.com/runtimes/<url-encoded-arn>/invocations' \
-d '{"message": "what is 3 + 5?"}' \
-H 'Content-Type: application/json'

Cliquez ici pour plus de détails sur la configuration de la commande acurl ci-dessus

Cognito

Authentification JWT / Cognito

Pour l’authentification Cognito, passez le jeton d’accès Cognito dans l’en-tête Authorization :

curl -N -X POST 'https://bedrock-agentcore.<region>.amazonaws.com/runtimes/<url-encoded-arn>/invocations' \
  -d '{"message": "what is 3 + 5?"}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <access-token>"

Vous pouvez obtenir le jeton d’accès en utilisant la commande cognito-idp admin-initiate-auth de l’AWS CLI, par exemple :

aws cognito-idp admin-initiate-auth \
  --user-pool-id <user-pool-id> \
  --client-id <user-pool-client-id> \
  --auth-flow ADMIN_NO_SRP_AUTH \
  --auth-parameters USERNAME=<username>,PASSWORD=<password> \
  --region <region> \
  --query 'AuthenticationResult.AccessToken' \
  --output text

Navigateur / Site web React

Pour invoquer votre agent depuis un site web React, vous pouvez utiliser le générateur connection, qui configure automatiquement un client avec l’authentification appropriée (IAM ou Cognito).

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

Consultez le guide du générateur connection pour plus de détails sur la configuration de la connexion.

protocol = a2a

Invocation d’un agent A2A en tant qu’outil

Pour déléguer du travail de cet agent vers un agent A2A distant (soit TypeScript soit Python), utilisez le générateur connection. Il fournit un client authentifié SigV4 pour l’agent cible et transforme le agent.py de cet agent par AST pour enregistrer l’agent A2A distant en tant que délégué décoré avec @tool.

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

Consultez le guide du générateur connection pour plus de détails sur la configuration de la connexion.

protocol = ag-ui

Invocation d’un agent AG-UI

Pour invoquer votre agent AG-UI depuis un site web React, utilisez le générateur connection, qui configure un client CopilotKit pour votre agent déployé avec l’authentification appropriée (IAM ou Cognito).

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

Consultez le guide du générateur connection pour plus de détails sur la configuration de la connexion.

Connexions

Utilisez le générateur connection pour intégrer ce projet avec d’autres dans votre espace de travail. Les connexions suivantes impliquent ce projet :

React vers Python Agent Appeler un Python Agent depuis un site React

React vers AG-UI Agent Appeler un Agent exposant le protocole AG-UI depuis un site React via CopilotKit

Python Agent vers MCP Connecter un Python Agent à un serveur MCP

Python Agent vers A2A Agent Connecter un Python Agent à un agent A2A distant

TypeScript Agent vers A2A Agent Connecter un TypeScript Agent à un agent A2A distant

Python Agent vers Python DynamoDB Connecter un Python Agent à une table DynamoDB

Python Agent vers AgentCore Gateway Connecter un Python Agent à une AgentCore Gateway