View a markdown version of this page

Entorno y sistema de archivos - Base amazónica AgentCore
Ejecuta comandos en el entornoEntorno personalizado (imágenes de contenedor)Variables de entornoSistema de archivos

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Entorno y sistema de archivos

Cada sesión de arnés se ejecuta en una microVM aislada con su propio sistema de archivos y shell. En esta página se describe la configuración del entorno de ejecución (contenedor predeterminado o personalizado), la ejecución de comandos directamente en la máquina virtual, la configuración de las variables de entorno y el montaje de sistemas de archivos persistentes.

Ejecuta comandos en el entorno

No es necesario que todo pase por el ciclo de agentes. InvokeAgentRuntimeCommandle brinda acceso directo desde el shell a la microVM del arnés: ejecución determinista de comandos sin razonamiento basado en modelos, sin coste de fichas y sin ambigüedad.

Utilízala para:

  • Ejecute scripts deterministas previos o posteriores a la invocación.

  • Prepara el entorno antes de la invocación: clona un repositorio, instala dependencias, copia los archivos de entrada.

  • Actúe en función de lo que ha producido el agente: ejecute pruebas, confirme e inserte, extraiga los artefactos de compilación.

  • Inspeccione la máquina virtual durante el desarrollo:ls,cat,env, python --version sin hacer un recorrido de ida y vuelta por el modelo.

ejemplo
AWS CLI/boto3
response = client.invoke_agent_runtime_command(
    agentRuntimeArn=HARNESS_ARN,
    runtimeSessionId=SESSION_ID,
    body={"command": "ls -la /workspace"},
)

for event in response["stream"]:
    chunk = event.get("chunk", {})
    if "contentDelta" in chunk:
        delta = chunk["contentDelta"]
        if "stdout" in delta:
            print(delta["stdout"], end="", flush=True)
        if "stderr" in delta:
            print(delta["stderr"], end="", flush=True)
    elif "contentStop" in chunk:
        print(f"\n[exit code: {chunk['contentStop']['exitCode']}]")
AgentCore CLI
# Install dependencies before the agent starts
agentcore invoke --exec --harness my-agent --session-id "$(uuidgen)" \
  "pip install pandas matplotlib"

# After the agent finishes, inspect what it created
agentcore invoke --exec --harness my-agent --session-id "$(uuidgen)" \
  "ls -la /tmp && cat /tmp/results.csv"
nota

El entorno base incluye Python y bash. gitEn node el caso de herramientas similares u otros tiempos de ejecución, instálalas al inicio de la sesión (por ejemploapt-get install -y git) o usa un entorno personalizado.

En la TUI, pulse ! para entrar en el modo ejecutivo y ejecutar los comandos en línea.

Consulta la InvokeAgentRuntimeCommand API para obtener más información.

nota

Los comandos se ejecutan como root (uid 0) en la microVM. Esto es similar a lo que ocurre con el usuario root en su propia instancia de EC2: el permiso de IAM es la puerta de acceso, no el nivel de privilegio de la máquina virtual. Si su Dockerfile incluye una USER directiva, se aplica únicamente al proceso del agente (el punto de entrada principal del contenedor). InvokeAgentRuntimeCommandse ejecuta con un nivel de privilegios más alto para fines operativos, similar al modo docker exec predeterminado en root, incluso cuando el contenedor se ejecuta como usuario no root. Consulte Ejecutar comandos de shell en las sesiones AgentCore de ejecución para obtener más información sobre la seguridad, la gestión de errores y las prácticas recomendadas.

Entorno personalizado (imágenes de contenedor)

El entorno base incluye Python y bash, suficientes para la mayoría de las tareas. Cuando necesites más, empaqueta el código fuente, las dependencias, los tiempos de ejecución y las herramientas en una imagen de contenedor, envíala a ECR y haz referencia a ella en el arnés. Tu agente se ejecuta en ese entorno exacto. Combine imágenes personalizadas con una configuración específica InvokeAgentRuntimeCommand para cada sesión, que varía según la invocación.

Las imágenes de contenedor deben crearse para la plataforma. linux/arm64

El arnés prevalece sobre el de su contenedor ENTRYPOINT y CMD lo mantiene funcionando como un entorno. El software, el sistema de archivos y las variables de entorno instalados están disponibles para el agente; el comando de inicio del contenedor no se ejecuta. Si necesita un proceso en segundo plano (como un servidor de desarrollo), inícielo InvokeAgentRuntimeCommand después de que comience la sesión.

ejemplo
AWS CLI/boto3
aws bedrock-agentcore-control create-harness \
  --harness-name "CodingAgent" \
  --execution-role-arn "arn:aws:iam::123456789012:role/MyHarnessRole" \
  --environment-artifact '{"containerConfiguration": {"containerUri": "123456789012.dkr.ecr.us-west-2.amazonaws.com/my-dev-env:latest"}}' \
  --system-prompt '[{"text": "You are an expert TypeScript developer."}]'

La función de ejecución necesita permisos de extracción de ECR. Consulte la política de funciones de ejecución para obtener más información.

AgentCore CLI

Organice un arnés con un Dockerfile:

agentcore create --name coding-agent --container ./Dockerfile
agentcore deploy

En el momento de la implementación, la CLI crea la imagen, la envía al ECR y la conecta al arnés.

O haga referencia a una imagen prediseñada:

agentcore create --name node-agent \
  --container public.ecr.aws/docker/library/node:slim
agentcore deploy

Variables de entorno

Configure las variables de entorno que se pasan al contenedor de tiempo de ejecución. Las variables de entorno están disponibles para el agente y para cualquier contenedor personalizado que se ejecute en la sesión.

ejemplo
AWS CLI/boto3
aws bedrock-agentcore-control create-harness \
  --harness-name "MyHarness" \
  --execution-role-arn "arn:aws:iam::123456789012:role/MyHarnessRole" \
  --environment-variables '{"MY_API_URL": "https://api.example.com", "LOG_LEVEL": "debug"}'
AgentCore CLI

Establezca las variables de entorno enharness.json:

{
  "environmentVariables": {
    "MY_API_URL": "https://api.example.com",
    "LOG_LEVEL": "debug"
  }
}

Ejecute agentcore deploy para aplicar.

Sistema de archivos

El arnés monta el almacenamiento persistente en las rutas que especifique. Los archivos escritos en estos montajes sobreviven a la finalización de la sesión y son visibles para las invocaciones posteriores.

Un arnés admite tres tipos de sistemas de archivos:

  • Almacenamiento de sesión: almacenamiento por sesión administrado por servicios que se mantiene durante varios stop/resume ciclos durante la misma sesión. runtimeSessionId No se requiere una VPC.

  • Punto de acceso Amazon EFS: traiga su propio sistema de archivos EFS, compartido entre sesiones y agentes. Se requiere una VPC.

  • Punto de acceso a Amazon S3 Files: trae tu propio sistema de archivos S3 Files que se sincroniza bidireccionalmente con un bucket de S3. Se requiere una VPC.

Para conocer los requisitos previos (redes de VPC, permisos de IAM, grupos de seguridad), la comparación de tipos, los límites y el comportamiento del ciclo de vida, consulte Configuraciones del sistema de archivos para Runtime. AgentCore Los mismos requisitos se aplican a los arneses.

Configure el entorno y el sistema de archivos en la CLI AgentCore

ejemplo
Interactive

Ejecute agentcore en el directorio de un proyecto para abrir la TUI, seleccione agregar y, a continuación, elija Harness. El asistente le guiará por el entorno de ejecución y, en la configuración avanzada, por el sistema de archivos persistente.

  1. En el paso Entorno personalizado, mantenga el entorno predeterminado o elija una imagen de contenedor prediseñada (URI ECR) o un Dockerfile.

    Asistente para agregar Harness: entorno personalizado

  2. Los montajes de sistemas de archivos requieren el modo VPC, por lo que en la configuración avanzada habilita tanto el almacenamiento en red como en el sistema de archivos con espacio y, a continuación, pulsa Entrar.

    Configuración avanzada con el almacenamiento en red y en sistema de archivos activado

  3. Elija el modo de red VPC y, a continuación, proporcione las subredes y los grupos de seguridad para el arnés.

    Selecciona el modo de red de VPC

  4. Establezca la ruta de montaje del almacenamiento de la sesión (en/mnt).

    Introduzca la ruta de montaje del almacenamiento de la sesión

  5. Para adjuntar un sistema de archivos de Amazon EFS, introduzca el ARN del punto de acceso EFS (y su ruta de montaje en el siguiente paso).

    Introduzca el ARN del punto de acceso EFS

  6. Para adjuntar archivos de Amazon S3, introduzca el ARN del punto de acceso a los archivos S3 (y su ruta de montaje).

    Introduzca el ARN del punto de acceso a los archivos S3

Confirme el asistente y, a continuación, ejecútelo agentcore deploy para solicitarlo.

Almacenamiento de sesiones

Los archivos escritos en la ruta de montaje persisten durante varios stop/resume ciclos cuando se invoca con la misma runtimeSessionId ruta.

ejemplo
AWS CLI/boto3
aws bedrock-agentcore-control update-harness \
  --harness-id "MyHarness-UuFdkQoXSL" \
  --environment '{"agentCoreRuntimeEnvironment": {"filesystemConfigurations": [{"sessionStorage": {"mountPath": "/mnt/data/"}}]}}'
AgentCore CLI
# At create time
agentcore create --name myagent --session-storage-mount-path /mnt/data/

# Or add to an existing harness
agentcore add harness --name my-agent --session-storage /mnt/data/
agentcore deploy

Punto de acceso de Amazon EFS

Adjunte un ARN de punto de acceso EFS a una ruta de montaje situada debajo/mnt. Los datos permanecen en su cuenta y se pueden compartir con otros arneses o equipos de ejecución de agentes que monten el mismo punto de acceso.

ejemplo
AWS CLI/boto3
aws bedrock-agentcore-control create-harness \
  --harness-name "SharedToolsAgent" \
  --execution-role-arn "arn:aws:iam::123456789012:role/MyHarnessRole" \
  --environment '{
    "agentCoreRuntimeEnvironment": {
      "networkConfiguration": {
        "networkMode": "VPC",
        "networkModeConfig": {
          "subnets": ["subnet-abc123", "subnet-def456"],
          "securityGroups": ["sg-abc123"]
        }
      },
      "filesystemConfigurations": [
        {
          "efsAccessPoint": {
            "accessPointArn": "arn:aws:elasticfilesystem:us-west-2:123456789012:access-point/fsap-0123456789abcdef0",
            "mountPath": "/mnt/efs"
          }
        }
      ]
    }
  }'
AgentCore CLI

Adjunte un punto de acceso EFS con --efs-access-point as. <accessPointArn>:<mountPath> EFS requiere el modo de red VPC:

agentcore add harness --name shared-tools-agent \
  --network-mode VPC \
  --subnets subnet-abc123,subnet-def456 \
  --security-groups sg-abc123 \
  --efs-access-point arn:aws:elasticfilesystem:us-west-2:123456789012:access-point/fsap-0123456789abcdef0:/mnt/efs
agentcore deploy
nota

La ruta de montaje debe estar en. /mnt La marca es repetible (hasta 2 montajes EFS); --network-mode VPC --security-groups es necesaria para los montajes de archivos EFS y S3. --subnets

Punto de acceso a Amazon S3 Files

Adjunte un ARN del punto de acceso a S3 Files a una ruta de montaje situada debajo/mnt. Los archivos que se encuentran en la ruta de montaje se sincronizan bidireccionalmente con el depósito S3 posterior.

ejemplo
AWS CLI/boto3
aws bedrock-agentcore-control create-harness \
  --harness-name "DataAgent" \
  --execution-role-arn "arn:aws:iam::123456789012:role/MyHarnessRole" \
  --environment '{
    "agentCoreRuntimeEnvironment": {
      "networkConfiguration": {
        "networkMode": "VPC",
        "networkModeConfig": {
          "subnets": ["subnet-abc123", "subnet-def456"],
          "securityGroups": ["sg-abc123"]
        }
      },
      "filesystemConfigurations": [
        {
          "s3FilesAccessPoint": {
            "accessPointArn": "arn:aws:s3files:us-west-2:123456789012:file-system/fs-0123456789abcdef0/access-point/fsap-0123456789abcdef0",
            "mountPath": "/mnt/s3data"
          }
        }
      ]
    }
  }'
AgentCore CLI

Adjunte un punto de acceso a S3 Files con as--s3-access-point. <accessPointArn>:<mountPath> S3 Files requiere el modo de red VPC:

agentcore add harness --name data-agent \
  --network-mode VPC \
  --subnets subnet-abc123,subnet-def456 \
  --security-groups sg-abc123 \
  --s3-access-point arn:aws:s3files:us-west-2:123456789012:file-system/fs-0123456789abcdef0/access-point/fsap-0123456789abcdef0:/mnt/s3data
agentcore deploy
nota

El ARN del punto de acceso en sí contiene dos puntos; la ruta de montaje se toma del segmento situado después de los dos puntos finales. El indicador se puede repetir (se montan hasta 2 archivos S3).

importante

UpdateHarnessreemplaza la lista completafilesystemConfigurations. Para añadir un nuevo soporte a un arnés que ya tiene configurados los sistemas de archivos, llame GetHarness primero y, a continuación, envíe la lista completa deseada (las entradas existentes y la nueva). UpdateHarness

Más información: Configuraciones del sistema de archivos para AgentCore Runtime.

Temas relacionados