Agent de Strands Python

Générez un Agent Strands en Python pour créer des agents IA avec des outils, et déployez-le éventuellement sur Amazon Bedrock AgentCore Runtime.

Qu’est-ce que Strands ?

Strands est un framework Python léger et prêt pour la production permettant de créer des agents IA. Principales fonctionnalités :

• Léger et personnalisable : Boucle d’agent simple qui reste discrète
• Prêt pour la production : Observabilité complète, traçage et options de déploiement évolutif
• Agnostique aux modèles et fournisseurs : Prend en charge de nombreux modèles de différents fournisseurs
• Outils communautaires : Ensemble puissant d’outils contribués par la communauté
• Support multi-agents : Techniques avancées comme les équipes d’agents et agents autonomes
• Modes d’interaction flexibles : Support conversationnel, streaming et non-streaming

Utilisation

Générer un Agent Strands

Vous pouvez générer un Agent Strands en Python de deux façons :

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

CLI

pnpm

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

yarn

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

npm

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

bun

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

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

pnpm

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

yarn

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

npm

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

bun

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

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

Options

Paramètre	Type	Par défaut	Description
project Requis	string	-	The project to add the Strands Agent to
computeType	string	BedrockAgentCoreRuntime	The type of compute to host your Strands Agent.
name	string	-	The name of your Strands Agent (default: agent)
iacProvider	string	CDK	The preferred IaC provider

Résultat du générateur

Le générateur ajoutera les fichiers suivants à votre projet Python existant :

• 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 pour Bedrock AgentCore Runtime
      • agentcore_mcp_client.py Factory client utile pour invoquer des serveurs MCP hébergés sur Bedrock AgentCore Runtime
      • Dockerfile Point d’entrée pour héberger votre agent (exclu si computeType est None)
  • pyproject.toml Mis à jour avec les dépendances Strands
  • project.json Mis à jour avec les cibles de service de l’agent

Infrastructure

Note

Si vous avez sélectionné None pour computeType, le générateur ne fournira aucune infrastructure as code.

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

Note

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

Note

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 Strands, 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
        • Dockerfile Fichier Docker transmis utilisé par le construct CDK
  • Répertoirecore

    • Répertoireagent-core

      • runtime.ts Construct CDK générique pour le déploiement sur Bedrock AgentCore Runtime

Terraform

• Répertoirepackages/common/terraform/src

  • Répertoireapp

    • Répertoireagents

      • Répertoire<project-name>

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

    • Répertoireagent-core

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

Utilisation de votre Agent Strands

Ajout d’outils

Les outils sont des fonctions que l’agent IA peut appeler pour effectuer des actions. Le framework Strands utilise une approche basée sur des décorateurs pour définir les outils.

Vous pouvez ajouter de nouveaux outils dans le fichier agent.py :

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 pour une ville"""
    # Intégration de votre API météo ici
    return f"Météo à {city} : Ensoleillé, 25°C"

# Ajout des outils à votre agent
agent = Agent(
    system_prompt="Vous êtes un assistant utile avec accès à divers outils.",
    tools=[calculate_sum, get_weather],
)

Le framework Strands gère automatiquement :

• La validation des types basée sur les indications de type
• La génération de schémas JSON pour l’appel d’outils
• La gestion des erreurs et le formatage des réponses

Utilisation d’outils pré-construits

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="Vous êtes un assistant utile.",
    tools=[current_time, http_request, file_read],
)

Configuration du modèle

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

from strands import Agent
from strands.models import BedrockModel

# Création d'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)

Utilisation des serveurs MCP

Vous pouvez ajouter des outils depuis des serveurs MCP à votre agent Strands.

Pour utiliser les serveurs MCP créés avec les générateurs py#mcp-server ou ts#mcp-server (ou d’autres hébergés sur Bedrock AgentCore Runtime), une factory client est générée pour vous dans agentcore_mcp_client.py.

Vous pouvez mettre à jour votre méthode get_agent dans agent.py pour créer des clients MCP et ajouter des outils. L’exemple suivant montre comment faire cela avec une authentification IAM (SigV4) :

agent.py

import os
from contextlib import contextmanager

import boto3
from strands import Agent

from .agentcore_mcp_client import AgentCoreMCPClient

# Obtention de la région et des credentials
region = os.environ["AWS_REGION"]
boto_session = boto3.Session(region_name=region)
credentials = boto_session.get_credentials()

@contextmanager
def get_agent(session_id: str):
    mcp_client = AgentCoreMCPClient.with_iam_auth(
        agent_runtime_arn=os.environ["MCP_AGENTCORE_RUNTIME_ARN"],
        credentials=credentials,
        region=region,
        session_id=session_id,
    )

    with mcp_client:
        mcp_tools = mcp_client.list_tools_sync()

        yield Agent(
            system_prompt="..."
            tools=[*mcp_tools],
        )

Si votre serveur MCP cible utilise l’authentification JWT, vous pouvez utiliser la méthode AgentCoreMCPClient.with_jwt_auth à la place.

Avec l’exemple d’authentification IAM ci-dessus, nous devons configurer deux éléments dans notre infrastructure. D’abord, ajouter la variable d’environnement consommée par notre agent pour l’ARN du runtime AgentCore du serveur MCP, puis accorder les permissions d’invocation à notre agent. Cela peut être réalisé ainsi :

CDK

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

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

    const agent = new MyProjectAgent(this, 'MyProjectAgent', {
      environment: {
        MCP_AGENTCORE_RUNTIME_ARN: mcpServer.agentCoreRuntime.arn,
      },
    });

    mcpServer.agentCoreRuntime.grantInvoke(agent.agentCoreRuntime);
  }
}

Terraform

# Serveur MCP
module "my_project_mcp_server" {
  source = "../../common/terraform/src/app/mcp-servers/my-project-mcp-server"
}

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

  env = {
    MCP_AGENTCORE_RUNTIME_ARN = module.my_project_mcp_server.agent_core_runtime_arn
  }

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

Pour aller plus loin

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

SDK Python Bedrock AgentCore

Le générateur configure le SDK Python Bedrock AgentCore pour gérer le contrat HTTP sous-jacent que les agents sur AgentCore doivent implémenter.

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

Note

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.

Exécution de votre Agent Strands

Développement local

Le générateur configure une cible nommée <your-agent-name>-serve qui démarre votre Agent Strands localement pour le développement et les tests.

pnpm

pnpm nx run your-project:agent-serve

yarn

yarn nx run your-project:agent-serve

npm

npx nx run your-project:agent-serve

bun

bunx nx run your-project:agent-serve

Cette commande utilise uv run pour exécuter votre Agent Strands avec le SDK Python Bedrock AgentCore.

Déploiement sur Bedrock AgentCore Runtime

Infrastructure as Code

Si vous avez sélectionné BedrockAgentCoreRuntime pour computeType, l’infrastructure CDK ou Terraform pertinente est générée pour déployer votre Agent Strands sur Amazon Bedrock AgentCore Runtime.

CDK

Un construct CDK est généré pour vous, nommé selon le name 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) {
    // Ajoutez l'agent à votre stack
    const agent = new MyProjectAgent(this, 'MyProjectAgent');

    // Accordez les permissions d'invoquer les modèles Bedrock concernés
    agent.agentCoreRuntime.role.addToPolicy(
      new PolicyStatement({
        actions: [
          'bedrock:InvokeModel',
          'bedrock:InvokeModelWithResponseStream',
        ],
        // Vous pouvez restreindre cette portée aux modèles spécifiques utilisés
        resources: ['arn:aws:bedrock:*::foundation-model/*'],
      }),
    );
  }
}

Terraform

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

Vous pouvez utiliser ce module Terraform dans un projet Terraform :

# Agent
module "my_project_agent" {
  # Chemin relatif vers le module généré dans common/terraform
  source = "../../common/terraform/src/app/agents/my-project-agent"

  # Accordez les permissions d'invoquer les modèles Bedrock concernés
  additional_iam_policy_statements = [
    {
      Effect = "Allow"
      Action = [
        "bedrock:InvokeModel",
        "bedrock:InvokeModelWithResponseStream"
      ]
      Resource = [
        "arn:aws:bedrock:*::foundation-model/*"
      ]
    }
  ]
}

Note

Lors du déploiement sur Bedrock AgentCore Runtime, assurez-vous que les modèles de base appropriés sont activés dans votre compte AWS. Par défaut, les agents Strands utilisent Claude 4 Sonnet, mais ceci peut être personnalisé comme décrit ci-dessus.

Pour activer l’accès aux modèles dans Amazon Bedrock, suivez les instructions ici.

Attention

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

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

Cibles Bundle et Docker

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

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

Une cible docker spécifique à votre Agent Strands est également ajoutée, qui :

• Construit une image Docker depuis le Dockerfile exécutant votre agent, conformément au contrat runtime AgentCore

L’image Docker est construite avec un tag (ex: my-scope-my-project-agent:latest), référencé par votre infrastructure CDK ou Terraform, permettant à votre Dockerfile d’être co-localisé avec votre projet Strands Agent.

Authentification

IAM

Par défaut, votre Agent Strands est sécurisé avec l’authentification IAM. Déployez-le simplement sans arguments :

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 à invoquer votre agent sur Bedrock AgentCore Runtime avec la méthode grantInvoke, 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.agentCoreRuntime.grantInvoke(lambdaFunction);
  }
}

Terraform

# Agent
module "my_project_agent" {
  # Chemin relatif vers le module généré dans common/terraform
  source = "../../common/terraform/src/app/agents/my-project-agent"
}

Pour accorder l’accès d’invocation, ajoutez une politique 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 JWT

L’exemple suivant montre comment configurer l’authentification Cognito pour votre agent.

CDK

Pour configurer l’authentification JWT, passez la propriété authorizerConfiguration à votre construct agent. Exemple configurant un user pool Cognito :

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

export class ExampleStack extends Stack {
  constructor(scope: Construct, id: string) {
    const userPool = new UserPool(this, 'UserPool');
    const client = userPool.addClient('Client', {
      authFlows: {
        userPassword: true,
      },
    });

    new MyProjectAgent(this, 'MyProjectAgent', {
      authorizerConfiguration: {
        customJWTAuthorizer: {
          discoveryUrl: `https://cognito-idp.${Stack.of(userPool).region}.amazonaws.com/${userPool.userPoolId}/.well-known/openid-configuration`,
          allowedClients: [client.userPoolClientId],
        },
      },
    });
  }
}

Terraform

Pour configurer l’authentification JWT, modifiez votre module agent pour configurer la variable customJWTAuthorizer :

packages/common/terraform/src/app/agents/my-project-agent/my-project-agent.tf

data "aws_region" "current" {}

locals {
  aws_region = data.aws_region.current.name

  # Remplacez par vos IDs user pool/client ou exposez-les comme variables
  user_pool_id = "xxx"
  user_pool_client_ids = ["yyy"]
}

module "agent_core_runtime" {
  source = "../../../core/agent-core"
  agent_runtime_name = "MyProjectAgent"
  docker_image_tag = "my-scope-my-project-agent:latest"
  server_protocol = "HTTP"
  customJWTAuthorizer = {
    discoveryUrl = "https://cognito-idp.${local.aws_region}.amazonaws.com/${local.user_pool_id}/.well-known/openid-configuration",
    allowedClients = local.user_pool_client_ids
  }
  env = var.env
  additional_iam_policy_statements = var.additional_iam_policy_statements
  tags = var.tags
}

Observabilité

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

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

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