Comment ça marche Conditions préalables Exécuter une commande Exemple de flux de travail d'agent de codage Cas d’utilisation courants Principaux choix de conception Considérations sur la sécurité Gestion des erreurs Bonnes pratiques

Exécuter des commandes shell dans les sessions AgentCore d'exécution

L'InvokeAgentRuntimeCommandopération vous permet d'exécuter des commandes shell directement dans une session AgentCore d'exécution en cours et de retransmettre la sortie HTTP/2. Les commandes s'exécutent dans le même conteneur, le même système de fichiers et le même environnement que votre agent, c'est-à-dire dans la même session que celle utilisée parInvokeAgentRuntime. Cela permet de créer des flux de travail dans lesquels votre application utilise l'agent pour raisonner des tâches et des commandes pour des opérations déterministes telles que l'exécution de tests, des opérations git ou la configuration de l'environnement.

Pour appelerInvokeAgentRuntimeCommand, vous avez besoin d'bedrock-agentcore:InvokeAgentRuntimeCommandautorisations.

Comment ça marche

InvokeAgentRuntimeCommandexécute une commande shell dans le conteneur d'une session AgentCore d'exécution active et renvoie la sortie.

Même agent, même session

InvokeAgentRuntimeCommandfonctionne sur le même environnement d'exécution et la même session d'agent queInvokeAgentRuntime. Vous ne créez pas de ressources distinctes. L'agent avec lequel vous avez déployé CreateAgentRuntime accepte à la fois les appels d'agent et l'exécution de commandes sur toute session active.

Note

Par défaut, AgentCore Runtime MicroVM n'inclut pas d'outils de développement tels que gitnpm, ou de langages d'exécution. Tous les outils dont dépendent vos commandes doivent être inclus dans l'image de votre conteneur (via votre Dockerfile) ou installés dynamiquement lors de l'exécution.

La réponse est un flux de trois types d'événements :

Événement	Lorsque	Contains
`contentStart`	Premier morceau	Confirme que la commande a été lancée
`contentDelta`	Pendant l'exécution	Sortie dans l’`stdout` and/or `stderr`
`contentStop`	Dernier morceau	`exitCode`et `status` (`COMPLETED`ou`TIMED_OUT`)

Flux de sortie en temps réel. Vous voyez les résultats au fur et à mesure qu'ils s'exécutent, pas après la fin.

Conditions préalables

Autorisation IAM bedrock-agentcore:InvokeAgentRuntimeCommand
Un ARN de point de terminaison AgentCore d'exécution valide

Note

Les agents créés après le 17 mars 2026 prennent en charge l'exécution automatique des commandes. Si vous avez déployé votre agent avant cette date, vous devez le redéployer pour mettre à jour le runtime de l'agent.

Exécuter une commande

Exemple

Python

L'exemple suivant montre comment utiliser boto3 pour exécuter une commande dans une session AgentCore d'exécution.


import boto3
import sys

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

response = client.invoke_agent_runtime_command(
    agentRuntimeArn='arn:aws:bedrock-agentcore:us-west-2:account-id:runtime/my-agent',
    runtimeSessionId='session-id-at-least-33-characters-long',
    qualifier='DEFAULT',
    contentType='application/json',
    accept='application/vnd.amazon.eventstream',
    body={
        'command': '/bin/bash -c "npm test"',
        'timeout': 60
    }
)

# Process the streaming response
for event in response.get('stream', []):
    if 'chunk' in event:
        chunk = event['chunk']

        if 'contentStart' in chunk:
            print("Command execution started")

        if 'contentDelta' in chunk:
            delta = chunk['contentDelta']
            if delta.get('stdout'):
                print(delta['stdout'], end='')
            if delta.get('stderr'):
                print(delta['stderr'], end='', file=sys.stderr)

        if 'contentStop' in chunk:
            stop = chunk['contentStop']
            print(f"\nExit code: {stop.get('exitCode')}, Status: {stop.get('status')}")

Java

L'exemple suivant montre comment utiliser le AWS SDK pour Java afin d'exécuter une commande dans une session AgentCore d'exécution.


import software.amazon.awssdk.auth.credentials.DefaultCredentialsProvider;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.bedrockagentcore.BedrockAgentCoreAsyncClient;
import software.amazon.awssdk.services.bedrockagentcore.model.*;
import java.util.UUID;
import java.util.concurrent.CompletableFuture;

public class ExecuteCommandExample {
    public static void main(String[] args) throws Exception {
        String agentArn = "arn:aws:bedrock-agentcore:us-west-2:account-id:runtime/my-agent";
        String sessionId = UUID.randomUUID().toString();

        BedrockAgentCoreAsyncClient client = BedrockAgentCoreAsyncClient.builder()
                .region(Region.US_WEST_2)
                .credentialsProvider(DefaultCredentialsProvider.create())
                .build();

        InvokeAgentRuntimeCommandRequest request = InvokeAgentRuntimeCommandRequest.builder()
                .agentRuntimeArn(agentArn)
                .runtimeSessionId(sessionId)
                .qualifier("DEFAULT")
                .contentType("application/json")
                .accept("application/vnd.amazon.eventstream")
                .body(InvokeAgentRuntimeCommandRequestBody.builder()
                        .command("/bin/bash -c \"npm test\"")
                        .timeout(60)
                        .build())
                .build();

        InvokeAgentRuntimeCommandResponseHandler handler = InvokeAgentRuntimeCommandResponseHandler.builder()
                .subscriber(InvokeAgentRuntimeCommandResponseHandler.Visitor.builder()
                        .onChunk(chunk -> {
                            if (chunk.contentStart() != null) {
                                System.out.println("Command execution started");
                            }
                            if (chunk.contentDelta() != null) {
                                ContentDeltaEvent delta = chunk.contentDelta();
                                if (delta.stdout() != null) System.out.print(delta.stdout());
                                if (delta.stderr() != null) System.err.print(delta.stderr());
                            }
                            if (chunk.contentStop() != null) {
                                ContentStopEvent stop = chunk.contentStop();
                                System.out.println("\nExit code: " + stop.exitCode() +
                                    ", Status: " + stop.statusAsString());
                            }
                        })
                        .build())
                .build();

        CompletableFuture<Void> future = client.invokeAgentRuntimeCommand(request, handler);
        future.get();
        client.close();
    }
}

JavaScript

L'exemple suivant montre comment utiliser le AWS SDK pour la JavaScript version v3 afin d'exécuter une commande dans une session AgentCore d'exécution.


import {
    BedrockAgentCoreClient,
    InvokeAgentRuntimeCommandCommand
} from "@aws-sdk/client-bedrock-agentcore";
import { randomUUID } from "crypto";

const client = new BedrockAgentCoreClient({ region: "us-west-2" });

const request = {
    agentRuntimeArn: "arn:aws:bedrock-agentcore:us-west-2:account-id:runtime/my-agent",
    runtimeSessionId: randomUUID(),
    qualifier: "DEFAULT",
    contentType: "application/json",
    accept: "application/vnd.amazon.eventstream",
    body: {
        command: '/bin/bash -c "npm test"',
        timeout: 60,
    },
};

const command = new InvokeAgentRuntimeCommandCommand(request);
const response = await client.send(command);

// Process the event stream
for await (const event of response.stream) {
    if (event.chunk) {
        const chunk = event.chunk;

        if (chunk.contentStart) {
            console.log("Command execution started");
        }

        if (chunk.contentDelta) {
            if (chunk.contentDelta.stdout) process.stdout.write(chunk.contentDelta.stdout);
            if (chunk.contentDelta.stderr) process.stderr.write(chunk.contentDelta.stderr);
        }

        if (chunk.contentStop) {
            console.log(`\nExit code: ${chunk.contentStop.exitCode}, ` +
                `Status: ${chunk.contentStop.status}`);
        }
    }
}

client.destroy();

Exemple de flux de travail d'agent de codage

Un modèle courant est à utiliser pour le raisonnement et InvokeAgentRuntime InvokeAgentRuntimeCommand pour les opérations déterministes au cours de la même session.

Exemple de flux de travail d'agent de End-to-end codage


import boto3
import json

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

AGENT_ARN = 'arn:aws:bedrock-agentcore:us-west-2:account-id:runtime/my-agent'
SESSION_ID = 'session-id-at-least-33-characters-long'

def run_command(command, timeout=60):
    """Helper to run a command and return the exit code."""
    response = client.invoke_agent_runtime_command(
        agentRuntimeArn=AGENT_ARN,
        runtimeSessionId=SESSION_ID,
        contentType='application/json',
        accept='application/vnd.amazon.eventstream',
        body={'command': command, 'timeout': timeout}
    )
    for event in response.get('stream', []):
        if 'chunk' in event and 'contentStop' in event['chunk']:
            return event['chunk']['contentStop'].get('exitCode')
    return None

# Step 1: Invoke the agent to analyze and write a fix
response = client.invoke_agent_runtime(
    agentRuntimeArn=AGENT_ARN,
    runtimeSessionId=SESSION_ID,
    payload=json.dumps({"prompt": "Read JIRA-1234 and implement the fix in /workspace"}).encode()
)
# Process agent response...

# Step 2: Run tests deterministically
exit_code = run_command('/bin/bash -c "cd /workspace && npm test"', timeout=300)

# Step 3: If tests pass, commit and push
if exit_code == 0:
    run_command('/bin/bash -c "cd /workspace && git checkout -b fix/JIRA-1234"')
    run_command('/bin/bash -c "cd /workspace && git add -A && git commit -m \'Fix JIRA-1234\'"')
    run_command('/bin/bash -c "cd /workspace && git push origin fix/JIRA-1234"')

L'agent écrit le code. La plateforme exécute les commandes. Chacun fait ce qu'il fait de mieux.

Cas d’utilisation courants

Exécution de suites de tests

Une fois que l'agent a écrit le code, exécutez la suite de tests du projet sous forme de commande. La réponse en streaming vous permet de détecter les défaillances à un stade précoce et de renvoyer la sortie d'erreur spécifique à l'agent pour itération.


/bin/bash -c "cd /workspace && npm test 2>&1"

Opérations Git

Brancher, valider et pousser sont des opérations déterministes. Exécutez-les sous forme de commandes une fois que l'agent a terminé son travail, en gardant la logique de contrôle de version hors du LLM.


/bin/bash -c "cd /workspace && git add -A && git commit -m 'Fix issue'"

Installation de dépendances

Démarrez l'environnement avant d'appeler les dépôts agent -clone, installez les packages, configurez les outils de génération. Cette préparation s'exécute plus rapidement et de manière plus fiable sous forme de commandes directes.


/bin/bash -c "pip install -r requirements.txt"

Créez et compilez

Étapes de compilation et génération de ressources : tout ce qui comporte une commande connue qui doit s'exécuter exactement comme spécifié.


/bin/bash -c "cd /workspace && cargo build --release"

Linting et validation

Exécutez des contrôles de qualité du code en tant que porte de validation une fois que l'agent a écrit le code, avant de le valider.


/bin/bash -c "cd /workspace && npx eslint src/ --format json"

Inspection environnementale

Vérifiez l'état d'exécution, les packages installés et les outils disponibles, ce qui est utile pour le débogage des défaillances de l'agent.


/bin/bash -c "python --version && node --version && git --version"

Opérations relatives aux données

Récupérez des ensembles de données, téléchargez des résultats, exécutez des transformations de données, des opérations de réseau et de calcul qui s'exécutent plus rapidement sous forme de commandes directes.


/bin/bash -c "aws s3 cp s3://my-bucket/data.csv /workspace/"

Principaux choix de conception

One-shot, exécution non interactive: Chaque commande génère un nouveau processus bash, s'exécute jusqu'à la fin (ou timeout) et revient. Il n'y a pas de session shell persistante entre les commandes. Cela correspond à la façon dont les frameworks d'agents utilisent l'exécution des commandes : créez une commande, exécutez-la, lisez la sortie, décidez de la marche à suivre.
Réponse en streaming terminée HTTP/2: La sortie arrive au fur et à mesure qu'elle est produite, et n'est mise en mémoire tampon qu'une fois terminée. A npm test qui prend deux minutes, diffuse les résultats en temps réel. Votre application peut détecter une panne dès les premières secondes et annuler prématurément au lieu d'attendre la fin de l'exécution.
Isolation du conteneur: Les commandes s'exécutent dans le même conteneur que le code de votre agent. Ils voient le même système de fichiers, les mêmes variables d'environnement et les mêmes packages installés. Un fichier dans lequel l'agent a écrit /workspace/fix.py est immédiatement visible lors de l'exécution d'une commandecat /workspace/fix.py.
Non-blocking au runtime: L'exécution des commandes ne bloque pas les appels d'agents. Vous pouvez invoquer l'agent et exécuter des commandes simultanément sur la même session. La plateforme gère la simultanéité.
Stateless entre les commandes: Chaque commande redémarre à zéro : aucun historique du shell, aucune modification des variables d'environnement par rapport aux commandes précédentes n'est reportée. Si vous avez besoin d'un état, encodez-le dans la commande elle-même : cd /workspace && export NODE_ENV=test && npm test

Considérations sur la sécurité

Astuce

Pour une vue consolidée de toutes les recommandations de sécurité relatives à Runtime, consultez la section Bonnes pratiques en matière de sécurité pour AgentCore Runtime.

Important

Dans le cadre du modèle de responsabilité AWS partagée, vous êtes responsable de la sécurité des commandes que vous exécutez dans vos sessions AgentCore Runtime. AWS fournit une infrastructure sécurisée et une isolation au niveau de la microVM. Vous êtes responsable des commandes que vous exécutez, des données que vous traitez et des contrôles d'accès que vous configurez.

La limite de sécurité pour l'exécution des commandes est la microVM. Chaque session AgentCore d'exécution s'exécute dans une microVM isolée dotée de son propre noyau, de sa propre mémoire et de son propre système de fichiers. Les commandes que vous exécutez ne peuvent pas accéder aux charges de travail des autres clients ni échapper aux limites de la machine virtuelle. Cependant, au sein de votre machine virtuelle, les commandes ont un accès complet au système de fichiers du conteneur et à toutes les informations d'identification ou secrets que vous avez configurés.

Audit à l'aide de CloudWatch journaux

AgentCore Runtime envoie l'ID de demande et la commande d'entrée au groupe de CloudWatch journaux Amazon Logs de votre agent. Vous pouvez utiliser ces journaux pour surveiller l'activité des commandes et conserver une piste d'audit des commandes exécutées au cours de vos sessions. Le résultat de l'exécution de la commande (stdout et stderr) est renvoyé à votre application et n'est pas enregistré par le service.

Audit avec CloudTrail

AWS CloudTrail enregistre les appels d'InvokeAgentRuntimeCommandAPI sur votre compte. Chaque enregistrement inclut des métadonnées telles que l'identité de l'appelant, l'horodatage, l'adresse IP source et l'état de la réponse. CloudTrail n'enregistre pas la charge utile de la demande ou de la réponse. Utilisez-le CloudTrail pour vérifier qui a exécuté les commandes et quand, puis établissez une corrélation avec CloudWatch les journaux en utilisant l'ID de demande pour voir quelle commande a été exécutée.

Pour les charges de travail sensibles, envisagez de mettre en œuvre des contrôles supplémentaires tels que :

Utiliser les politiques IAM pour restreindre les numéros d'appel que les principaux peuvent appeler InvokeAgentRuntimeCommand
Configuration des points de terminaison VPC pour maintenir le trafic au sein de votre réseau
Configuration CloudWatch des filtres métriques et des alarmes des journaux pour détecter les modèles de commande inattendus
Examiner régulièrement CloudTrail les journaux pour détecter les tentatives d'accès non autorisées

Gestion des erreurs

Lors de l'utilisation de cette InvokeAgentRuntimeCommand opération, vous pouvez rencontrer les erreurs suivantes :

ValidationException: Survient lorsque les paramètres de demande ne sont pas valides. Vérifiez que l'ARN, l'ID de session et la commande de votre agent sont correctement formatés. La commande doit être comprise entre 1 octet et 64 Ko, le délai d'attente doit être compris entre 1 et 3 600 secondes et l'ID de session doit comporter au moins 33 caractères.
ResourceNotFoundException: Se produit lorsque l'exécution ou la session de l'agent spécifiée est introuvable. Vérifiez que l'ARN de l'agent est correct et que la session est active.
AccessDeniedException: Se produit lorsque vous ne disposez pas des autorisations nécessaires. Assurez-vous que votre politique IAM inclut cette bedrock-agentcore:InvokeAgentRuntimeCommand autorisation.
ThrottlingException: Survient lorsque vous dépassez la limite de taux de demande de 25 TPS. Implémentez une logique d'attente exponentielle et de nouvelle tentative dans votre application.
RetryableConflictException: Se produit (HTTP 409) lorsqu'une InvokeAgentRuntimeCommand opération cible une session que le service est en train de provisionner ou de supprimer. Le message estSession operation in progress, please retry. Cette condition est transitoire et peut être réessayée. Réessayez avec un court délai exponentiel au lieu de le traiter comme terminal. Les AWS kits SDK réessayent automatiquement cette exception lorsque les nouvelles tentatives par défaut sont activées. Si vous avez désactivé les nouvelles tentatives ou si vous avez appelé l'API directement sans AWS SDK, réessayez vous-même.

Une commande qui se termine par un code de sortie différent de zéro ne constitue pas une erreur d'API. Vérifiez exitCode l'contentStopévénement pour déterminer si la commande elle-même a réussi. Un status of TIMED_OUT indique que la commande a dépassé le délai d'expiration spécifié.

Bonnes pratiques

Suivez les bonnes pratiques suivantes lors de l'utilisation de l'InvokeAgentRuntimeCommandopération :

InvokeAgentRuntimeCommandÀ utiliser pour les opérations déterministes (tests, git, builds) et InvokeAgentRuntime pour les tâches de raisonnement. N'acheminez pas les opérations déterministes via le LLM.
Incluez tous les outils de développement dont dépendent vos commandes (tels que gitnpm, ou les environnements d'exécution du langage) dans votre image de conteneur via votre Dockerfile.
Vérifiez toujours la présence exitCode de l'contentStopévénement pour déterminer si la commande a réussi.
Définissez des délais d'attente appropriés. Une suite de tests peut nécessiter 5 minutes, alors qu'une suite de tests git push peut n'avoir besoin que de 30 secondes.
Traitez la sortie en continu de manière incrémentielle pour détecter les défaillances à un stade précoce. Vous pouvez annuler une commande de longue durée plutôt que d'attendre qu'elle soit terminée.
Encodez l'état dans la commande elle-même en utilisant le && chaînage (par exemplecd /workspace && export NODE_ENV=test && npm test), car chaque commande lance un nouveau processus bash.
Utilisez des UUID pour les ID de session afin de respecter le minimum de 33 caractères requis (par exemple,). 12345678-1234-1234-1234-123456789012

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Exécution du shell

Coques interactives (terminaux)