本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 环境和文件系统
每个安全带会话都在具有自己的文件系统和外壳的独立微虚拟机中运行。本页介绍配置执行环境（默认或自定义容器）、直接在虚拟机上运行命令、设置环境变量以及安装永久文件系统。
## 在环境中运行命令
并非所有内容都需要通过代理循环。`InvokeAgentRuntimeCommand`让您可以直接通过 shell 访问哈萨克斯的 microVM：确定性命令执行，无需模型推理，没有代币成本，没有歧义。
用它来：
+ 运行确定性调用前或调用后脚本。
+ 在调用之前准备环境：克隆存储库、安装依赖关系、复制输入文件。
+ 根据代理生成的内容采取行动：运行测试、提交和推送、提取构建工件。
+ 在开发期间检查虚拟机：`ls``cat``env`、、，`python --version`无需往返模型。
**Example**
```
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']}]")
```
```
# 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`）或使用[自定义环境](#harness-custom-container)。
在 TUI 中，按键进入执行模式并`!`以内联方式运行命令。
有关详细信息[，请参阅 ](https://docs.amazonaws.cn/bedrock-agentcore/latest/APIReference/API_InvokeAgentRuntimeCommand.html) InvokeAgentRuntimeCommand API。
**注意**
命令在 microVM 中以 root 用户 (uid 0) 身份运行。这类似于您自己的 EC2 实例上的 root 权限——IAM 权限是访问门，而不是虚拟机内权限级别。如果您的 Dockerfile 包含`USER`指令，则它仅适用于代理进程（容器的主入口点）。`InvokeAgentRuntimeCommand`出于操作目的以更高的权限级别运行，类似于即使容器以非 root 用户身份运行也`docker exec`默认为 root。有关安全性、错误处理和最佳实践[的完整详细信息，请参见在 AgentCore 运行时会话中](https://docs.amazonaws.cn/bedrock-agentcore/latest/devguide/runtime-execute-command.html)执行 shell 命令。
## 自定义环境（容器镜像）
基础环境包括 Python 和 bash，足以完成大多数任务。当你需要更多时，将源代码、依赖关系、运行时和工具打包到容器镜像中，将其推送到 ECR，然后在工具上引用。您的代理在那个确切的环境中运行。将自定义映像与配对`InvokeAgentRuntimeCommand`以进行会话特定的设置，具体设置因调用而异。
必须为`linux/arm64`平台构建容器镜像。
该安全带会覆盖您的容器`ENTRYPOINT``CMD`并保持其作为环境运行。您安装的软件、文件系统和环境变量可供代理使用；容器的启动命令不会执行。如果您需要后台进程（例如开发服务器），请在会话开始`InvokeAgentRuntimeCommand`后通过启动它。
**Example**
```
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 拉取权限。有关详细信息，请参阅[执行角色政策](harness-security.md#harness-execution-role-policy)。
用 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
```
## 环境变量
设置传递给运行时容器的环境变量。环境变量可供代理和会话中运行的任何自定义容器使用。
**Example**
```
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"}'
```
在以下位置设置环境变量`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 运行时[文件系统配置](https://docs.amazonaws.cn/bedrock-agentcore/latest/devguide/runtime-filesystem-configurations.html)。同样的要求也适用于安全带。
### 在 AgentCore CLI 中配置环境和文件系统
**Example**
在项目目录`agentcore`中运行以打开 TUI，选择 “**添加”**，然后选择 Harn ** es ** s。该向导将引导您浏览执行环境以及**高级设置**中的永久文件系统。
1. 在**自定义环境**步骤中，保留默认环境或选择预建容器镜像 (ECR URI) 或 Dockerfile。
1. 文件系统挂载需要 VPC 模式，因此在 “**高级” 设置中**启用**带**空间的**网络**和**文件系统存储**，然后**按 Enter **。
1. 选择 ** VPC ** 网络模式，然后为安全带提供子网和安全组。
1. 设置会话存储挂载路径（下方`/mnt`）。
1. 要连接 Amazon EFS 文件系统，请输入 EFS 接入点 ARN（以及下一步中的挂载路径）。
1. 要附加 Amazon S3 文件，请输入 S3 文件接入点 ARN（及其挂载路径）。
确认向导，然后运行`agentcore deploy`进行申请。
### 会话存储
当您使用该文件调用时，写入到挂载路径的文件会跨 stop/resume 周期保存`runtimeSessionId`。
**Example**
```
aws bedrock-agentcore-control update-harness \
--harness-id "MyHarness-UuFdkQoXSL" \
--environment '{"agentCoreRuntimeEnvironment": {"filesystemConfigurations": [{"sessionStorage": {"mountPath": "/mnt/data/"}}]}}'
```
```
# 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`数据保存在您的账户中，可以与安装相同接入点的其他安全带或代理运行时共享。
**Example**
```
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"
}
}
]
}
}'
```
使用 `--efs-access-point` as 连接 EFS 接入点`:`。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 存储桶双向同步。
**Example**
```
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"
}
}
]
}
}'
```
使用 `--s3-access-point` as 连接 S3 文件访问点`:`。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 运行时的[文件系统配置](https://docs.amazonaws.cn/bedrock-agentcore/latest/devguide/runtime-filesystem-configurations.html)。
#### 相关主题
+ [技能](harness-skills.md)-附加 Git、S3 或 Skills 中的 Amazon 技能
+ [内存](harness-memory.md)-在会话之间持续对话
+ [工具](harness-tools.md)-将工具连接到您的安全带
+ [安全性和访问控制](harness-security.md)-执行角色策略和 VPC 配置
+ [API 文档](harness-get-started.md#api-documentation)