View a markdown version of this page

环境和文件系统 - 亚马逊基岩 AgentCore
在环境中运行命令自定义环境（容器镜像）环境变量文件系统

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

环境和文件系统

每个安全带会话都在具有自己的文件系统和外壳的独立微虚拟机中运行。本页介绍配置执行环境（默认或自定义容器）、直接在虚拟机上运行命令、设置环境变量以及安装永久文件系统。

在环境中运行命令

并非所有内容都需要通过代理循环。InvokeAgentRuntimeCommand让您可以直接通过 shell 访问哈萨克斯的 microVM：确定性命令执行，无需模型推理，没有代币成本，没有歧义。

用它来：

  • 运行确定性调用前或调用后脚本。

  • 在调用之前准备环境：克隆存储库、安装依赖关系、复制输入文件。

  • 根据代理生成的内容采取行动：运行测试、提交和推送、提取构建工件。

  • 在开发期间检查虚拟机：lscatenv、、，python --version无需往返模型。

例
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"
注意

基础环境包括 Python 和 bash。对于gitnode、或其他运行时之类的工具，请在会话开始时安装它们（例如apt-get install -y git）或使用自定义环境。

在 TUI 中，按键进入执行模式并!以内联方式运行命令。

有关详细信息，请参阅 InvokeAgentRuntimeCommand API。

注意

命令在 microVM 中以 root 用户 (uid 0) 身份运行。这类似于您自己的 EC2 实例上的 root 权限——IAM 权限是访问门，而不是虚拟机内权限级别。如果您的 Dockerfile 包含USER指令，则它仅适用于代理进程（容器的主入口点）。InvokeAgentRuntimeCommand出于操作目的以更高的权限级别运行，类似于即使容器以非 root 用户身份运行也docker exec默认为 root。有关安全性、错误处理和最佳实践的完整详细信息，请参见在 AgentCore 运行时会话中执行 shell 命令。

自定义环境（容器镜像）

基础环境包括 Python 和 bash，足以完成大多数任务。当你需要更多时，将源代码、依赖关系、运行时和工具打包到容器镜像中，将其推送到 ECR，然后在工具上引用。您的代理在那个确切的环境中运行。将自定义映像与配对InvokeAgentRuntimeCommand以进行会话特定的设置，具体设置因调用而异。

必须为linux/arm64平台构建容器镜像。

该安全带会覆盖您的容器ENTRYPOINTCMD并保持其作为环境运行。您安装的软件、文件系统和环境变量可供代理使用；容器的启动命令不会执行。如果您需要后台进程（例如开发服务器），请在会话开始InvokeAgentRuntimeCommand后通过启动它。

例
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."}]'

执行角色需要 ECR 拉取权限。有关详细信息，请参阅执行角色政策。

AgentCore CLI

用 Dockerfile 搭建安全带：

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

部署时，CLI 生成映像，推送到 ECR，然后将其连接到安全带上。

或者参考预建的镜像：

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

环境变量

设置传递给运行时容器的环境变量。环境变量可供代理和会话中运行的任何自定义容器使用。

例
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

在以下位置设置环境变量harness.json：

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

运行agentcore deploy申请。

文件系统

该安全带将永久存储器安装在您指定的路径上。写入这些挂载的文件在会话终止后仍可生效，以后调用时也可见。

工具支持三种文件系统类型：

  • 会话存储 -由服务管理的每会话存储，可跨 stop/resume 周期持续存储。runtimeSessionId不需要 VPC。

  • Amazon EFS 接入点 -自带 EFS 文件系统，跨会话和代理共享。需要 VPC。

  • 亚马逊 S3 文件接入点 -自带 S3 文件系统，可与 S3 存储桶双向同步。需要 VPC。

有关先决条件（VPC 网络、IAM 权限、安全组）、类型比较、限制和生命周期行为，请参阅 AgentCore 运行时文件系统配置。同样的要求也适用于安全带。

在 AgentCore CLI 中配置环境和文件系统

例
Interactive

在项目目录agentcore中运行以打开 TUI，选择 “添加”，然后选择 Harn es s。该向导将引导您浏览执行环境以及高级设置中的永久文件系统。

  1. 在自定义环境步骤中，保留默认环境或选择预建容器镜像 (ECR URI) 或 Dockerfile。

    添加安全带向导：自定义环境

  2. 文件系统挂载需要 VPC 模式，因此在 “高级” 设置中启用带空间的网络和文件系统存储，然后按 Enter 。

    启用网络和文件系统存储的高级设置

  3. 选择 VPC 网络模式，然后为安全带提供子网和安全组。

    选择 VPC 网络模式

  4. 设置会话存储挂载路径（下方/mnt）。

    输入会话存储挂载路径

  5. 要连接 Amazon EFS 文件系统，请输入 EFS 接入点 ARN（以及下一步中的挂载路径）。

    输入 EFS 接入点 ARN

  6. 要附加 Amazon S3 文件，请输入 S3 文件接入点 ARN（及其挂载路径）。

    输入 S3 文件接入点 ARN

确认向导，然后运行agentcore deploy进行申请。

会话存储

当您使用该文件调用时，写入到挂载路径的文件会跨 stop/resume 周期保存runtimeSessionId。

例
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

亚马逊 EFS 接入点

在下面的安装路径上连接 EFS 接入点 ARN。/mnt数据保存在您的账户中，可以与安装相同接入点的其他安全带或代理运行时共享。

例
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

使用 --efs-access-point as 连接 EFS 接入点<accessPointArn>:<mountPath>。EFS 需要 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
注意

装载路径必须位于下方/mnt。该标志是可重复的（最多 2 个 EFS 挂载）；装载 EFS --subnets 和 --security-groups S3 文件时需要--network-mode VPC使用和标记。

亚马逊 S3 文件接入点

将 S3 文件接入点 ARN 附加到下方的/mnt挂载路径。挂载路径上的文件与后备的 S3 存储桶双向同步。

例
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

使用 --s3-access-point as 连接 S3 文件访问点<accessPointArn>:<mountPath>。S3 文件需要 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
注意

接入点 ARN 本身包含冒号；挂载路径取自最后一个冒号之后的分段。该标志是可重复的（最多 2 个 S3 文件挂载）。

重要

UpdateHarness替换整个filesystemConfigurations列表。要将新挂载添加到已配置文件系统的工具中，请GetHarness先调用，然后发送完整的所需清单（现有条目加上新条目）。UpdateHarness

了解更多： AgentCore 运行时的文件系统配置。

相关主题