Python 的直接程式碼部署
直接程式碼部署可讓您將 Python 型代理程式帶到 Amazon Bedrock AgentCore 執行期，只需在 .zip 檔案存檔中封裝代理程式程式碼及其相依性即可。您的代理程式仍然需要遵循 AgentCore 執行期要求：具有一個進入點 .py 檔案，該檔案使用來自 Amazon Bedrock AgentCore Python SDK 的@app.entrypoint註釋，或實作 /invocations POST 和 /ping GET 伺服器端點。
先決條件
開始前，請確保您具備以下條件：
步驟 1：設定專案並安裝相依性
使用以下命令初始化您的專案：
uv init agentcore_runtime_direct_deploy --python 3.13
cd agentcore_runtime_direct_deploy
新增核心套件：
uv add bedrock-agentcore strands-agents
安裝 AgentCore CLI （以下步驟需要）：
npm install -g @aws/agentcore
套件描述：
-
bedrock-agentcore - 用於建置 AI 代理器的 Amazon Bedrock AgentCore 開發套件
-
strands-agents - Strands Agents SDK
-
@aws/agentcore - AgentCore CLI
或者，執行 uv add aws-opentelemetry-distro以啟用 Amazon Bedrock AgentCore 可觀測性追蹤。
Uv 會自動建立具有相依性pyproject.toml的檔案、具有相依性關閉uv.lock的檔案和.venv目錄。
步驟 2：建立您的代理程式專案
使用 agentcore create命令，使用您選擇的架構來設定骨架代理程式專案：
agentcore create
命令會提示您：
此命令會產生：
步驟 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 執行期。如需詳細資訊，請參閱 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 執行期相容的 wheel，您可以使用 uv pip --python-platform選項。AgentCore Runtime 僅支援 arm64 指令集架構，請執行下列命令。以您所使用的 Pytho 執行期版本取代 --python 3.x。
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 CLI 將負責上述步驟來建立 .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 儲存貯體已存在。請依照此處 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 檔案
-
範本 - 使用預先建置的代理程式範本
-
設定您的代理程式設定：
-
選擇要部署的建立代理程式
建立端點
選擇建立端點，為您的代理程式建立新的端點。端點名稱和相關聯的版本將會預先填入。
測試端點
選取端點，然後選擇測試端點以導覽至遊樂場/沙盒進行測試。
執行角色需求
您的代理程式需要具有適當許可的執行角色。如需執行角色和許可的詳細資訊，請參閱 AgentCore 執行期許可。執行角色必須包含基本 Amazon Bedrock AgentCore 執行期許可、部署套件的 S3 存取許可，以及 CloudWatch Logs 可觀測性許可。
步驟 6：停止工作階段、更新或清除
使用下列其中一種方法停止執行階段工作階段、更新或清除代理程式：
範例
- AgentCore CLI
-
-
若要更新先前部署的 AgentCore 執行期，請執行：
agentcore deploy
若要在可設定 IdleRuntimeSessionTimeout（預設為 15 分鐘） 之前停止執行中的工作階段，並節省任何潛在的失控成本，請使用 StopRuntimeSession API 操作。AgentCore CLI 目前不支援直接停止工作階段。
若要刪除與 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 中刪除 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!")
- 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 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。
