# 直接部署适用于 Python 的代码 直接部署代码使您只需将 Python-based 代理代码及其依赖项打包到.zip 文件存档中即可将代理引入 Amazon Bedrock Runt AgentCore ime。您的代理仍然需要遵循[AgentCore 运行时要求](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-service-contract.html)：拥有一个 entrypoint .py 文件，该文件要么使用 Amazon B [edrock Pyth AgentCore on SDK `@app.entrypoint`](https://github.com/aws/bedrock-agentcore-sdk-python) 中的注释，要么实现 P `/invocations` OST 和 `/ping` GET 服务器端点。 ## 先决条件 在开始之前，请确保您满足以下条件： + AWS 已配置凭据的@@ **账户**。要配置您的 AWS 证书，请参阅 [AWS CLI 中的配置和凭证文件设置](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html)。 + **安装了 [Uv](https://docs.astral.sh/uv/getting-started/installation/) 并安装了** [Python 3.10\+](https://docs.astral.sh/uv/guides/install-python/) + ** AWS 权限**：要使用 AgentCore CLI 创建和部署代理，必须具有相应的权限。有关更多信息，请参阅[使用 AgentCore CLI](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-permissions.html#runtime-permissions-cli)。 + **模型访问权限**：在亚马逊 Bedrock 主机中[启用了](https://docs.aws.amazon.com/bedrock/latest/userguide/model-access-modify.html) Anthropic Claude Sonnet 4.0。有关在 Strands Agents 中使用其他模型的信息，请参阅 Strands Agent [s SDK 文档](https://strandsagents.com/latest/documentation/docs/)中的*模型提供者*部分。 ## 第 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](https://strandsagents.com/latest/) + **@ aws/agentcore**- AgentCore CLI （可选）运行`uv add aws-opentelemetry-distro`以启用 [Amazon Bedrock AgentCore 可观测性跟踪](https://docs.aws.amazon.com/xray/latest/devguide/xray-services-adot.html)。 Uv 将自动创建一个包含依赖项的`pyproject.toml``uv.lock`文件、包含依赖项闭包的文件和`.venv`目录。 ## 第 2 步：创建您的代理项目 使用`agentcore create`命令使用您选择的框架来设置骨架代理项目： ``` agentcore create ``` 该命令将提示您： + 选择框架（在本教程中选择 Strands Agents） + 提供项目名称 + 选择模板（基础版或生产版） + 选择模型提供商和其他选项 此命令生成： + 使用所选框架的代理代码 + 具有必要依赖关系的`pyproject.toml`文件 + `agentcore/agentcore.json`配置文件 + 基础架构即代码 (IaC) 文件（如果选择了生产模板） ## 第 3 步：在本地测试 在启动之前，请确保端口 8080 是空闲的。请参阅 “[常见问题和解决方案](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-get-started-cli.html#common-issues)*” 中的 “正在使用的端口 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 观测性](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability.html)可帮助您跟踪、调试和监控您在运行时中 AgentCore 托管的代理。首先按照启用 [Amazon Bedrock AgentCore 运行时可观察性中的说明启用 CloudWatch ](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability-configure.html#observability-configure-builtin)交易搜索。要观察您的代理，请参阅[查看您的 Amazon Bedrock AgentCore 代理的可观察性数据](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/observability-view.html)。 ## 步骤 5：部署到 AgentCore 运行时并调用 使用以下方法之一部署代理： **Example** 1. 要将代理部署到 AgentCore Runtime，需要执行以下步骤。有关更多信息，请参阅 [ AgentCore CLI 入门](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-get-started-cli.html)。如果 Uv 可用， AgentCore CLI 将建议直接部署代码。否则，它将默认为容器部署类型。 使用设置代理后`agentcore create`，使用`deploy`命令创建 zip 部署包，将其上传到指定的存储桶，然后部署代理。 ``` agentcore deploy ``` 让我们提示经纪人开个玩笑吧！ ``` agentcore invoke "Tell me a joke" ``` 第一次部署需要花费时间来安装依赖关系，但是代理的后续更新通过重复使用压缩的依赖项来优化依赖关系 **配置管理** 您可以随时使用`agentcore add`命令或直接编辑配置文件来修改代理`agentcore/agentcore.json`配置。 配置文件允许您更新部署参数，例如 VPC 配置、执行角色、会话超时和 OAuth 授权机构设置。 1. 运行打开 `agentcore` TUI，然后选择**部署**。部署屏幕在验证您的项目、合成 CloudFormation和配置资源时会显示实时进度： AWS ![AgentCore 显示 CloudFormation 堆栈更新的部署进度](http://docs.aws.amazon.com/zh_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 运行时或更新现有的运行时。您可以使用 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 `要在 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))。\+。。 如果您不授予 R AgentCore untime 访问部署包中目录所需的权限，则 AgentCore 运行时会将这些目录的权限设置为 755 (rwxr-xr-x)。 需要将包含 Linux **arm64** 依赖项的 ZIP 存档上传到 S3，以此作为创建代理运行时的先决条件。以下代码要求指定的 S3 存储桶已经存在。请按照[此处](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/s3/client/create_bucket.html)的 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']}") ``` 有关以编程方式调用代理的更多信息，请参阅以编程方式[调用代理](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-get-started-cli.html#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.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-permissions.html)。执行角色必须包括基本 Amazon Bedrock AgentCore 运行时权限、部署包的 S3 访问权限以及可观察性的 CloudWatch 日志权限。 ## 步骤 6：停止会话、更新或清理 使用以下方法之一停止运行时会话、更新或清理代理： **Example** 1. 要更新先前部署的 AgentCore 运行时，请执行： ``` agentcore deploy ``` 要在可配置会话`IdleRuntimeSessionTimeout`（默认为 15 分钟）之前停止正在运行的会话并节省任何潜在的失控成本，请使用 [StopRuntimeSession](https://docs.aws.amazon.com/bedrock-agentcore/latest/APIReference/API_StopRuntimeSession.html)API 操作。C AgentCore LI 目前不支持直接停止会话。 要删除与 AgentCore 运行时相关的所有资源，请先移除所有资源，然后部署以拆除 AWS 资源： ``` 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 直接代码部署的概念 了解在 Amazon Bedrock Runt AgentCore ime 中使用直接代码部署时的 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 字节码和 *pyache* 文件夹 我们建议您不要在代理的部署包中包含` pycache `文件夹。在具有不同架构或操作系统的生成计算机上编译的 Python 字节码可能与 AgentCore 运行时执行环境不兼容。 ### 带有原生库的部署包 如果您的函数仅使用纯 Python 程序包和模块，则可以使用 `uv pip install` 命令在任何本地生成计算机上安装依赖项并创建 .zip 文件。许多流行的 Python 库（包括 NumPy 和 Pandas）都不是纯粹的 Python，而是包含用 C 或 C 编写的 C/C 代码。将包含代码的库添加到部署包时，必须正确构建包以使其与 AgentCore 运行时执行环境兼容。 Python Package Index (P [yPI](https://pypi.org/)) 上可用的大多数包都以 “轮子”（.whl 文件）的形式提供。.whl 文件是一种 zip 文件，它包含已构建的分发，其中包含针对特定操作系统和指令集架构的预编译二进制文件。要使您的部署包与 Amazon Bedrock AgentCore AgentCore Runtime 兼容，您需要安装 Linux 操作系统和 **arm64** 指令集架构的轮子。 有些包可能只能作为源分发提供。对于这些软件包，你需要自己编译和构建 C/C \+\+ 组件。 要查看哪些分发可用于所需的包，请执行以下操作： 1. 在 [Python 程序包索引主页](https://pypi.org/)上搜索程序包名称。 1. 选择要使用的包的版本。 1. 选择**下载文件**。 ### 使用源分发 如果您的软件包仅作为源代码发行版提供，则需要自己构建 C/C \+\+ 库。要使您的软件包与 Amazon Bedrock AgentCore AgentCore 运行时执行环境兼容，您需要在使用与 **arm64** 指令集相同的亚马逊 Linux 操作系统的环境中进行构建。您可以通过在 Amazon Elastic Compute Cloud（Amazon EC2）Linux 实例中构建包来实现此目的。 要了解如何启动并连接到 Amazon EC2 Linux 实例，请参阅**《Amazon EC2 用户指南》中的[开始使用 Amazon EC2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/EC2_GetStarted.html)。