本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # Python 的直接代码部署 通过直接代码部署，您只需将 Python-based 代理代码及其依赖项打包到.zip 文件存档中，即可将代理引入 Amazon Bedrock AgentCore Runtime。您的代理仍需要遵循[AgentCore 运行时要求](https://docs.amazonaws.cn/bedrock-agentcore/latest/devguide/runtime-service-contract.html)：拥有一个入口点.py 文件，该文件要么使用[亚马逊 Bedrock Py AgentCore thon SDK 中的`@app.entrypoint`注解，要](https://github.com/aws/bedrock-agentcore-sdk-python)么实现 P `/invocations` OST 和 `/ping` GET 服务器终端节点。 ## 先决条件 在开始之前，请确保您满足以下条件： + ** Amazon 配置**了凭据的账户。要配置您的 Amazon 证书，请参阅 C Amazon LI 中的[配置和凭据文件设置。](https://docs.amazonaws.cn/cli/latest/userguide/cli-configure-files.html) + [https://docs.astral.sh/uv/getting-started/installation/](https://docs.astral.sh/uv/getting-started/installation/)**已安装 Uv ** 并安装了 [ Python 3.10\+ ](https://docs.astral.sh/uv/guides/install-python/) + ** Amazon 权限**：要使用 AgentCore CLI 创建和部署代理，必须具有相应的权限。有关更多信息，请参阅[使用 AgentCore CLI ](https://docs.amazonaws.cn/bedrock-agentcore/latest/devguide/runtime-permissions.html#runtime-permissions-cli)。 + **模型访问权限**：默认情况下，Amazon Bedrock 允许访问基础模型。要使用非基础模型，请按照[模型访问步骤](https://docs.amazonaws.cn/bedrock/latest/userguide/model-access.html#model-access-sdk-step4)进行操作。 ## 第 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`文件 + 一个`agentcore/agentcore.json`配置文件 + `agentcore/cdk/`基础设施项目 生成的`pyproject.toml`包括 Strands AgentCore 和 Strands 依赖关系。Uv 在项目创建期间创建虚拟环境和锁定文件。 （可选）运行`cd app/DirectDeployAgent && uv add aws-opentelemetry-distro && cd ../..`以启用 [ Amazon Bedrock AgentCore 可观测性跟踪。](https://docs.amazonaws.cn/xray/latest/devguide/xray-services-adot.html) ## 第 3 步：在本地测试 在启动之前，请确保端口 8080 是空闲的。[如果端口已在使用中，请参见](runtime-get-started-cli.md#common-issues)故障排除。 打开终端窗口并使用以下命令启动代理： ``` 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 观测性](https://docs.amazonaws.cn/bedrock-agentcore/latest/devguide/observability.html)可帮助您跟踪、调试和监控您在运行时托管的 AgentCore 代理。首先，按照启用 Amazon Bedrock AgentCore 运行时可观察性[中的说明](https://docs.amazonaws.cn/bedrock-agentcore/latest/devguide/observability-configure.html#observability-configure-builtin)启用 CloudWatch 交易搜索。要观察您的代理，请参阅[查看您的亚马逊 Bedrock AgentCore 代理的可观测性数据。](https://docs.amazonaws.cn/bedrock-agentcore/latest/devguide/observability-view.html) ## 第 5 步：部署到 AgentCore 运行时并调用 使用以下方法之一部署代理： **Example** 1. 以下步骤部署在步骤 2 中创建的 CodeZip 项目。有关更多信息，请参阅 AgentCore CLI [ 入门](runtime-get-started-cli.md)。需要使用 Uv 来创建和打包 Python 项目。 使用设置代理后`agentcore create`，使用该`deploy`命令创建 zip 部署包，将其上传到指定的存储桶，然后部署代理。 ``` agentcore deploy ``` 让我们提示特工开个玩笑！ ``` agentcore invoke "Tell me a joke" ``` 第一次部署需要一些时间来安装依赖项，但是代理的后续更新通过重复使用压缩的依赖项来优化这一点 **配置管理 ** 您可以随时使用`agentcore add`命令或直接编辑配置文件来修改代理`agentcore/agentcore.json`配置。 配置文件允许您更新部署参数，例如 VPC 配置、执行角色、会话超时和 OAuth 授权方设置。 1. 运行打开 `agentcore` TUI，然后选择**部署**。部署屏幕在验证项目、综合 CloudFormation和配置资源时显示实时进度： Amazon ![AgentCore 显示 CloudFormation 堆栈更新的部署进度](https://docs.amazonaws.cn/bedrock-agentcore/latest/devguide/images/tui/code-deploy-progress.png) 部署完成后，使用`agentcore invoke`来测试您的代理。 1. 要下载与 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 运行时控制台和 Amazon 命令行接口部署 .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 `要在 Windows 中更改文件权限，请参阅 Microsoft Windows 文档中的 [Set, View, Change, or Remove Permissions on an Object](https://learn.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2008-R2-and-2008/cc731667(v=ws.10))。\+。。如果您没有授予 AgentCore Runtime 访问部署包中目录所需的权限，R AgentCore untime 会将这些目录的权限设置为 755 (rwxr-xr-x)。 包含 Linux ** arm64 ** 依赖项的 ZIP 存档需要上传到 S3，这是创建代理运行时的先决条件。以下代码要求指定的 S3 存储桶已经存在。请按照[此处](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3/client/create_bucket.html)的 Amazon 文档使用 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']}") ``` 有关以编程方式调用代理的更多信息，请参阅以编程方式[调用代理。](runtime-get-started-cli.md#invoke-programmatically) 1. 您可以使用具有托管运行时支持的 Amazon Bedrock AgentCore 控制台来部署代理。控制台为上传 ZIP 文件和配置代理设置提供了直观的界面。 要使用控制台进行部署，请先按照上面*自定义 zip \+ boto3 * 选项卡中的步骤创建部署包。 **通过控制台创建代理 ** 要创建您的代理，请执行以下操作： 1. 在代理主页上，选择**主机代理 ** 1. 选择您的来源选择： + **S3 来源 **-从 S3 存储桶上传 + **本地上传 **-从您的计算机上传 ZIP 文件 + **模板 **-使用预建的代理模板 1. 配置您的代理设置： + 座席姓名 + 运行时版本（推荐 Python 3.13） + 入口点（例如，`main.py`） + 执行角色（新建或使用现有角色） 1. 选择**创建代理**进行部署 **创建终端节点 ** 选择 “**创建终端节点**” 为您的代理创建新的终端节点。将预先填写端点名称和关联版本。 **测试端点 ** 选择一个端点并选择 “**测试端点” ** 以导航到 Playground/Sandbox 进行测试。 **执行角色要求 ** 您的代理需要具有适当权限的执行角色。有关执行角色和权限的详细信息，请参阅[AgentCore 运行时权限](https://docs.amazonaws.cn/bedrock-agentcore/latest/devguide/runtime-permissions.html)。执行角色必须包括基本的 Amazon Bedrock AgentCore 运行时权限、部署包的 S3 访问权限以及用于可观察性的 CloudWatch 日志权限。 ## 步骤 6：停止会话、更新或清理 使用以下方法之一停止运行时会话、更新或清理代理： **Example** 1. 要更新之前部署的 AgentCore Runtime，请执行： ``` agentcore deploy ``` 要在可配置会话`IdleRuntimeSessionTimeout`（默认为 15 分钟）之前停止正在运行的会话并节省任何潜在的失控成本，请使用 [ StopRuntimeSession ](https://docs.amazonaws.cn/bedrock-agentcore/latest/APIReference/API_StopRuntimeSession.html) API 操作。C AgentCore LI 目前不支持直接停止会话。 要删除与 AgentCore 运行时相关的所有资源，请先移除所有资源，然后进行部署以拆除 Amazon 资源： ``` agentcore remove all agentcore deploy ``` 1. 以下 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='', 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='' ) 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!") ``` 1. ===== 更新代理 在代理详细信息页面上，选择**更新主机**，使用更新的代码或配置创建新版本。 **更新终端节点 ** 从 “端点” 表中选择一个端点，然后选择 “**编辑” ** 以更新描述或关联版本。 **删除终端节点 ** 选择一个端点并选择**删除**。你需要键入 “删除” 来确认删除。 **删除代理 ** 在代理列表或详细信息页面上，选择您的代理并选择**删除**以删除代理和所有关联资源。 ## Python-specific 直接代码部署的概念 了解在亚马逊 Bedrock R AgentCore untime 中使用直接代码部署时的 Python-specific 概念。 **Topics** ### 依赖项搜索路径和包含运行时系统的库 在代码中使用 `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 ``` ### Python 字节码和 *pycach* 文件夹 我们建议您不要在代理的部署包中包含` pycache `文件夹。在具有不同架构或操作系统的编译计算机上编译的 Python 字节码可能与 AgentCore 运行时执行环境不兼容。 ### 带有原生库的部署包 如果您的函数仅使用纯 Python 程序包和模块，则可以使用 `uv pip install` 命令在任何本地生成计算机上安装依赖项并创建 .zip 文件。许多流行的 Python 库，包括 NumPy 和 Pandas，都不是纯 Python，它们包含用 C 或 C 编写的 C/C 代码。当您将包含代码的库添加到部署包时，必须正确构建包以使其与 AgentCore 运行时执行环境兼容。 Python 软件包索引 (P [ yPI](https://pypi.org/)) 上可用的大多数软件包都以 “轮子”（.whl 文件）的形式提供。.whl 文件是一种 zip 文件，它包含已构建的分发，其中包含针对特定操作系统和指令集架构的预编译二进制文件。为了使您的部署包与 Amazon Bedrock AgentCore Runtime 兼容，您需要安装适用于 Linux 操作系统和 ** arm64 ** 指令集架构的滚轮。 有些包可能只能作为源分发提供。对于这些包，你需要自己编译和构建 C/C \+\+ 组件。 要查看哪些分发可用于所需的包，请执行以下操作： 1. 在 [Python 程序包索引主页](https://pypi.org/)上搜索程序包名称。 1. 选择要使用的包的版本。 1. 选择**下载文件**。 ### 使用源分发 如果您的软件包仅作为源代码发行版提供，则需要自己构建 C/C \+\+ 库。要使您的软件包与亚马逊 Bedrock AgentCore 运行时执行环境兼容，您需要将其构建在使用相同亚马逊 Linux 操作系统和 ** arm64 ** 指令集的环境中。您可以通过在 Amazon Elastic Compute Cloud（Amazon EC2）Linux 实例中构建包来实现此目的。 要了解如何启动并连接到 Amazon EC2 Linux 实例，请参阅**《Amazon EC2 用户指南》中的[开始使用 Amazon EC2](https://docs.amazonaws.cn/AWSEC2/latest/UserGuide/EC2_GetStarted.html)。