Démarrez avec l' AgentCore interface de ligne de commande

Ce démarrage rapide vous permet de passer de zéro à un agent actif en quelques minutes à l'aide de l' AgentCore interface de ligne de commande. Vous allez installer la CLI, échafauder un projet, tester localement, déployer sur votre agent AWS et l'invoquer.

Deux méthodes permettent de créer un agent sur la même interface AgentCore de ligne de commande :

• Harnais géré. Vous déclarez l'agent dans un fichier de configuration (modèle, invite, outils, mémoire) et AgentCore vous exécutez la boucle pour vous. Pas de framework, pas de code d'orchestration. Bon chemin lorsque vous voulez le chemin le plus rapide entre une idée et un agent de course. En savoir plus.

• Code-based agent. Vous écrivez la boucle d'agent en Python à l'aide d'un framework que vous connaissez déjà (Strands LangGraph, Google ADK ou OpenAI Agents), puis vous la déployez sur Runtime. AgentCore Contrôle total de la logique d'orchestration.

Cette page décrit le flux basé sur le code. Pour le harnais, voir Qu'est-ce que le AgentCore harnais  ?

Inscrivez-vous pour un AWS compte

Inscrivez-vous pour un AWS compte

Pour commencer AWS, vous avez besoin d'un AWS compte. Pour plus d'informations sur la création d'un AWS compte, consultez la section Démarrage avec un AWS compte dans le Guide de référence sur la gestion des AWS comptes.

Conditions préalables

• Node.js 20 ou version ultérieure. La AgentCore CLI est distribuée sous forme de package npm. Vérifiez auprès denode --version. Installez depuis https://nodejs.org nodejs.org si nécessaire.

• npm. Inclus avec Node.js.

• Un AWS compte avec des informations d'identification configurées. Configurez via l' AWS interface de ligne de commande, des variables d'environnement ou un AWS profil. Consultez la section Configuration de la AWS CLI.

• Python 3.10 ou version ultérieure (pour le code de l'agent). Vérifiez auprès depython3 --version.

• Autorisations IAM. Votre identité a besoin d'autorisations pour effectuer des appels d' AgentCore API et assumer les rôles d'amorçage CDK utilisés lors du déploiement. Consultez la section Utiliser l' AgentCore interface de ligne de commande.

• Accès au modèle. Amazon Bedrock permet d'accéder aux modèles de base par défaut. Les modèles disponibles incluent les modèles Amazon Nova, Anthropic Claude, Meta Llama et Mistral AI. Pour utiliser des modèles autres que ceux de base, suivez les étapes d'accès au modèle.

• Docker. Obligatoire uniquement si vous choisissez le type de Container construction. Le type de CodeZip build par défaut ne nécessite pas Docker.

Étape 1 : Installation de la AgentCore CLI

npm install -g @aws/agentcore

Vérifier:

agentcore --version

Note

Si cela signale une erreur au lieu d'un numéro de version, une ancienne agentcore commande Python masque celle de npm sur votre. PATH Cela se produit si vous avez déjà installé le package bedrock-agentcore-starter-toolkit pip, et c'est le plus courant sous Windows. Exécutezpip uninstall bedrock-agentcore-starter-toolkit, puis ouvrez un nouveau terminal et réessayez.

Pour effectuer une mise à jour ultérieure, réexécutez la commande d'installation ouagentcore update. Source et problèmes : agentcore-cli on. GitHub

Étape 2 : Créez votre projet

agentcore create

L'assistant interactif vous demande d'abord ce que vous souhaitez créer :

• Harness  : boucle d'agent gérée basée sur la configuration. Aucun framework ou code d'orchestration n'est requis. Voir Qu'est-ce que le AgentCore harnais.

• Agent  : agent basé sur du code utilisant le framework de votre choix, déployé sur Runtime. AgentCore

• Ignorer  : créez la structure du projet sans agent. Ajoutez-en un plus tard avecagentcore add.

Si vous choisissez Agent, l'assistant continue avec :

• Framework  : Strands Agents (recommandé) LangChain/LangGraph, kit de développement Google Agent ou SDK OpenAI Agents

• Fournisseur de modèles  : Amazon Bedrock, Anthropic, OpenAI ou Gemini

• Mémoire  : aucune, à court terme uniquement, ou à long terme et à court terme

• Type de build - CodeZip (par défaut) ou conteneur

Vous pouvez également transmettre des indicateurs directement pour créer un agent basé sur du code :

agentcore create \
  --project-name MyProject \
  --name MyAgent \
  --language Python \
  --framework Strands \
  --model-provider Bedrock \
  --memory none \
  --build CodeZip

Pour toutes les commandes et options disponibles, consultez la référence AgentCore CLI.

Types de construction

• CodeZip(par défaut) regroupe votre code dans un fichier zip et le télécharge sur Amazon S3. Ce type de build ne nécessite pas Docker.

• Containercrée et déploie une image de conteneur. Ce type de build nécessite un démon Docker en cours d'exécution.

Structure du projet

agentcore creategénère une configuration de projet partagée et une structure d'application différente pour les agents et les harnais basés sur du code :

Exemple

Code-based agent

MyProject/
├── AGENTS.md
├── README.md
├── agentcore/
│   ├── agentcore.json
│   ├── aws-targets.json
│   └── cdk/
└── app/
    └── MyAgent/
        ├── main.py
        ├── pyproject.toml
        ├── README.md
        ├── model/
        ├── mcp_client/
        └── skills/

Harness

MyHarnessProject/
├── AGENTS.md
├── README.md
├── agentcore/
│   ├── agentcore.json
│   ├── aws-targets.json
│   └── cdk/
└── app/
    └── MyHarness/
        ├── harness.json
        └── system-prompt.md

Fichiers clés :

• agentcore/agentcore.json- Le fichier de configuration principal. Il définit vos agents, vos harnais, vos mémoires, vos passerelles, vos informations d'identification et d'autres ressources. Les agentcore remove commandes agentcore add et gèrent ce fichier.

• agentcore/aws-targets.json- Les AWS comptes et les régions à déployer.

• agentcore/.env.local- Les secrets locaux, tels que les clés d'API pour les fournisseurs de modèles.

• app/- Le répertoire de l'application. Un agent basé sur du code contient un point d'entrée et des dépendances. Un harnais contient harness.json etsystem-prompt.md.

Étape 3 : Testez localement

cd MyProject
agentcore dev

agentcore devcrée un environnement virtuel Python, installe des dépendances, démarre un serveur local avec rechargement à chaud et ouvre l'inspecteur d'agent dans votre navigateur pour que vous puissiez discuter avec l'agent, inspecter les traces et parcourir les ressources du projet. Les modifications de code sont automatiquement prises en compte.

Étape 4 : Déployez votre agent

agentcore deploy

Déploiement :

1. Empaquette votre code dans un artefact zip (ou crée un conteneur si--build Container)

2. Utilise AWS CDK sous le capot pour synthétiser et approvisionner les ressources

3. Crée un point de terminaison AgentCore d'exécution pour votre agent

4. Configure la CloudWatch journalisation et l'observabilité

Le premier déploiement prend quelques minutes pendant que CDK démarre votre compte. Les déploiements suivants sont plus rapides.

Prévisualisez ce qui va changer sans déployer :

agentcore deploy --dry-run

État de la vérification :

agentcore status

Étape 5 : Invoquez votre agent déployé

agentcore invoke --prompt "Hello, what can you do?"

Si les paiements sont configurés pour votre agent, fournissez le contexte des paiements au moment de l'appel :

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

C'est la boucle. Effectuez une itérationapp/MyAgent/main.py, testez avecagentcore dev, déployez avecagentcore deploy, invoquez avec. agentcore invoke

Invoquer un agent par programmation

Vous pouvez invoquer l'agent déployé à l'aide de l' AWS opération SDK. InvokeAgentRuntime Obtenez l'ARN d'exécution de l'agent :

agentcore status

Créez un fichier nommé invoke_agent.py. Remplacez Agent ARN par l'ARN de votre agent :

import json
import uuid

import boto3

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

client = boto3.client("bedrock-agentcore")
response = client.invoke_agent_runtime(
    agentRuntimeArn=agent_arn,
    runtimeSessionId=str(uuid.uuid4()),
    payload=json.dumps({"prompt": prompt}).encode(),
    qualifier="DEFAULT",
)

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

print(json.loads("".join(content)))

Exécutez le code :

python invoke_agent.py

Votre identité doit faire l'objet d'bedrock-agentcore:InvokeAgentRuntimeune autorisation.

Note

Pour un agent qui utilise OAuth, envoyez une requête HTTPS au InvokeAgentRuntime lieu d'utiliser le AWS SDK. Pour plus d'informations, voir Authentification et autorisation à l'aide d'autorisations entrantes et sortantes.

Ajoutez des fonctionnalités à votre projet

agentcore addgère les ressources dansagentcore.json. Exécutez-le sans arguments pour le menu interactif, ou ciblez directement une ressource.

agentcore add memory        # Store conversation context
agentcore add agent         # Add a second agent to the same project
agentcore add gateway       # Connect external APIs/tools through Gateway
agentcore add credential    # Add an API key for a non-Bedrock provider
agentcore add evaluator     # Quality evaluation
agentcore add payment-manager   # Payments: create a payment manager
agentcore add payment-connector # Payments: link a payment provider

Chaque commande d'ajout définit la configuration et demande les valeurs requises. Après l'ajout, passez agentcore deploy à la configuration.

Des plongées approfondies pour découvrir les fonctionnalités que vous pouvez associer :

• AgentCore Mémoire - mémoire à court et à long terme, stratégies de récupération

• AgentCore Passerelle  : connectivité gérée vers les API et les serveurs MCP

• AgentCore Navigateur  : navigation Web gérée pour les agents

• AgentCore Interpréteur de code  : exécution de code en mode sandbox

• AgentCore Identité  : OAuth, fournisseurs d'informations d'identification clés d'API, identité de la charge de travail

• AgentCore Observabilité  : traces, journaux et métriques dans CloudWatch

• AgentCore VPC  : exécutez des agents dans votre VPC

• AgentCore Paiements  : paiements par microtransaction pour les agents via x402

Afficher les journaux et les traces

# Stream recent logs
agentcore logs

# Filter
agentcore logs --since 30m --level error
agentcore logs --query "timeout"

# List recent traces
agentcore traces list

# Get a specific trace
agentcore traces get <trace-id>

Dépannage

Erreurs d'autorisation refusée

Vérifiez vos informations d'identification avecaws sts get-caller-identity. Assurez-vous que votre identité dispose des autorisations requises dans Utiliser l' AgentCore interface de ligne de commande.

Accès au modèle refusé

Amazon Bedrock permet d'accéder aux modèles de base par défaut. Pour utiliser un modèle non fondamental, suivez les étapes d'accès au modèle.

Erreurs de déploiement

Exécutez agentcore deploy --verbose pour afficher les événements de déploiement au niveau des ressources. La CLI vérifie l'état du bootstrap du AWS CDK. Si le bootstrap est requis, le déploiement interactif demande une confirmation. agentcore deploy --yesapprouve l'opération d'amorçage sans invite.

Port déjà utilisé

Exécutez agentcore dev --port 3000 pour utiliser un autre port local.

Erreurs de validation de configuration

Exécutez agentcore validate pour vérifier la configuration du projet.

Pour plus d'informations, consultez Résoudre les problèmes liés à Amazon Bedrock Runtime AgentCore .

Nettoyage

agentcore remove all
agentcore deploy

remove allréinitialise la configuration. Le suivi deploy détecte l'état vide et décompose les ressources de votre compte.

Étapes suivantes

• Qu'est-ce que le AgentCore harnais ? Le chemin basé sur la configuration vers un agent en cours d'exécution. Utilisez n'importe quel modèle, connectez-vous à des outils, conservez l'état, déployez-le dans votre VPC et passez au code quand vous en avez besoin.

• AgentCore exemples de code  : exemples de bout en bout couvrant différents frameworks et fonctionnalités.