View a markdown version of this page

Prise en main - Base rocheuse de l'Amazonie AgentCore
Conditions préalablesPrise en mainDocumentation sur les APIFormat de réponse en streaming

Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

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

  • AWS informations d'identification configurées dans l'une des régions prises en charge.

  • Pour la CLI : Node.js 20+

  • Pour SDK/boto3 : Python 3.10+, boto3 installé, et un rôle d'exécution IAM que le harnais peut assumer. Consultez la politique relative aux rôles d'exécution pour connaître les autorisations minimales.

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'au"status": "READY". Notez le arn dans la réponse.

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

Invoquer depuis Python. Si vous ne spécifiez pas de 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 indicateurs :

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-le --session-id dans toutes les invocations 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) - utilisez 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 (8080 par défaut)

  • --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 indicateur 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 de modèles :

    Assistant de création : sélection du fournisseur de modèles

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

    Assistant de création : sélectionnez 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 : vérifiez et confirmez

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, créant le rôle IAM, le harnais et toute mémoire ou informations d'identification configurées 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 des agents dans votre navigateur, où vous pouvez discuter avec le harnais, inspecter les traces et parcourir les ressources du projet :

Inspecteur des agents : discutez avec votre harnais

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

Inspecteur d'agents : paramètres et configuration du harnais

C'est tout ce dont tu as 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 dans toutes 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 (inclutrole)

  • 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 signe « 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é