本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
Python 的直接代码部署
通过直接代码部署，您只需将 Python-based 代理代码及其依赖项打包到.zip 文件存档中，即可将代理引入 Amazon Bedrock AgentCore Runtime。您的代理仍需要遵循AgentCore 运行时要求：拥有一个入口点.py 文件，该文件要么使用亚马逊 Bedrock Py AgentCore thon SDK 中的@app.entrypoint注解，要么实现 P /invocations OST 和 /ping GET 服务器终端节点。
先决条件
在开始之前，请确保您满足以下条件：
第 1 步：安装 AgentCore CLI
安装 C AgentCore LI：
npm install -g @aws/agentcore
第 2 步：创建代理项目
为教程创建一个 AgentCore 项目：
agentcore create \
--project-name DirectDeployProject \
--name DirectDeployAgent \
--language Python \
--framework Strands \
--model-provider Bedrock \
--memory none \
--build CodeZip
cd DirectDeployProject
此命令生成：
生成的pyproject.toml包括 Strands AgentCore 和 Strands 依赖关系。Uv 在项目创建期间创建虚拟环境和锁定文件。
（可选）运行cd app/DirectDeployAgent && uv add aws-opentelemetry-distro && cd ../..以启用 Amazon Bedrock AgentCore 可观测性跟踪。
第 3 步：在本地测试
在启动之前，请确保端口 8080 是空闲的。如果端口已在使用中，请参见故障排除。
打开终端窗口并使用以下命令启动代理：
agentcore dev --no-browser
打开另一个终端窗口并输入以下命令来测试您的代理：
curl -X POST http://localhost:8080/invocations \
-H "Content-Type: application/json" \
-d '{"prompt": "Hello!"}'
成功：您应该看到类似的回复{"result": "Hello! I’m here to help…"}。在运行代理的终端窗口中，输入Ctrl+C以停止代理。
第 4 步：为您的代理启用可观察性
Amazon Bedrock 可 AgentCore 观测性可帮助您跟踪、调试和监控您在运行时托管的 AgentCore 代理。首先，按照启用 Amazon Bedrock AgentCore 运行时可观察性中的说明启用 CloudWatch 交易搜索。要观察您的代理，请参阅查看您的亚马逊 Bedrock AgentCore 代理的可观测性数据。
第 5 步：部署到 AgentCore 运行时并调用
使用以下方法之一部署代理：
例
- AgentCore CLI
-
-
以下步骤部署在步骤 2 中创建的 CodeZip 项目。有关更多信息，请参阅 AgentCore CLI 入门。需要使用 Uv 来创建和打包 Python 项目。
使用设置代理后agentcore create，使用该deploy命令创建 zip 部署包，将其上传到指定的存储桶，然后部署代理。
agentcore deploy
让我们提示特工开个玩笑！
agentcore invoke "Tell me a joke"
第一次部署需要一些时间来安装依赖项，但是代理的后续更新通过重复使用压缩的依赖项来优化这一点
配置管理
您可以随时使用agentcore add命令或直接编辑配置文件来修改代理agentcore/agentcore.json配置。
配置文件允许您更新部署参数，例如 VPC 配置、执行角色、会话超时和 OAuth 授权方设置。
- Interactive
-
-
运行打开 agentcore TUI，然后选择部署。部署屏幕在验证项目、综合 CloudFormation和配置资源时显示实时进度： AWS
部署完成后，使用agentcore invoke来测试您的代理。
- Custom zip + boto3
-
-
要下载与 AgentCore Runtime 兼容的轮子，可以使用 uv pip --python-platform 选项。 AgentCore 运行时仅支持 arm64 指令集架构，运行以下命令。将 --python 3.x 替换为正在使用的 Python 运行时系统版本。
uv pip install \
--python-platform aarch64-manylinux2014 \
--python-version 3.13 \
--target=deployment_package \
--only-binary=:all: \
-r pyproject.toml
在项目根目录下使用已安装的库创建 .zip 文件。
cd deployment_package
zip -r ../deployment_package.zip .
将main.py文件和软件包中的其他文件添加到 .zip 文件的根目录中。
cd ..
zip deployment_package.zip main.py
创建 .zip 部署包后，您可以使用它来创建新的 AgentCore Runtime 或更新现有的 Runtime。您可以使用 AgentCore 运行时 API、 AgentCore 运行时控制台和 AWS 命令行接口部署 .zip 包。 AgentCore CLI 将执行上述步骤来创建 .zip。
。 AgentCore 运行时.zip 部署包的最大大小为 250 MB（压缩）和 750 MB（未压缩）。请注意，此限制适用于您上传的所有文件的总大小。 AgentCore 运行时需要权限才能读取部署包中的文件。在 Linux 权限八进制表示法中， AgentCore 运行时对不可执行文件（rw-r—r--）需要 644 个权限，对于目录和可执行文件，需要 755 个权限（rwxr-xr-x）。在 Linux 和 MacOS 中，使用 chmod 命令更改部署包中文件和目录的文件权限。例如，要为不可执行文件提供正确的权限，请运行以下命令。chmod 644 <filepath>要在 Windows 中更改文件权限，请参阅 Microsoft Windows 文档中的 Set, View, Change, or Remove Permissions on an Object。+。。如果您没有授予 AgentCore Runtime 访问部署包中目录所需的权限，R AgentCore untime 会将这些目录的权限设置为 755 (rwxr-xr-x)。
包含 Linux arm64 依赖项的 ZIP 存档需要上传到 S3，这是创建代理运行时的先决条件。以下代码要求指定的 S3 存储桶已经存在。请按照此处的 AWS 文档使用 boto3 创建存储桶。以下 boto3 代码会将.zip 文件档案上传到 s3 并创建 Amazon Bedrock 运行时。 AgentCore
import boto3
account_id = "your aws account id"
agent_name = "strands_10_23"
s3_client = boto3.client('s3', region_name='us-west-2')
print("Uploading deployment.zip to S3...")
s3_client.upload_file(
'deployment_package.zip', # archive on file system
f"bedrock-agentcore-code-{account_id}-us-west-2", # bucket name
f"{agent_name}/deployment_package.zip", # prefix
ExtraArgs={'ExpectedBucketOwner': account_id} # ownership check
)
print("Upload completed successfully!")
print(f"S3 Location: s3://bedrock-agentcore-code-{account_id}-us-west-2/{agent_name}/deployment_package.zip")
agentcore_client = boto3.client('bedrock-agentcore-control', region_name='us-west-2')
response = agentcore_client.create_agent_runtime(
agentRuntimeName=agent_name,
agentRuntimeArtifact={
'codeConfiguration': {
'code': {
's3': {
'bucket': f"bedrock-agentcore-code-{account_id}-us-west-2",
'prefix': f"{agent_name}/deployment_package.zip"
}
},
'runtime': 'PYTHON_3_13',
'entryPoint': ['opentelemetry-instrument', 'main.py']
} # if not adding otel dependency, remove opentelemetry-instrument from entrypoint array
},
networkConfiguration={"networkMode": "PUBLIC"},
roleArn=f"arn:aws:iam::{account_id}:role/AmazonBedrockAgentCoreSDKRuntime-us-west-2",
lifecycleConfiguration={
'idleRuntimeSessionTimeout': 300, # 5 min, configurable
'maxLifetime': 1800 # 30 minutes, configurable
},
)
print(f"Agent Runtime created successfully!")
print(f"Agent Runtime ARN: {response['agentRuntimeArn']}")
print(f"Status: {response['status']}")
有关以编程方式调用代理的更多信息，请参阅以编程方式调用代理。
- console
-
-
您可以使用具有托管运行时支持的 Amazon Bedrock AgentCore 控制台来部署代理。控制台为上传 ZIP 文件和配置代理设置提供了直观的界面。
要使用控制台进行部署，请先按照上面自定义 zip + boto3 选项卡中的步骤创建部署包。
通过控制台创建代理
要创建您的代理，请执行以下操作：
-
在代理主页上，选择主机代理
-
选择您的来源选择：
-
S3 来源 -从 S3 存储桶上传
-
本地上传 -从您的计算机上传 ZIP 文件
-
模板 -使用预建的代理模板
-
配置您的代理设置：
-
座席姓名
-
运行时版本（推荐 Python 3.13）
-
入口点（例如，main.py）
-
执行角色（新建或使用现有角色）
-
选择创建代理进行部署
创建终端节点
选择 “创建终端节点” 为您的代理创建新的终端节点。将预先填写端点名称和关联版本。
测试端点
选择一个端点并选择 “测试端点” 以导航到 Playground/Sandbox 进行测试。
执行角色要求
您的代理需要具有适当权限的执行角色。有关执行角色和权限的详细信息，请参阅AgentCore 运行时权限。执行角色必须包括基本的 Amazon Bedrock AgentCore 运行时权限、部署包的 S3 访问权限以及用于可观察性的 CloudWatch 日志权限。
步骤 6：停止会话、更新或清理
使用以下方法之一停止运行时会话、更新或清理代理：
例
- AgentCore CLI
-
-
要更新之前部署的 AgentCore Runtime，请执行：
agentcore deploy
要在可配置会话IdleRuntimeSessionTimeout（默认为 15 分钟）之前停止正在运行的会话并节省任何潜在的失控成本，请使用 StopRuntimeSession API 操作。C AgentCore LI 目前不支持直接停止会话。
要删除与 AgentCore 运行时相关的所有资源，请先移除所有资源，然后进行部署以拆除 AWS 资源：
agentcore remove all
agentcore deploy
- boto3
-
-
以下 boto3 代码将更新运行时。 AgentCore
import boto3
account_id = "your aws account id"
agent_name = "strands_10_23"
s3_client = boto3.client('s3', region_name='us-west-2')
print("Uploading deployment.zip to S3...")
s3_client.upload_file(
'deployment_package.zip', # archive on file system
f"bedrock-agentcore-code-{account_id}-us-west-2", # bucket name
f"{agent_name}/deployment_package.zip", # prefix
ExtraArgs={'ExpectedBucketOwner': account_id} # ownership check
)
print("Upload completed successfully!")
print(f"S3 Location: s3://bedrock-agentcore-code-{account_id}-us-west-2/{agent_name}/deployment_package.zip")
bedrock_agentcore_client = boto3.client('bedrock-agentcore-control', region_name='us-west-2')
response = bedrock_agentcore_client.update_agent_runtime(
agentRuntimeId='<your-agent-id>',
agentRuntimeArtifact={
'codeConfiguration': {
'code': {
's3': {
'bucket': f"bedrock-agentcore-code-{account_id}-us-west-2",
'prefix': f"{agent_name}/deployment_package.zip"
}
},
'runtime': 'PYTHON_3_13',
'entryPoint': ['opentelemetry-instrument', 'main.py']
} # if not adding otel dependency, remove opentelemetry-instrument from entrypoint array
},
networkConfiguration={"networkMode": "PUBLIC"},
roleArn=f"arn:aws:iam::{account_id}:role/AmazonBedrockAgentCoreSDKRuntime-us-west-2"
)
print(f"Agent Runtime updated successfully!")
print(f"Agent Runtime ARN: {response['agentRuntimeArn']}")
print(f"Status: {response['status']}")
要在可配置会话IdleRuntimeSessionTimeout（默认为 15 分钟）之前停止正在运行的会话并节省任何潜在的失控成本，请使用以下 boto3 代码：
import boto3
agent_core_client = boto3.client('bedrock-agentcore', region_name='us-west-2')
response = agent_core_client.stop_runtime_session(
agentRuntimeArn='arn:aws:bedrock-agentcore:us-west-2:account-id:runtime/agent-name-suffix',
runtimeSessionId='your-session-id',
qualifier="DEFAULT"
)
以下 boto3 代码将删除 s3 中的亚马逊 Bedrock AgentCore 运行时和 .zip 存档文件。
import boto3
account_id = "your aws account id"
agent_name = "strands_10_23"
bedrock_agentcore_client = boto3.client('bedrock-agentcore-control', region_name='us-west-2')
print("Deleting Agent from Amazon Bedrock AgentCore Runtime!")
response = bedrock_agentcore_client.delete_agent_runtime(
agentRuntimeId='<agent-id>'
)
print(f"Agent Runtime delete successfully!")
print(f"Status: {response['status']}")
s3_client = boto3.client('s3', region_name='us-west-2')
print("Deleting deployment archive from S3...")
s3_client.delete_object(
Bucket=f"bedrock-agentcore-code-{account_id}-us-west-2",
Key=f"{agent_name}/deployment_package.zip",
ExpectedBucketOwner=account_id
)
print("Archive deleted successfully from S3!")
- console
-
-
===== 更新代理
在代理详细信息页面上，选择更新主机，使用更新的代码或配置创建新版本。
更新终端节点
从 “端点” 表中选择一个端点，然后选择 “编辑” 以更新描述或关联版本。
删除终端节点
选择一个端点并选择删除。你需要键入 “删除” 来确认删除。
删除代理
在代理列表或详细信息页面上，选择您的代理并选择删除以删除代理和所有关联资源。
Python-specific 直接代码部署的概念
了解在亚马逊 Bedrock R AgentCore untime 中使用直接代码部署时的 Python-specific 概念。
在代码中使用 import 语句时，Python 运行时系统会搜索其搜索路径中的目录，直到找到相应模块或包。默认情况下，运行时搜索的第一个位置是解压缩和挂载 .zip 部署包的目录 () /var/task。
通过添加以下代码片段，您可以查看 AgentCore Runtime 代理的完整搜索路径。
import sys
search_path = sys.path
print(search_path)
您还可以在 .zip 程序包内的单独文件夹中添加依赖项。例如，您可以将 Boto3 SDK 的一个版本添加到您的.zip 包中名为的文件夹中。common解压缩并安装 .zip 程序包后，此文件夹将放置在 /var/task 目录中。要在代码中使用 .zip 部署包中某个文件夹中的依赖项，请使用 import from 语句。例如，要使用 .zip 程序包中名为 common 的文件夹中的 Boto3 版本，请使用以下语句。
from common import boto3
我们建议您不要在代理的部署包中包含
pycache
文件夹。在具有不同架构或操作系统的编译计算机上编译的 Python 字节码可能与 AgentCore 运行时执行环境不兼容。
如果您的函数仅使用纯 Python 程序包和模块，则可以使用 uv pip install 命令在任何本地生成计算机上安装依赖项并创建 .zip 文件。许多流行的 Python 库，包括 NumPy 和 Pandas，都不是纯 Python，它们包含用 C 或 C 编写的 C/C 代码。当您将包含代码的库添加到部署包时，必须正确构建包以使其与 AgentCore 运行时执行环境兼容。
Python 软件包索引 (P yPI) 上可用的大多数软件包都以 “轮子”（.whl 文件）的形式提供。.whl 文件是一种 zip 文件，它包含已构建的分发，其中包含针对特定操作系统和指令集架构的预编译二进制文件。为了使您的部署包与 Amazon Bedrock AgentCore Runtime 兼容，您需要安装适用于 Linux 操作系统和 arm64 指令集架构的滚轮。
有些包可能只能作为源分发提供。对于这些包，你需要自己编译和构建 C/C ++ 组件。
要查看哪些分发可用于所需的包，请执行以下操作：
如果您的软件包仅作为源代码发行版提供，则需要自己构建 C/C ++ 库。要使您的软件包与亚马逊 Bedrock AgentCore 运行时执行环境兼容，您需要将其构建在使用相同亚马逊 Linux 操作系统和 arm64 指令集的环境中。您可以通过在 Amazon Elastic Compute Cloud（Amazon EC2）Linux 实例中构建包来实现此目的。
要了解如何启动并连接到 Amazon EC2 Linux 实例，请参阅《Amazon EC2 用户指南》中的开始使用 Amazon EC2。
