View a markdown version of this page

環境和檔案系統 - Amazon Bedrock AgentCore
在環境中執行命令自訂環境 （容器映像）環境變數檔案系統

環境和檔案系統

每個繫帶工作階段都會在具有自己的檔案系統和 shell 的隔離microVM中執行。此頁面涵蓋設定執行環境 （預設或自訂容器）、直接在 VM 上執行命令、設定環境變數，以及掛載持久性檔案系統。

在環境中執行命令

並非所有項目都需要經過代理程式迴圈。 InvokeAgentRuntimeCommand可讓您直接透過 shell 存取工具組 microVM：沒有模型推理的確定性命令執行、沒有字符成本、沒有模棱兩可之處。

用它來：

  • 執行決定性叫用前或叫用後指令碼。

  • 在調用之前準備環境：複製儲存庫、安裝相依性、複製輸入檔案。

  • 對代理程式產生的內容採取行動：執行測試、遞交和推送、擷取建置成品。

  • 在開發期間檢查 VM：ls、cat、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。對於 git、 node或其他執行時間等工具，請在工作階段開始時安裝它們 （例如 apt-get install -y git) 或使用自訂環境。

在 TUI 中，按 ! 進入 exec 模式並內嵌執行命令。

如需詳細資訊，請參閱 InvokeAgentRuntimeCommand API。

注意

命令在 microVM 中以根 (uid 0) 執行。這類似於您自己的 EC2 執行個體上的根 - IAM 許可是存取閘道，而不是 VM 內權限層級。如果您的 Dockerfile 包含USER指令，它僅適用於代理程式程序 （容器的主要進入點）。 會基於操作目的在更高的權限層級InvokeAgentRuntimeCommand執行，類似於容器以非根使用者身分執行時docker exec預設為根。如需安全性、錯誤處理和最佳實務的完整詳細資訊，請參閱 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以套用。

檔案系統

繫帶會將持久性儲存掛載在您指定的路徑。寫入這些掛載的檔案在工作階段終止後仍然有效，並且可供稍後的調用使用。

繫帶支援三種檔案系統類型：

  • 工作階段儲存 - 在相同 的停止/繼續週期中持續存在的服務受管、每個工作階段儲存runtimeSessionId。不需要 VPC。

  • Amazon EFS 存取點 - bring-your-own EFS 檔案系統，跨工作階段和客服人員共用。需要 VPC。

  • Amazon S3 檔案存取點 - bring-your-own的 S3 檔案系統，可與 S3 儲存貯體雙向同步。需要 VPC。

如需先決條件 (VPC 聯網、IAM 許可、安全群組）、類型比較、限制和生命週期行為，請參閱 AgentCore 執行期的檔案系統組態。相同的要求適用於 繫帶。

在 AgentCore CLI 中設定環境和檔案系統

範例
Interactive

agentcore 在專案目錄中執行以開啟 TUI，選取新增 ，然後選擇繫結 。精靈會逐步引導您完成執行環境，並在進階設定 中引導持久性檔案系統。

  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以套用。

工作階段儲存

當您使用相同的 叫用 時，寫入掛載路徑的檔案會跨停止/繼續週期保留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

Amazon 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連接 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和 S3 檔案掛載--security-groups需要 --network-mode VPC 和 EFS 。

Amazon 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連接 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 執行期的檔案系統組態。

相關主題