本文為英文版的機器翻譯版本,如內容有任何歧義或不一致之處,概以英文版為準。
Python 的直接程式碼部署
透過直接程式碼部署,您可以將 Python 代理程式程式碼及其相依性封裝在 .zip 檔案封存中,並將其部署到 AgentCore 執行期。您的代理程式仍然需要遵循 AgentCore 執行期要求:具有一個進入點 .py 檔案,該檔案使用來自 Amazon Bedrock AgentCore Python SDK 的@app.entrypoint註釋,或實作 /invocations POST 和 /ping GET 伺服器端點。
此頁面包含簡潔的 AgentCore CLI 路徑,以及使用 uv、Boto3 或 AWS 管理主控台手動封裝和部署 .zip 檔案的詳細說明。如需完整的 CLI 工作流程,請參閱使用 AgentCore CLI 開始使用 AgentCore 執行期。
先決條件
開始前,請確保您具備以下條件:
步驟 1:準備和測試您的 Python 代理程式
您的專案應該包含您要新增至部署套件的檔案:
my-agent/
├── main.py
└── pyproject.toml
為您的應用程式使用 命令在本機執行代理程式。對於從 啟動其伺服器的進入點main.py,請執行:
uv run main.py
在另一個終端機中,測試/invocations端點:
curl -X POST http://localhost:8080/invocations \
-H "Content-Type: application/json" \
-d '{"prompt": "Hello!"}'
成功:您應該會看到類似 {"result": "Hello! I’m here to help…"} 的回應。在執行代理程式的終端機視窗中,輸入 Ctrl+C以停止代理程式。
或者,執行 uv add aws-opentelemetry-distro以啟用 Amazon Bedrock AgentCore 可觀測性追蹤。
步驟 2:啟用代理程式的可觀測性
Amazon Bedrock AgentCore 可觀測性可協助您追蹤、偵錯和監控您在 AgentCore 執行期中託管的代理程式。首先,遵循啟用 Amazon Bedrock AgentCore 執行時間可觀測性 中的指示來啟用 CloudWatch 交易搜尋。若要觀察您的代理程式,請參閱檢視 Amazon Bedrock AgentCore 代理程式的可觀測性資料。
步驟 3:封裝、部署和叫用
使用下列其中一種方法封裝和部署您的代理程式:
範例
- AgentCore CLI
-
-
對於 CLI 管理的CodeZip專案,AgentCore CLI 會為您封裝和部署專案。若要使用 AgentCore CLI 部署現有的代理程式,請從最小範本建立專案:
agentcore create --name DirectDeployProject --template agent-python-minimal
cd DirectDeployProject
將您的 main.py和 複製到 pyproject.toml app/agent/,取代產生的檔案。然後部署專案:
agentcore deploy
或者,agentcore build先執行 來合成和檢查專案,而不進行部署。
叫用部署的執行期:
agentcore invoke --runtime agent \
--payload '{"prompt":"Hello!"}'
您也可以在沒有引數agentcore的情況下執行 以開啟互動式終端機 UI,然後選擇部署來監看部署進度。如需本機測試,請參閱使用 AgentCore CLI 開始使用 AgentCore 執行期。
- Boto3
-
-
若要下載與 AgentCore 執行期相容的 wheel,您可以使用 uv pip --python-platform選項。AgentCore 執行期僅支援 arm64 架構。執行下列命令,並將 3.13 中的 取代--python-version為您的 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 Runtime API、AgentCore Runtime 主控台或 AWS Command Line Interface 部署 .zip 套件。
AgentCore 執行期的 .zip 部署套件大小上限為 250 MB (壓縮) 和 750 MB (解壓縮)。此限制適用於您上傳之所有檔案的合併大小。
AgentCore 執行期需要讀取部署套件中檔案的許可。在 Linux 許可八進位表示法中,AgentCore 執行期需要 644 個不可執行檔案的許可 (rw-r— r--) 和 755 個目錄和可執行檔的許可 (rwxr-xr-x)。在 Linux 和 MacOS 中,使用 chmod 命令變更部署套件中檔案和目錄的檔案許可。例如,若要為不可執行的檔案提供正確的許可,請執行 chmod 644 <filepath>。若要在 Windows 中變更檔案許可,請參閱 Microsoft Windows 文件的 Set, View, Change, or Remove Permissions on an Object。如果您未授予 AgentCore Runtime 存取部署套件中目錄所需的許可,AgentCore Runtime 會將這些目錄的許可設定為 755 (rwxr-xr-x)。
包含 Linux arm64 相依性的 ZIP 封存需要上傳到 S3 作為建立代理程式執行期的先決條件。下列程式碼要求指定的 S3 儲存貯體已存在。若要建立儲存貯體,請參閱 Boto3 文件中的 create_bucket。下列 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']}")
如需以程式設計方式叫用代理程式的詳細資訊,請參閱叫用串流代理程式。
- AWS Management Console
-
您可以使用具有受管執行期支援的 Amazon Bedrock AgentCore 主控台來部署代理程式。
若要使用 主控台部署,請先依照上述 Boto3 索引標籤中的步驟建立部署套件。
透過主控台建立代理程式
若要建立您的代理程式:
-
從客服人員首頁中,選擇託管客服人員
-
選擇您的來源選擇:
-
S3 來源 - 從 S3 儲存貯體上傳
-
本機上傳 - 從您的電腦上傳 ZIP 檔案
-
範本 - 使用預先建置的代理程式範本
-
設定您的代理程式設定:
-
選擇要部署的建立代理程式
建立端點
選擇建立端點,為您的代理程式建立新的端點。端點名稱和相關聯的版本將會預先填入。
測試端點
選取端點,然後選擇測試端點以導覽至遊樂場/沙盒進行測試。
執行角色需求
您的代理程式需要具有適當許可的執行角色。如需執行角色和許可的詳細資訊,請參閱 AgentCore 執行期許可。執行角色必須包含基本的 Amazon Bedrock AgentCore 執行期許可、部署套件的 S3 存取許可,以及 CloudWatch Logs 可觀測性許可。
步驟 4:停止工作階段、更新或清除
使用下列其中一種方法停止執行階段工作階段、更新或清除代理程式:
範例
- AgentCore CLI
-
-
再次部署專案以更新執行期:
agentcore deploy
若要刪除專案已部署的資源,請從專案中移除資源並部署更新的組態:
agentcore remove all --yes
agentcore deploy --yes
若要停止作用中的執行期工作階段,請使用 StopRuntimeSession API 操作。
- 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 中刪除 Amazon 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!")
- AWS Management Console
-
更新代理程式
在客服人員詳細資訊頁面中,選擇更新託管,以使用更新的程式碼或組態建立新的版本。
更新端點
從端點資料表中選取端點,然後選擇編輯以更新描述或相關聯的版本。
刪除端點
選取端點,然後選擇刪除 。您需要輸入「刪除」以確認刪除。
刪除代理程式
從客服人員清單或詳細資訊頁面,選取您的客服人員,然後選擇刪除以移除客服人員和所有相關聯的資源。
適用於直接程式碼部署的 Python 特定概念
了解將直接程式碼部署與 Amazon Bedrock AgentCore 執行期搭配使用時的 Python 特定概念。
當您在程式碼中使用 import 陳述式時,Python 執行期會在其搜尋路徑中搜尋目錄,直到找到模組或套件為止。根據預設,執行時間搜尋的第一個位置是解壓縮和掛載 .zip 部署套件的目錄 (/var/task)。
您可以新增下列程式碼片段,查看 AgentCore 執行期代理程式的完整搜尋路徑。
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 檔案。包括 NumPy 和 Pandas 在內的許多熱門 Python 程式庫並非純 Python,且包含以 C 或 C 撰寫的程式碼。當您將包含 C/C 程式碼的程式庫新增至部署套件時,您必須正確建置套件,使其與 AgentCore 執行期執行環境相容。
Python 套件索引 ( PyPI) 上提供的大多數套件都以「輪子」(.whl 檔案)的形式提供。.whl 檔案是一種 ZIP 檔案,其中的內建發佈包含針對特定作業系統和指令集架構預先編譯的二進位檔。若要讓您的部署套件與 Amazon Bedrock AgentCore 執行期相容,請安裝 Linux 作業系統和 arm64 指令集架構的 wheel。
某些套件可能只能作為原始檔發佈。對於這些套件,您需要自行編譯和建置 C/C++ 元件。
若要查看所需套件可用的發佈,請執行以下操作:
如果您的套件只能作為原始檔發佈,則需要自行建置 C/C++ 程式庫。若要讓您的套件與 Amazon Bedrock AgentCore 執行期執行環境相容,您需要將其建置在使用相同 Amazon Linux 作業系統搭配 arm64 指令集的環境中。您可以在 Amazon Elastic Compute Cloud (Amazon EC2) Linux 執行個體中建置套件來執行此操作。
若要了解如何啟動並連線 Amazon EC2 Linux 執行個體,請參閱 Amazon EC2 User Guide 中的 Get started with Amazon EC2。