直接部署适用于 Python 的代码
直接部署代码使您只需将 Python-based 代理代码及其依赖项打包到.zip 文件存档中即可将代理引入 Amazon Bedrock Runt AgentCore ime。您的代理仍然需要遵循AgentCore 运行时要求：拥有一个 entrypoint .py 文件，该文件要么使用 Amazon B edrock Pyth AgentCore on SDK @app.entrypoint 中的注释，要么实现 P /invocations OST 和 /ping GET 服务器端点。
先决条件
在开始之前，请确保您满足以下条件：
第 1 步：设置项目并安装依赖关系
使用以下命令初始化您的项目：
uv init agentcore_runtime_direct_deploy --python 3.13
cd agentcore_runtime_direct_deploy
添加核心软件包：
uv add bedrock-agentcore strands-agents
安装 C AgentCore LI（后续步骤所必需的）：
npm install -g @aws/agentcore
Package 描述：
-
bedrock-agentcore-用于构建人工智能代理的亚马逊 B AgentCore edrock SDK
-
strands-agents-Strands Agen ts
-
@ aws/agentcore- AgentCore CLI
（可选）运行uv add aws-opentelemetry-distro以启用 Amazon Bedrock AgentCore 可观测性跟踪。
Uv 将自动创建一个包含依赖项的pyproject.tomluv.lock文件、包含依赖项闭包的文件和.venv目录。
第 2 步：创建您的代理项目
使用agentcore create命令使用您选择的框架来设置骨架代理项目：
agentcore create
该命令将提示您：
此命令生成：
-
使用所选框架的代理代码
-
具有必要依赖关系的pyproject.toml文件
-
agentcore/agentcore.json配置文件
-
基础架构即代码 (IaC) 文件（如果选择了生产模板）
第 3 步：在本地测试
在启动之前，请确保端口 8080 是空闲的。请参阅 “常见问题和解决方案” 中的 “正在使用的端口 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 交易搜索。要观察您的代理，请参阅查看您的 Amazon Bedrock AgentCore 代理的可观察性数据。
步骤 5：部署到 AgentCore 运行时并调用
使用以下方法之一部署代理：
例
- AgentCore CLI
-
-
要将代理部署到 AgentCore Runtime，需要执行以下步骤。有关更多信息，请参阅 AgentCore CLI 入门。如果 Uv 可用， AgentCore CLI 将建议直接部署代码。否则，它将默认为容器部署类型。
使用设置代理后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 运行时或更新现有的运行时。您可以使用 AgentCore 运行时 API、 AgentCore 运行时控制台和 AWS 命令行界面来部署您的.zip 包。C AgentCore LI 将执行上述步骤来创建.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。+。。 如果您不授予 R AgentCore untime 访问部署包中目录所需的权限，则 AgentCore 运行时会将这些目录的权限设置为 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 运行时，请执行：
agentcore deploy
要在可配置会话IdleRuntimeSessionTimeout（默认为 15 分钟）之前停止正在运行的会话并节省任何潜在的失控成本，请使用 StopRuntimeSessionAPI 操作。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 直接代码部署的概念
了解在 Amazon Bedrock Runt AgentCore ime 中使用直接代码部署时的 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 Package Index (P yPI) 上可用的大多数包都以 “轮子”（.whl 文件）的形式提供。.whl 文件是一种 zip 文件，它包含已构建的分发，其中包含针对特定操作系统和指令集架构的预编译二进制文件。要使您的部署包与 Amazon Bedrock AgentCore AgentCore Runtime 兼容，您需要安装 Linux 操作系统和 arm64 指令集架构的轮子。
有些包可能只能作为源分发提供。对于这些软件包，你需要自己编译和构建 C/C ++ 组件。
要查看哪些分发可用于所需的包，请执行以下操作：
如果您的软件包仅作为源代码发行版提供，则需要自己构建 C/C ++ 库。要使您的软件包与 Amazon Bedrock AgentCore AgentCore 运行时执行环境兼容，您需要在使用与 arm64 指令集相同的亚马逊 Linux 操作系统的环境中进行构建。您可以通过在 Amazon Elastic Compute Cloud（Amazon EC2）Linux 实例中构建包来实现此目的。
要了解如何启动并连接到 Amazon EC2 Linux 实例，请参阅《Amazon EC2 用户指南》中的开始使用 Amazon EC2。
