Agent de Strands Python

Générer un agent Strands Agent en Python pour créer des agents IA avec des outils, et optionnellement le déployer 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 évolutives
• Agnostique aux modèles et fournisseurs : Supporte 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 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#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

Astuce

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	Inherit	The preferred IaC provider. By default this is inherited from your initial selection.

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 générera pas d’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 d'une ville"""
    # Votre intégration d'API météo ici
    return f"Météo à {city} : Ensoleillé, 25°C"

# Ajoutez les 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 via les annotations 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é-définis

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

Utilisation des serveurs MCP

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

Pour utiliser des 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 l’authentification IAM (SigV4) :

agent.py

import os
from contextlib import contextmanager

import boto3
from strands import Agent

from .agentcore_mcp_client import AgentCoreMCPClient

# Obtenez la région et les 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],
        )

Astuce

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. Premièrement, ajouter la variable d’environnement consommée par notre agent pour l’ARN du runtime AgentCore du serveur MCP, et deuxièmement accorder les permissions d’invocation à notre agent. Cela peut être réalisé comme suit :

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.

Serveur FastAPI

Le générateur utilise FastAPI pour créer le serveur HTTP de votre agent Strands. FastAPI fournit un framework web moderne et rapide pour créer des API avec Python, avec documentation API automatique et validation de types.

Le serveur 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 prompt et un ID de session.

from pydantic import BaseModel

class InvokeInput(BaseModel):
    prompt: str
    session_id: str

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

Attention

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, l’annotation de type de retour sur votre point de terminaison correspond au type de chaque valeur générée par votre fonction génératrice. Par défaut, l’agent génère des chaînes contenant le texte de réponse de l’agent tel qu’il est diffusé en continu depuis Strands :

@app.post("/invocations", openapi_extra={"x-streaming": True})
async def invoke(input: InvokeInput) -> str:
    """Point d'entrée pour l'invocation de l'agent"""
    return StreamingResponse(handle_invoke(input), media_type="text/event-stream")

Vous pouvez définir un modèle Pydantic pour générer des données structurées à la place :

from pydantic import BaseModel

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

@app.post("/invocations", openapi_extra={"x-streaming": True})
async def invoke(input: InvokeInput) -> StreamChunk:
    return StreamingResponse(handle_invoke(input), media_type="application/json")

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.

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 via le SDK Python Bedrock AgentCore.

Déploiement de votre agent Strands 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'invocation des modèles Bedrock
    agent.agentCoreRuntime.role.addToPolicy(
      new PolicyStatement({
        actions: [
          'bedrock:InvokeModel',
          'bedrock:InvokeModelWithResponseStream',
        ],
        // Vous pouvez restreindre cette ressource 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 le projet common/terraform
  source = "../../common/terraform/src/app/agents/my-project-agent"

  # Accordez les permissions d'invocation des modèles Bedrock
  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 via uv export
• Installe les dépendances pour la plateforme cible (aarch64-manylinux2014) via 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

Astuce

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 d’agent Strands.

Authentification

IAM

Par défaut, votre agent Strands sera sécurisé via 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 à votre agent sur Bedrock AgentCore Runtime via 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 le projet common/terraform
  source = "../../common/terraform/src/app/agents/my-project-agent"
}

Pour accorder l’accès à votre agent, ajoutez une politique IAM 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 de 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), via l’auto-instrumentation dans votre Dockerfile.

Vous pouvez trouver les traces dans la console 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é.