View a markdown version of this page

Commencez avec la AgentCore CLI - Amazon Bedrock AgentCore
Conditions préalablesÉtape 1 : Installation de la AgentCore CLIÉtape 2 : Créez votre projet d'agentÉtape 3 : Testez votre agent localementÉtape 4 : Activez l'observabilité pour votre agentÉtape 5 : Déploiement sur Amazon Bedrock Runtime AgentCoreÉtape 6 : testez votre agent déployéÉtape 7 : Invoquez votre agent déployéÉtape 8 : nettoyerIdentifiez vos ressourcesProblèmes courants et solutions correspondantesOptions avancées (facultatif)

Commencez avec la AgentCore CLI

Ce didacticiel explique comment utiliser la AgentCore CLI pour créer, déployer et invoquer un agent Python sur Amazon Bedrock AgentCore Runtime.

La AgentCore CLI est un outil de ligne de commande qui structure les projets d'agents, les déploie sur Amazon AgentCore Bedrock Runtime et les invoque. Vous pouvez utiliser la CLI avec des frameworks d'agents Python courants tels que Strands Agents LangChain/LangGraph, Google ADK et OpenAI Agents. Ce didacticiel utilise des agents Strands.

Pour plus d'informations sur le protocole HTTP utilisé par l'agent, consultez le contrat de protocole HTTP.

Conditions préalables

Avant de commencer, assurez-vous d'avoir :

  • AWS Compte avec informations d'identification configurées. Pour configurer vos AWS informations d'identification, consultez la section Configuration et paramètres des fichiers d'identification dans la AWS CLI.

  • Node.js Plus de 20 personnes installées. La AgentCore CLI est distribuée sous forme de package npm.

  • Python 3.10+ installé. Le code de l'agent généré est Python.

  • AWS CDK installé. La CLI utilise le AWS CDK pour déployer des ressources. Pour plus d'informations, consultez la section Mise en route avec le AWS CDK.

  • AWS Autorisations : pour créer et déployer un agent avec la AgentCore CLI, vous devez disposer des autorisations appropriées. Pour plus d'informations, consultez la section Utiliser la AgentCore CLI.

  • Accès au modèle : Anthropic Claude Sonnet 4.0 activé dans la console Amazon Bedrock (si vous utilisez Bedrock comme fournisseur de modèles). Pour plus d'informations sur l'utilisation d'un modèle différent avec Strands Agents, consultez la section Fournisseurs de modèles dans la documentation du SDK Strands Agents.

Étape 1 : Installation de la AgentCore CLI

Installez la AgentCore CLI globalement :

npm install -g @aws/agentcore

Vérifiez l’installation :

agentcore --help

Vous devez voir des résultats similaires à ce qui suit :

Usage: agentcore [options] [command]

Build and deploy Agentic AI applications on AgentCore

Options:
  -V, --version                output the version number
  -h, --help                   Display help

Commands:
  add [subcommand]             Add resources (agent, evaluator, online-eval,
                               memory, identity, target)
  dev|d [options]              Launch local development server with hot-reload.
  deploy|p [options]           Deploy project infrastructure to AWS via CDK.
  create [options]             Create a new AgentCore project
  evals                        View past eval run results.
  fetch                        Fetch access info for deployed resources.
  help                         Display help topics
  invoke|i [options] [prompt]  Invoke a deployed agent endpoint.
  logs|l [options]             Stream or search agent runtime logs.
  package|pkg [options]        Package agent artifacts without deploying.
  pause                        Pause an online eval config.
  remove [subcommand]          Remove resources from project config.
  resume                       Resume a paused online eval config.
  run                          Run on-demand evaluation.
  status|s [options]           Show deployed resource details and status.
  traces|t                     View and download agent traces.
  update [options]             Check for and install CLI updates
  validate [options]           Validate agentcore/ config files.

Étape 2 : Créez votre projet d'agent

Utilisez la agentcore create commande pour créer un nouveau projet d'agent :

Exemple
AgentCore CLI

  1. Passez des drapeaux directement pour créer un projet de manière non interactive :

    agentcore create --name MyAgent --framework Strands --protocol HTTP --model-provider Bedrock --memory none

    Pour accepter toutes les valeurs par défaut (Python, Strands, Bedrock, pas de mémoire), utilisez le --defaults drapeau :

    agentcore create --name MyAgent --defaults
Interactive

  1. Exécutez agentcore create sans drapeaux pour lancer l'assistant interactif :

    agentcore create

  2. Entrez le nom de votre projet :

    Assistant de création : entrez le nom du projet

  3. Choisissez votre framework d'agents et votre fournisseur de modèles :

    Assistant de création : sélectionnez le framework

  4. Vérifiez votre configuration et confirmez :

    Assistant de création : révision et confirmation

La agentcore create commande accepte les drapeaux suivants :

  • --name— Le nom du projet (alphanumérique, commence par une lettre, 36 caractères maximum).

  • --framework— Le framework des agents. Valeurs prises en charge : StrandsLangChain_LangGraph,GoogleADK,OpenAIAgents.

  • --protocol— Le mode protocole. Valeurs prises en charge : HTTP (par défaut),MCP,A2A.

  • --build— Le type de construction. Valeurs prises en charge : CodeZip (par défaut),Container.

  • --model-provider— Le fournisseur de modèles. Valeurs prises en charge : BedrockAnthropic,OpenAI,Gemini.

  • --memory— Configuration de la mémoire. Valeurs prises en charge :none,shortTerm,longAndShortTerm.

La commande génère un répertoire de projet dont la structure est la suivante :

MyAgent/
  agentcore/
    agentcore.json        # Project and agent configuration
    aws-targets.json      # AWS account and region targets
    .env.local            # Local environment variables (gitignored)
  app/
    MyAgent/
      main.py             # Agent entrypoint
      pyproject.toml      # Python dependencies
  README.md

Le agentcore/agentcore.json fichier contient la configuration de votre projet et de votre agent. Le app/MyAgent/main.py fichier contient le code de l'agent de démarrage utilisant le framework que vous avez sélectionné.

Pour ajouter des fonctionnalités de paiement à votre projet, exécutez :

agentcore add payment-manager --name MyPayments --auto-payment --default-spend-limit 5.00
agentcore add payment-connector --manager MyPayments --name MyConnector --provider CoinbaseCDP \
  --api-key-id <KEY_ID> --api-key-secret <KEY_SECRET> --wallet-secret <WALLET_SECRET>

Cela permet de configurer l'infrastructure de paiement AgentCorePaymentsPlugin de votre agent et de provisionner l'infrastructure de paiement lors du déploiement. Voir Démarrage rapide des paiements pour le flux de travail complet.

Étape 3 : Testez votre agent localement

Avant de le déployer sur AWS, testez votre agent localement à l'aide du serveur de développement. Tout d'abord, allez dans le répertoire du projet :

cd MyAgent

Si vous avez sélectionné un fournisseur de modèles nécessitant une clé d'API (OpenAI, Anthropic ou Gemini), assurez-vous que la clé est configurée dans. agentcore/.env.local

Démarrez le serveur de développement local :

Exemple
AgentCore CLI

  1. agentcore dev
Interactive

  1. Exécutez agentcore pour ouvrir l'écran d'accueil de TUI, puis sélectionnez dev pour démarrer le serveur de développement local :

    agentcore
    AgentCore agent inspecteur avec invite de chat

La agentcore dev commande :

  • Ouvre l'inspecteur d'agents dans votre navigateur Web

  • Crée automatiquement un environnement virtuel Python et installe les dépendances

  • Démarre un serveur local qui imite l' AgentCore environnement d'exécution

  • Fonctionne http://localhost:8080 par défaut (-pà utiliser pour changer de port)

Pour consulter les journaux du serveur en temps réel (mode non interactif), utilisez l'--logsindicateur :

agentcore dev --logs

Dans un terminal séparé, appelez votre agent local :

agentcore dev "Hello, tell me a joke"

La transmission d'une invite l'envoie au serveur de développement local en cours d'exécution. --streamUtilisez-le pour voir la réponse diffusée en temps réel.

Étape 4 : Activez l'observabilité pour votre agent

Amazon Bedrock AgentCore Observability vous permet de suivre, de déboguer et de surveiller les agents que vous hébergez dans Amazon Bedrock Runtime. AgentCore Activez d'abord CloudWatch Transaction Search en suivant les instructions de la section Activer l'observabilité du AgentCore runtime Amazon Bedrock. Pour observer votre agent, consultez Afficher les données d'observabilité de vos agents Amazon Bedrock AgentCore .

Après avoir déployé votre agent, vous pouvez utiliser la AgentCore CLI pour diffuser les journaux et afficher les traces :

# Stream agent logs
agentcore logs

# List recent traces
agentcore traces list

Étape 5 : Déploiement sur Amazon Bedrock Runtime AgentCore

Déployez votre agent sur Amazon Bedrock AgentCore Runtime :

Exemple
AgentCore CLI

  1. agentcore deploy
Interactive

  1. Exécutez agentcore deploy pour démarrer le déploiement. La CLI indique la progression du déploiement au fur et à mesure de la création et du déploiement de votre projet :

    agentcore deploy
    Progression du déploiement : création CloudFormation des ressources et état du déploiement

Pour prévisualiser le déploiement sans apporter de modifications, utilisez le --dry-run drapeau :

agentcore deploy --dry-run

La agentcore deploy commande :

  • Lit votre agentcore/aws-targets.json configuration agentcore/agentcore.json et

  • Empaquète le code de votre agent (sous forme d' CodeZip archive ou de conteneur Docker, selon votre type de build)

  • Utilise le AWS CDK pour synthétiser et déployer les ressources CloudFormation

  • Crée les AWS ressources nécessaires (rôles IAM, Amazon Bedrock AgentCore Runtime, etc.)

-vÀ utiliser pour une sortie détaillée qui montre les événements de déploiement au niveau des ressources. -yÀ utiliser pour confirmer automatiquement le déploiement sans invite.

Si le déploiement échoue, vérifiez les problèmes courants.

Étape 6 : testez votre agent déployé

Une fois le déploiement terminé, appelez votre agent déployé :

Exemple
AgentCore CLI

  1. agentcore invoke "Tell me a joke"

    Vous pouvez également transmettre l'invite avec l'--promptindicateur, spécifier un environnement d'exécution avec --runtime ou diffuser la réponse en temps réel avec --stream :

    agentcore invoke --prompt "Tell me a joke" --stream

    Pour maintenir une conversation après plusieurs invocations, utilisez le --session-id drapeau :

    agentcore invoke --session-id my-session "What else can you tell me?"

    Si votre agent a configuré les paiements, fournissez le contexte du paiement :

    agentcore invoke \
  --prompt "Access https://example-x402-merchant.com/paid-api" \
  --payment-instrument-id <INSTRUMENT_ID> \
  --auto-session \
  --payment-user-id user@example.com
Interactive

  1. Exécutez agentcore pour ouvrir l'écran d'accueil de TUI, puis sélectionnez l'option d'appel pour discuter avec votre agent déployé :

    agentcore
    Appelez l'écran TUI affichant l'interface de chat

Si vous voyez une blague dans la réponse, cela signifie que votre agent fonctionne dans Amazon Bedrock AgentCore Runtime et peut être invoqué. Si ce n'est pas le cas, vérifiez les problèmes courants.

Étape 7 : Invoquez votre agent déployé

Exemple
AgentCore CLI

  1. Appelez votre agent déployé à l'aide d'une invite :

    agentcore invoke --runtime MyAgent "Hello, what can you do?"

    Diffusez la réponse en temps réel :

    agentcore invoke --runtime MyAgent "Tell me a joke" --stream

    Exécutez agentcore invoke sans qu'on vous demande d'ouvrir le chat interactif TUI, qui diffuse les réponses par défaut et gère automatiquement votre session.

AWS Python SDK (Boto3)

  1. Vous pouvez également appeler l'agent à l'aide de l'InvokeAgentRuntimeopération du AWS SDK. Pour obtenir l'ARN de votre agent déployé, utilisez la agentcore status commande suivante :

    agentcore status

    Utilisez le code boto3 (AWS SDK pour Python) suivant pour appeler votre agent. Agent ARNRemplacez-le par l'ARN de votre agent. Vérifiez que vous disposez des bedrock-agentcore:InvokeAgentRuntime autorisations nécessaires. Créez un fichier nommé invoke_agent.py et ajoutez le code suivant :

    import json
import uuid
import boto3

agent_arn = "Agent ARN"
prompt = "Tell me a joke"

# Initialize the Amazon Bedrock AgentCore client
agent_core_client = boto3.client('bedrock-agentcore')

# Prepare the payload
payload = json.dumps({"prompt": prompt}).encode()

# Invoke the agent
response = agent_core_client.invoke_agent_runtime(
    agentRuntimeArn=agent_arn,
    runtimeSessionId=str(uuid.uuid4()),
    payload=payload,
    qualifier="DEFAULT"
)

content = []
for chunk in response.get("response", []):
    content.append(chunk.decode('utf-8'))
print(json.loads(''.join(content)))

    Ouvrez une fenêtre de terminal et exécutez le code à l'aide de la commande suivante :

    python invoke_agent.py

    En cas de succès, vous devriez voir une blague dans la réponse. Si l'appel échoue, consultez les journaux à l'aide d'Amazon agentcore logs ou consultez-les sur Amazon CloudWatch.

    Note

    Si vous envisagez d'intégrer votre agent à OAuth, vous ne pouvez pas utiliser le AWS SDK pour appeler. InvokeAgentRuntime Envoyez plutôt une requête HTTPS àInvokeAgentRuntime. Pour plus d'informations, consultez Authentifier et autoriser avec l'authentification entrante et l'authentification sortante.

Étape 8 : nettoyer

Si vous ne souhaitez plus héberger l'agent dans Amazon Bedrock AgentCore Runtime, supprimez les AWS ressources déployées. Tout d'abord, supprimez toutes les ressources de votre configuration locale :

Exemple
AgentCore CLI

  1. agentcore remove all
Interactive

  1. Exécutez agentcore pour ouvrir l'écran d'accueil de TUI, puis sélectionnez l'option de suppression pour choisir les ressources à supprimer :

    agentcore
    Supprimer la sélection de ressources TUI

Déployez ensuite à nouveau pour réduire les AWS ressources :

Exemple
AgentCore CLI

  1. agentcore deploy
Interactive

  1. Sur l'écran d'accueil de la AgentCore CLI, sélectionnez deploy pour appliquer les AWS ressources de suppression et de démolition :

    Progression du déploiement : état de CloudFormation la suppression et du démontage des ressources

La remove all commande réinitialise le fichier de agentcore/agentcore.json configuration tout en préservant l'état agentcore/aws-targets.json de déploiement. Le deploy système détecte ensuite les ressources supprimées et démonte les AWS ressources correspondantes.

Identifiez vos ressources

Après le déploiement, vous pouvez vérifier l'état de vos ressources à l'aide de la AgentCore CLI :

Exemple
AgentCore CLI

  1. agentcore status
Interactive

  1. Exécutez agentcore et sélectionnez status pour afficher un tableau de bord en direct de toutes les ressources déployées :

    agentcore
    AgentCore Tableau de bord de statut CLI TUI

Vous pouvez également consulter vos ressources dans la AWS console :

Ressource Location

Journaux des agents

CloudWatch → Groupes de journaux → /aws/bedrock-agentcore/runtimes/{agent-id}-DEFAULT

CloudFormation Empiler

CloudFormation → Stacks → recherchez le nom de votre projet

IAM Role

IAM → Rôles → Rechercher « » BedrockAgentCore

Ressources S3 (CodeZip)

S3 → Godets → Bac de préparation CDK

Problèmes courants et solutions correspondantes

Problèmes courants et solutions lors de la prise en main de la AgentCore CLI. Pour plus d'informations sur le dépannage, consultez Résoudre les problèmes liés à Amazon Bedrock Runtime AgentCore .

Erreurs d'autorisation refusée

Vérifiez vos AWS informations d'identification et vos autorisations :

  • Vérifiez les AWS informations d'identification : aws sts get-caller-identity

  • Vérifiez que vous avez joint les politiques requises

  • Consultez la politique d'autorisation des appelants pour connaître les exigences détaillées

Accès au modèle refusé

Activez l'accès au modèle dans la console Bedrock :

  • Activez Anthropic Claude 4.0 dans la console Bedrock

  • Assurez-vous que vous vous trouvez dans la bonne AWS région (us-west-2 par défaut)

Erreurs de déploiement du CDK

Vérifiez la configuration et les autorisations du CDK :

  • Assurez-vous d'avoir démarré votre AWS compte pour CDK : cdk bootstrap

  • Vérifiez que les autorisations de votre appelant incluent CloudFormation l'accès au CDK

  • agentcore deploy -vÀ utiliser pour une sortie détaillée afin d'identifier la ressource défaillante

Port 8080 en cours d'utilisation (local uniquement)

Recherchez et arrêtez les processus qui utilisent le port 8080 :

Permet lsof -ti:8080 d'obtenir la liste des processus utilisant le port 8080.

kill -9 PIDÀ utiliser pour arrêter le processus. Remplacez PID par l'ID du processus.

Vous pouvez également démarrer le serveur de développement sur un port différent : agentcore dev -p 3000

Incompatibilité entre les régions

Vérifiez la AWS région auprès de laquelle vos ressources doivent être déployées aws configure get region et assurez-vous qu'elle agentcore/aws-targets.json correspond à celle dans laquelle vos ressources doivent être déployées.

Erreurs de validation de configuration

Validez vos fichiers de configuration :

agentcore validateÀ utiliser pour vérifier l'absence d'erreurs de syntaxe ou de schéma dans agentcore/agentcore.json les fichiers de configuration associés.

Options avancées (facultatif)

Après avoir créé votre projet d'agent avecagentcore create, vous pouvez l'étendre à l'aide des agentcore add commandes. Pour la référence complète de la CLI, consultez la documentation de la AgentCore CLI.

Types de construction

Lors de la création de votre projet, choisissez un type de construction adapté à vos besoins :

CodeZip (default)

Le code de votre agent est empaqueté sous forme d'archive zip et téléchargé sur S3. Il s'agit de l'option la plus simple et ne nécessite pas Docker :

agentcore create --name MyAgent --framework Strands --model-provider Bedrock --memory none --build CodeZip
Conteneur

Le code de votre agent est empaqueté sous forme d'image de conteneur Docker. Utilisez cette option lorsque vous avez besoin de dépendances personnalisées au niveau du système ou d'une image de base spécifique :

agentcore create --name MyAgent --framework Strands --model-provider Bedrock --memory none --build Container

Ajoutez des ressources à votre projet

Vous pouvez ajouter des ressources supplémentaires à votre projet après sa création :

# Add another agent to the same project
agentcore add agent --name SecondAgent --language Python --framework Strands --model-provider Bedrock

# Add a memory store for conversational context
agentcore add memory --name MyMemory --strategies SEMANTIC

# Add an API key credential for external services
agentcore add credential --name MyApiKey --type api-key --api-key your-api-key

# Add a payment manager for x402 microtransactions
agentcore add payment-manager --name MyPayments --auto-payment --default-spend-limit 5.00

Après avoir ajouté des ressources, exécutez agentcore deploy pour provisionner les nouvelles ressources AWS.

Pourquoi ARM64 ?

Amazon Bedrock AgentCore Runtime fonctionne sur ARM64 (AWS Graviton). La AgentCore CLI gère automatiquement la compatibilité de l'architecture pour les types de version CodeZip et de conteneur. Pour les versions de conteneurs, seules les images créées pour ARM64 fonctionneront lorsqu'elles seront déployées sur Amazon Bedrock Runtime AgentCore .