Aller au contenu

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.

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

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

  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
    • Cliquez sur Generate
    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.

    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

    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 :

    • 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

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

    • 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

    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

    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],
    )

    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)

    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],
    )

    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 :

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

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

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

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

    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.

    Terminal window
    pnpm 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

    Section intitulée « Déploiement de votre agent Strands sur Bedrock AgentCore Runtime »

    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.

    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/*'],
    }),
    );
    }
    }

    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 :

    Par défaut, votre agent Strands sera sécurisé via l’authentification IAM. Déployez-le simplement sans arguments :

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

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

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

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