先決條件步驟 1：安裝 AgentCore CLI 步驟 2：建立您的代理程式專案步驟 3：在本機測試您的代理程式步驟 4：啟用代理程式的可觀測性步驟 5：部署至 Amazon Bedrock AgentCore 執行期步驟 6：測試您部署的代理程式步驟 7：叫用您部署的代理程式步驟 8：清理標記您的資源常見問題與解決方案進階選項（選用）

開始使用 AgentCore CLI

本教學課程說明如何使用 AgentCore CLI 在 Amazon Bedrock AgentCore 執行期上建立、部署和叫用 Python 代理程式。

AgentCore CLI 是一種命令列工具，可堆疊代理程式專案、將它們部署到 Amazon Bedrock AgentCore 執行期，以及叫用它們。您可以使用 CLI 搭配熱門的 Python 代理程式架構，例如 Strands Agents 、LangChain/LangGraph、Google ADK 和 OpenAI Agents。本教學課程使用 Strands Agents。

如需代理程式使用之 HTTP 通訊協定的相關資訊，請參閱 HTTP 通訊協定合約。

先決條件

開始之前，請確定您已：

AWS 已設定登入資料的帳戶。若要設定您的 AWS 登入資料，請參閱 CLI AWS 中的組態和登入資料檔案設定。
已安裝 Node.js 20+。AgentCore CLI 以 npm 套件的形式分佈。
已安裝 Python 3.10+。產生的代理程式程式碼是 Python。
AWS 已安裝 CDK。CLI 使用 AWS CDK 來部署資源。如需詳細資訊，請參閱 AWS CDK 入門。
AWS 許可 ：若要使用 AgentCore CLI 建立和部署代理程式，您必須擁有適當的許可。如需詳細資訊，請參閱使用 AgentCore CLI。
模型存取 ：在 Amazon Bedrock 主控台中啟用 Anthropic Claude Sonnet 4.0 （如果使用 Bedrock 作為模型提供者）。如需搭配 Strands Agents 使用不同模型的詳細資訊，請參閱 Strands Agents SDK 文件中的模型提供者一節。

步驟 1：安裝 AgentCore CLI

全域安裝 AgentCore CLI：


npm install -g @aws/agentcore

驗證安裝：


agentcore --help

您應該會看到類似下列的輸出：


Usage: agentcore [options] [command]

Build and deploy Agentic AI applications on AgentCore

Options:
  -V, --version                output the version number
  -h, --help                   Display help

Commands:
  add [subcommand]             Add resources (agent, evaluator, online-eval,
                               memory, identity, target)
  dev|d [options]              Launch local development server with hot-reload.
  deploy|p [options]           Deploy project infrastructure to AWS via CDK.
  create [options]             Create a new AgentCore project
  evals                        View past eval run results.
  fetch                        Fetch access info for deployed resources.
  help                         Display help topics
  invoke|i [options] [prompt]  Invoke a deployed agent endpoint.
  logs|l [options]             Stream or search agent runtime logs.
  package|pkg [options]        Package agent artifacts without deploying.
  pause                        Pause an online eval config.
  remove [subcommand]          Remove resources from project config.
  resume                       Resume a paused online eval config.
  run                          Run on-demand evaluation.
  status|s [options]           Show deployed resource details and status.
  traces|t                     View and download agent traces.
  update [options]             Check for and install CLI updates
  validate [options]           Validate agentcore/ config files.

步驟 2：建立您的代理程式專案

使用 agentcore create命令來堆疊新的代理程式專案：

範例

agentcore create 命令接受下列旗標：

--name – 專案名稱（英數字元，以字母開頭，最多 36 個字元）。
--framework – 代理程式架構。支援的值：Strands、LangChain_LangGraph、GoogleADK、OpenAIAgents。
--protocol – 通訊協定模式。支援的值： HTTP（預設）MCP、、A2A。
--build – 建置類型。支援的值： CodeZip（預設）、Container。
--model-provider – 模型提供者。支援的值：Bedrock、Anthropic、OpenAI、Gemini。
--memory – 記憶體組態。支援的值：none、shortTerm、longAndShortTerm。

命令會產生具有下列結構的專案目錄：


MyAgent/
  agentcore/
    agentcore.json        # Project and agent configuration
    aws-targets.json      # AWS account and region targets
    .env.local            # Local environment variables (gitignored)
  app/
    MyAgent/
      main.py             # Agent entrypoint
      pyproject.toml      # Python dependencies
  README.md

agentcore/agentcore.json 檔案包含您的專案和代理程式組態。app/MyAgent/main.py 檔案包含使用您所選架構的入門代理程式程式碼。

若要將付款功能新增至您的專案，請執行：


agentcore add payment-manager --name MyPayments --auto-payment --default-spend-limit 5.00
agentcore add payment-connector --manager MyPayments --name MyConnector --provider CoinbaseCDP \
  --api-key-id <KEY_ID> --api-key-secret <KEY_SECRET> --wallet-secret <WALLET_SECRET>

這會在您的代理程式AgentCorePaymentsPlugin中設定，並在部署時佈建付款基礎設施。如需完整的工作流程，請參閱付款快速入門。

步驟 3：在本機測試您的代理程式

部署至之前 AWS，請使用開發伺服器在本機測試您的代理程式。首先，將變更為專案目錄：


cd MyAgent

如果您選取的模型提供者需要 API 金鑰 (OpenAI、Anthropic 或 Gemini)，請確定金鑰已在中設定agentcore/.env.local。

啟動本機開發伺服器：

範例

agentcore dev 命令：

在 Web 瀏覽器中開啟代理程式檢查程式
自動建立 Python 虛擬環境並安裝相依性
啟動模擬 AgentCore 執行期環境的本機伺服器
http://localhost:8080 根據預設在上執行（使用 -p 變更連接埠）

若要即時檢視伺服器日誌（非互動式模式），請使用 --logs旗標：


agentcore dev --logs

在個別終端機中，叫用您的本機代理程式：


agentcore dev "Hello, tell me a joke"

傳遞提示會將其傳送至執行中的本機開發伺服器。使用查看即時串流的--stream回應。

步驟 4：啟用代理程式的可觀測性

Amazon Bedrock AgentCore 可觀測性可協助您追蹤、偵錯和監控您在 Amazon Bedrock AgentCore 執行期中託管的代理程式。首先，遵循啟用 Amazon Bedrock AgentCore 執行時間可觀測性中的指示來啟用 CloudWatch 交易搜尋。若要觀察您的代理程式，請參閱檢視 Amazon Bedrock AgentCore 代理程式的可觀測性資料。

部署代理程式之後，您可以使用 AgentCore CLI 串流日誌和檢視追蹤：


# Stream agent logs
agentcore logs

# List recent traces
agentcore traces list

步驟 5：部署至 Amazon Bedrock AgentCore 執行期

將您的代理程式部署到 Amazon Bedrock AgentCore 執行期：

範例

若要預覽部署而不進行變更，請使用 --dry-run旗標：


agentcore deploy --dry-run

agentcore deploy 命令：

讀取您的 agentcore/agentcore.json和 agentcore/aws-targets.json組態
封裝您的代理程式程式碼（做為 CodeZip 封存檔或 Docker 容器，視您的建置類型而定）
使用 AWS CDK 合成和部署 CloudFormation 資源
建立必要的 AWS 資源 (IAM 角色、Amazon Bedrock AgentCore 執行期等）

-v 用於顯示資源層級部署事件的詳細輸出。使用 -y可在沒有提示的情況下自動確認部署。

如果部署失敗，請檢查是否有常見問題。

步驟 6：測試您部署的代理程式

部署完成後，叫用您部署的代理程式：

範例

如果您在回應中看到玩笑，表示您的代理程式正在 Amazon Bedrock AgentCore 執行期中執行，並且可以叫用。如果沒有，請檢查是否有常見問題。

步驟 7：叫用您部署的代理程式

範例

AgentCore CLI

使用提示叫用已部署的代理程式：
```
agentcore invoke --runtime MyAgent "Hello, what can you do?"
```
即時串流回應：
```
agentcore invoke --runtime MyAgent "Tell me a joke" --stream
```
在agentcore invoke無提示的情況下執行以開啟互動式聊天 TUI，依預設串流回應並自動維護您的工作階段。

AWS Python SDK (Boto3)

您也可以使用 AWS SDK InvokeAgentRuntime 操作叫用代理程式。若要取得已部署代理程式的 ARN，請使用 agentcore status命令：
```
agentcore status
```
使用下列 boto3 （適用於 Python 的AWS SDK) 程式碼來叫用您的代理程式。將客服人員 ARN 取代為您客服人員的 ARN。請確定您具有 bedrock-agentcore:InvokeAgentRuntime 許可。建立名為的檔案invoke_agent.py，並新增下列程式碼：
```
import json
import uuid
import boto3

agent_arn = "Agent ARN"
prompt = "Tell me a joke"

# Initialize the Amazon Bedrock AgentCore client
agent_core_client = boto3.client('bedrock-agentcore')

# Prepare the payload
payload = json.dumps({"prompt": prompt}).encode()

# Invoke the agent
response = agent_core_client.invoke_agent_runtime(
    agentRuntimeArn=agent_arn,
    runtimeSessionId=str(uuid.uuid4()),
    payload=payload,
    qualifier="DEFAULT"
)

content = []
for chunk in response.get("response", []):
    content.append(chunk.decode('utf-8'))
print(json.loads(''.join(content)))
```
開啟終端機視窗，並使用下列命令執行程式碼：
```
python invoke_agent.py
```
如果成功，您應該會在回應中看到一則笑話。如果呼叫失敗，請使用檢查日誌agentcore logs或在 Amazon CloudWatch 中檢視日誌。

注意
如果您打算將代理程式與 OAuth 整合，則無法使用 AWS SDK 呼叫 InvokeAgentRuntime 。請改為向提出 HTTPS InvokeAgentRuntime 請求。如需詳細資訊，請參閱使用傳入身分驗證和傳出身分驗證進行身分驗證和授權。

步驟 8：清理

如果您不想再在 Amazon Bedrock AgentCore 執行期中託管代理程式，請移除部署 AWS 的資源。首先，從本機組態中移除所有資源：

範例

然後再次部署以縮減 AWS 資源：

範例

remove all 命令會在保留agentcore/aws-targets.json和部署狀態時重設agentcore/agentcore.json組態檔案。後續會deploy偵測已移除的資源，並縮減對應的 AWS 資源。

標記您的資源

部署之後，您可以使用 AgentCore CLI 檢查資源的狀態：

範例

您也可以在 AWS 主控台中檢視您的資源：

資源	Location
客服人員日誌	CloudWatch → 日誌群組 → `/aws/bedrock-agentcore/runtimes/{agent-id}-DEFAULT`
CloudFormation 堆疊	CloudFormation → 堆疊 → 搜尋您的專案名稱
IAM 角色	IAM → 角色 → 搜尋 "BedrockAgentCore"
S3 資產 (CodeZip)	S3 → 儲存貯體 → CDK 預備儲存貯體

常見問題與解決方案

開始使用 AgentCore CLI 時的常見問題和解決方案。如需更多故障診斷資訊，請參閱故障診斷 Amazon Bedrock AgentCore 執行期。

許可遭拒錯誤

驗證您的 AWS 登入資料和許可：

驗證 AWS 登入資料： aws sts get-caller-identity
檢查是否已連接必要的政策
檢閱來電者許可政策以了解詳細需求

拒絕模型存取

在 Bedrock 主控台中啟用模型存取：

在 Bedrock 主控台中啟用 Anthropic Claude 4.0
確定您位於正確的 AWS 區域（預設為us-west-2)

CDK 部署錯誤

檢查 CDK 設定和許可：

請確定您已為 CDK 啟動 AWS 帳戶： cdk bootstrap
驗證您的發起人許可包括 CloudFormation 和 CDK 存取
agentcore deploy -v 使用的詳細輸出來識別失敗的資源

連接埠 8080 使用中（僅限本機）

尋找並停止使用連接埠 8080 的程序：

使用 lsof -ti:8080取得使用連接埠 8080 的程序清單。

使用 kill -9 PID停止程序。將 PID 取代為程序 ID。

或者，在不同連接埠上啟動開發伺服器： agentcore dev -p 3000

區域不相符

使用驗證 AWS 區域aws configure get region，並確保中的區域agentcore/aws-targets.json符合您資源的部署位置。

組態驗證錯誤

驗證您的組態檔案：

使用 agentcore validate檢查 agentcore/agentcore.json和相關組態檔案中的語法或結構描述錯誤。

進階選項（選用）

使用 agentcore create 建立代理程式專案之後，您可以使用 agentcore add命令來擴展專案。如需完整的 CLI 參考，請參閱 AgentCore CLI 文件。

組建類型

建立專案時，請選擇符合您需求的建置類型：

CodeZip （預設）

您的代理程式程式碼會封裝為 zip 封存檔並上傳至 S3。這是最簡單的選項，不需要 Docker：


agentcore create --name MyAgent --framework Strands --model-provider Bedrock --memory none --build CodeZip

容器

您的代理程式程式碼會封裝為 Docker 容器映像。當您需要自訂系統層級相依性或特定基礎映像時，請使用此選項：


agentcore create --name MyAgent --framework Strands --model-provider Bedrock --memory none --build Container

將資源新增至您的專案

您可以在建立之後將其他資源新增至您的專案：


# Add another agent to the same project
agentcore add agent --name SecondAgent --language Python --framework Strands --model-provider Bedrock

# Add a memory store for conversational context
agentcore add memory --name MyMemory --strategies SEMANTIC

# Add an API key credential for external services
agentcore add credential --name MyApiKey --type api-key --api-key your-api-key

# Add a payment manager for x402 microtransactions
agentcore add payment-manager --name MyPayments --auto-payment --default-spend-limit 5.00

新增資源後，請執行 agentcore deploy以佈建新的資源 AWS。

為什麼選擇 ARM64？

Amazon Bedrock AgentCore 執行期在 ARM64 (AWS Graviton) 上執行。AgentCore CLI 會自動處理 CodeZip 和容器建置類型的架構相容性。對於容器組建，只有為 ARM64 建置的映像在部署到 Amazon Bedrock AgentCore 執行期時才能運作。

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

AgentCore 執行期入門

AgentCore CLI (TypeScript) 入門