View a markdown version of this page

环境和文件系统 - Amazon Bedrock AgentCore
在环境上运行命令自定义环境（容器镜像）环境变量文件系统

环境和文件系统

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

在环境上运行命令

并非所有内容都需要通过代理循环。 InvokeAgentRuntimeCommand允许你直接使用 shell 访问线束 microVM：确定性命令执行，无需模型推理，没有代币成本，没有歧义。

用它来：

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

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

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

  • 在开发过程中检查 VM：lscat，，env，，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平台构建。

安全带会覆盖您的容器ENTRYPOINT并CMD使其作为环境运行。您安装的软件、文件系统和环境变量可供代理使用；容器的启动命令不会被执行。如果您需要后台进程（例如开发服务器），请在会话开始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。

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

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

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

例
Interactive

在项目目录agentcore中运行以打开 TUI，选择添加，然后选择 H arness 。该向导将引导您完成执行环境，并在高级设置中引导您完成永久文件系统。

  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

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

使用 a --s3-access-point s 连接 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 Runtime 的文件系统配置。

相关主题