View a markdown version of this page

Prise en main - Amazon Bedrock AgentCore
Conditions préalablesPrise en mainDocumentation sur les APIFormat de réponse en streaming

Prise en main

Vous pouvez utiliser le harnais via la AgentCore CLI ou directement avec AWS des SDK tels queboto3. La CLI est le chemin le plus rapide pour la plupart des développeurs ; les SDK sont destinés à une utilisation programmatique à partir de votre propre application.

Conditions préalables

Prise en main

Exemple
AWS CLI/boto3

Créez le harnais avec un nom et un rôle d'exécution :

aws bedrock-agentcore-control create-harness \
  --harness-name "MyHarness" \
  --execution-role-arn "arn:aws:iam::123456789012:role/MyHarnessRole"

Sondage get-harness jusqu'à"status": "READY". Notez le arn dans la réponse.

aws bedrock-agentcore-control get-harness \
  --harness-id "MyHarness-XyZ123"

Invoquez depuis Python. Si vous ne spécifiez aucun modèle, le harnais est défini par défaut sur Anthropic Claude Sonnet 4.6 sur Amazon Bedrock :

import boto3

client = boto3.client("bedrock-agentcore", region_name="us-west-2")

response = client.invoke_harness(
    harnessArn="arn:aws:bedrock-agentcore:us-west-2:123456789012:harness/MyHarness-XyZ123",  # Replace with your harness ARN
    runtimeSessionId="1234abcd-12ab-34cd-56ef-1234567890ab",
    messages=[{
        "role": "user",
        "content": [{"text": "Research three tropical vacation options under $3k."}]
    }],
)

for event in response["stream"]:
    if "contentBlockDelta" in event:
        delta = event["contentBlockDelta"].get("delta", {})
        if "text" in delta:
            print(delta["text"], end="", flush=True)
    elif "runtimeClientError" in event:
        print(f"\nError: {event['runtimeClientError']['message']}")
AgentCore CLI

Installez la AgentCore CLI :

npm install -g @aws/agentcore

Créez un projet de harnais de manière non interactive avec des drapeaux :

agentcore create --name myresearchagent --model-provider bedrock

Déployez et invoquez :

agentcore deploy
agentcore invoke --harness myresearchagent \
  --session-id "$(uuidgen)" \
  "Research three tropical vacation options under $3k, within five hours of NYC."

La réponse est transmise à votre terminal. Réutilisez-les d'--session-idune manière ou d'une autre pour poursuivre la conversation dans le même environnement.

Pour ajouter d'autres harnais à un projet existant, utilisezagentcore add harness. Pour générer un script d'appel Python autonome, ajoutez--with-invoke-script.

Drapeaux utiles :

  • --no-browser(-b) - utilise le terminal TUI au lieu de l'inspecteur du navigateur

  • --logs(-l) - fonctionne en mode non interactif avec des journaux sur stdout

  • --port <port>(-p) - définit le port du serveur de développement (par défaut 8080)

  • --no-traces- désactiver la collecte de traces OTEL locale

Interactive

Installez la AgentCore CLI :

npm install -g @aws/agentcore

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

agentcore create

  1. Entrez le nom de votre projet :

    Assistant de création : entrez le nom du projet

  2. Sélectionnez Harness comme type de projet :

    Assistant de création : sélectionnez le type de projet

  3. Choisissez votre fournisseur modèle :

    Assistant de création : sélectionnez le fournisseur de modèles

  4. Choisissez votre environnement (par défaut, URI du conteneur ou Dockerfile) :

    Assistant de création : sélection de l'environnement

  5. Configuration de la mémoire :

    Assistant de création : configuration de la mémoire

  6. Configurez éventuellement les paramètres avancés (outils, authentification, réseau, cycle de vie, limites, troncature, stockage de session) :

    Assistant de création : paramètres avancés

  7. Vérifiez votre configuration et confirmez :

    Assistant de création : révision et confirmation

Après confirmation, l'assistant échafaude votre projet. Déployez avecagentcore deploy, puis invoquez avecagentcore invoke.

Vérifiez l'état du projet à tout moment avec agentcore status :

AgentCore tableau de bord de statut

  1. Développement local

Si vous souhaitez tester le harnais dans votre environnement local, vous pouvez exécuter le serveur de développement :

agentcore dev

Lorsque vous exécutezagentcore dev, la CLI déploie d'abord vos ressources de harnais AWS, en créant le rôle IAM, le harnais et toute mémoire ou information d'identification configurée dans votre projet :

Progression du déploiement : création CloudFormation de ressources

Une fois le déploiement terminé, il démarre un serveur local et ouvre l'inspecteur d'agents dans votre navigateur, où vous pouvez discuter avec le harnais, inspecter les traces et parcourir les ressources du projet :

Agent inspecteur : discutez avec votre harnais

Développez les paramètres du faisceau pour afficher et remplacer la configuration du faisceau pour la session en cours :

Agent Inspector : paramètres et configuration du harnais

C'est tout ce dont vous avez besoin pour faire fonctionner un harnais. Les sections suivantes couvrent tout ce que vous pouvez configurer.

Note

runtimeSessionIdIl doit comporter au moins 33 caractères. Utilisez un UUID ou un identifiant similaire. Réutilisez le même identifiant de session entre les invocations pour poursuivre une conversation dans le même environnement.

Documentation sur les API

Pour plus de détails, consultez la référence de l'API :

Format de réponse en streaming

InvokeHarnessrenvoie un flux d'événements. Les principaux types d'événements sont les suivants :

  • messageStart- début d'un nouveau message (inclusrole)

  • contentBlockStart- début d'un bloc de contenu (textetoolUse, outoolResult)

  • contentBlockDelta- contenu incrémentiel (text, toolUse entrée,reasoningContent)

  • contentBlockStop- fin d'un bloc de contenu

  • messageStop- fin du message (inclutstopReason)

  • metadata- mesures d'utilisation des jetons et de latence

  • runtimeClientError- erreur lors de l'exécution

Le stopReason in messageStop indique pourquoi l'agent s'est arrêté :

  • end_turn- l'agent a terminé normalement

  • tool_use- l'agent appelle une fonction en ligne et attend un résultat côté client

  • max_tokens- la limite de jetons par tour du modèle a été atteinte

  • max_iterations_exceeded- la maxIterations limite a été atteinte

  • timeout_exceeded- la timeoutSeconds limite a été atteinte

  • max_output_tokens_exceeded- le maxTokens budget était épuisé