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 Runtime en cours d'exécution 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 la même session utilisée parInvokeAgentRuntime. Cela permet des flux de travail dans lesquels votre application utilise l'agent pour des tâches de raisonnement et des commandes pour des opérations déterministes telles que l'exécution de tests, les 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 Runtime active et renvoie la sortie.

Même agent, même session

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

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

Flux de sortie en temps réel. Vous voyez les résultats au fur et à mesure qu'ils s'exécutent, et non une fois qu'ils sont terminés.

Conditions préalables

Exécuter une commande

Exemple de flux de travail avec agent de codage

Un modèle courant est à utiliser pour le raisonnement et InvokeAgentRuntime InvokeAgentRuntimeCommand pour les opérations déterministes au cours d'une 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 sait faire de mieux.

Cas d’utilisation courants

Principaux choix de design

Considérations sur la sécurité

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 avec son propre noyau, sa propre mémoire et 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 des machines virtuelles. Toutefois, au sein de votre machine virtuelle, les commandes ont un accès complet au système de fichiers du conteneur et à tous les identifiants 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 trace 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é vers votre application et n'est pas enregistré par le service.

Audit avec CloudTrail

AWS CloudTrail enregistre les appels d'InvokeAgentRuntimeCommandAPI dans votre compte. Chaque enregistrement inclut des métadonnées telles que l'identité de l'appelant, l'horodatage, l'adresse IP source et le statut de la réponse. CloudTrail n'enregistre pas la charge utile de la demande ou de la réponse. CloudTrail À utiliser pour vérifier qui a exécuté les commandes et à quel moment, puis établir une corrélation avec CloudWatch les journaux à l'aide de 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 :

Gestion des erreurs

Lorsque vous utilisez cette InvokeAgentRuntimeCommand opération, vous pouvez rencontrer les erreurs suivantes :

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

Bonnes pratiques

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