View a markdown version of this page

開始使用 AgentCore CLI - Amazon Bedrock AgentCore
註冊 AWS 帳戶先決條件步驟 1：安裝 AgentCore CLI步驟 2：建立您的專案步驟 3：在本機測試步驟 4：部署您的代理程式步驟 5：叫用您部署的代理程式將功能新增至您的專案檢視日誌和追蹤疑難排解清除後續步驟

本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

開始使用 AgentCore CLI

此快速入門可讓您使用 AgentCore CLI，在幾分鐘內從零到執行中的代理程式。您將安裝 CLI、堆疊專案、在本機測試 AWS、部署至 並叫用您的代理程式。

在 AgentCore 上建置代理程式的兩種方式，相同的 CLI：

  • 受管繫帶。您在組態檔案中宣告代理程式 （模型、提示、工具、記憶體），而 AgentCore 會為您執行迴圈。無架構、無協同運作程式碼。當您想要從想法到執行中代理程式的最快路由時，路徑良好。進一步了解。

  • 程式碼型代理程式。您可以使用已知的架構 (Strands、LangGraph、Google ADK 或 OpenAI 代理程式） 在 Python 中編寫代理程式迴圈，並將其部署到 AgentCore 執行期。完全控制協同運作邏輯。

此頁面會逐步解說程式碼型流程。如需 繫帶，請參閱什麼是 AgentCore 繫帶。

註冊 AWS 帳戶

註冊 AWS 帳戶

若要開始使用 AWS，您需要 AWS 帳戶。如需建立 AWS 帳戶的資訊，請參閱《AWS 帳戶管理參考指南》中的 帳戶入門。 AWS

先決條件

  • Node.js 20 或更新版本。AgentCore CLI 以 npm 套件的形式分佈。使用 檢查 node --version。如有需要，請從 nodejs.org 安裝 。

  • npm。隨附於 Node.js。

  • 已設定登入資料的 AWS 帳戶。透過 AWS CLI、環境變數或 AWS 設定檔設定 。請參閱設定 AWS CLI。

  • Python 3.10 或更新版本 （適用於代理程式程式碼）。使用 檢查 python3 --version。

  • IAM 許可。您的身分需要許可才能進行 AgentCore API 呼叫，並擔任部署期間使用的 CDK 引導角色。請參閱使用 AgentCore CLI。

  • 模型存取。Amazon Bedrock 預設允許存取基礎模型。可用的模型包括 Amazon Nova、Anthropic Claude、Meta Llama 和 Mistral AI 模型。若要使用非基礎模型，請遵循模型存取步驟。

  • Docker。只有在您選擇Container建置類型時才需要。預設CodeZip建置類型不需要 Docker。

步驟 1：安裝 AgentCore CLI

npm install -g @aws/agentcore

驗證：

agentcore --version
注意

如果報告錯誤而非版本編號，則較舊的 Python agentcore命令會在您的 上陰影 npm 一個PATH。如果您先前已安裝 bedrock-agentcore-starter-toolkit pip 套件，而且在 Windows 上最常見，就會發生這種情況。執行 pip uninstall bedrock-agentcore-starter-toolkit，然後開啟新的終端機，然後再試一次。

若要稍後更新，請重新執行安裝命令或 agentcore update。來源和問題：GitHub 上的 agentcore-cli。

步驟 2：建立您的專案

agentcore create

互動式精靈會先詢問您要建置的內容：

  • Harness - 受管組態型代理程式迴圈。不需要架構或協同運作程式碼。請參閱什麼是 AgentCore 繫帶。

  • 代理程式 - 使用您選擇的架構、部署到 AgentCore 執行期的程式碼型代理程式。

  • 略過 - 建立不含代理程式的專案結構。稍後使用 新增一個agentcore add。

如果您選擇 代理程式，精靈會繼續執行：

  • 架構 - Strands Agents （建議）、LangChain/LangGraph、Google Agent Development Kit 或 OpenAI Agents SDK

  • 模型提供者 - Amazon Bedrock、Anthropic、OpenAI 或 Gemini

  • 記憶體 - 無、短期或長期和短期

  • 組建類型 - CodeZip （預設） 或 Container

您也可以直接傳遞旗標，以建立以程式碼為基礎的代理程式：

agentcore create \
  --project-name MyProject \
  --name MyAgent \
  --language Python \
  --framework Strands \
  --model-provider Bedrock \
  --memory none \
  --build CodeZip

如需所有可用的命令和選項，請參閱 AgentCore CLI 參考。

組建類型

  • CodeZip （預設） 將您的程式碼封裝在 zip 檔案中，並將其上傳至 Amazon S3。此建置類型不需要 Docker。

  • Container 會建置和部署容器映像。此建置類型需要執行中的 Docker 協助程式。

專案結構

agentcore create 為程式碼型代理程式和工具產生共用專案組態和不同的應用程式結構：

範例
Code-based agent
MyProject/
├── AGENTS.md
├── README.md
├── agentcore/
│   ├── agentcore.json
│   ├── aws-targets.json
│   └── cdk/
└── app/
    └── MyAgent/
        ├── main.py
        ├── pyproject.toml
        ├── README.md
        ├── model/
        ├── mcp_client/
        └── skills/
Harness
MyHarnessProject/
├── AGENTS.md
├── README.md
├── agentcore/
│   ├── agentcore.json
│   ├── aws-targets.json
│   └── cdk/
└── app/
    └── MyHarness/
        ├── harness.json
        └── system-prompt.md

金鑰檔案：

  • agentcore/agentcore.json - 主要組態檔案。它定義了您的代理程式、繫帶、記憶體存放區、閘道、登入資料和其他資源。agentcore add 和 agentcore remove命令會管理此檔案。

  • agentcore/aws-targets.json - 要部署 AWS 的帳戶和區域。

  • agentcore/.env.local - 本機秘密，例如模型提供者的 API 金鑰。

  • app/ - 應用程式目錄。程式碼型代理程式包含進入點和相依性。繫帶包含 harness.json和 system-prompt.md。

步驟 3：在本機測試

cd MyProject
agentcore dev

agentcore dev 會建立 Python 虛擬環境、安裝相依性、啟動具有熱重新載入的本機伺服器，並在瀏覽器中開啟代理程式檢查程式，讓您可以與代理程式聊天、檢查追蹤和瀏覽專案資源。程式碼變更會自動收取。

步驟 4：部署您的代理程式

agentcore deploy

部署：

  1. 將您的程式碼封裝成 zip 成品 （如果 ，則建置容器--build Container)

  2. 在幕後使用 AWS CDK 來合成和佈建資源

  3. 為您的代理程式建立 AgentCore 執行期端點

  4. 設定 CloudWatch 記錄和可觀測性

第一次部署需要幾分鐘的時間，而 CDK 會引導您的帳戶。後續部署速度更快。

預覽在不部署的情況下變更的內容：

agentcore deploy --dry-run

檢查狀態：

agentcore status

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

agentcore invoke --prompt "Hello, what can you do?"

如果您的代理程式已設定付款，請在調用時提供付款內容：

agentcore invoke \
  --prompt "Access https://example-x402-merchant.com/paid-api" \
  --payment-instrument-id <INSTRUMENT_ID> \
  --auto-session \
  --payment-user-id user@example.com

這就是迴圈。在 上反覆運算app/MyAgent/main.py、使用 進行測試agentcore dev、使用 部署agentcore deploy、使用 叫用 agentcore invoke。

以程式設計方式叫用代理程式

您可以使用 AWS SDK InvokeAgentRuntime 操作叫用部署的代理程式。取得代理程式執行期 ARN：

agentcore status

建立名為 invoke_agent.py 的檔案。使用代理程式的 ARN 取代代理程式 ARN：

import json
import uuid

import boto3

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

client = boto3.client("bedrock-agentcore")
response = client.invoke_agent_runtime(
    agentRuntimeArn=agent_arn,
    runtimeSessionId=str(uuid.uuid4()),
    payload=json.dumps({"prompt": prompt}).encode(),
    qualifier="DEFAULT",
)

content = []
for chunk in response.get("response", []):
    content.append(chunk.decode("utf-8"))

print(json.loads("".join(content)))

執行程式碼：

python invoke_agent.py

您的身分必須具有 bedrock-agentcore:InvokeAgentRuntime許可。

注意

對於使用 OAuth 的代理程式，向 提出 HTTPS 請求，InvokeAgentRuntime而不是使用 AWS SDK。如需詳細資訊，請參閱使用傳入和傳出授權進行身分驗證和授權。

將功能新增至您的專案

agentcore add 管理 中的資源agentcore.json。在沒有互動式功能表引數的情況下執行它，或直接將資源設為目標。

agentcore add memory        # Store conversation context
agentcore add agent         # Add a second agent to the same project
agentcore add gateway       # Connect external APIs/tools through Gateway
agentcore add credential    # Add an API key for a non-Bedrock provider
agentcore add evaluator     # Quality evaluation
agentcore add payment-manager   # Payments: create a payment manager
agentcore add payment-connector # Payments: link a payment provider

每個新增命令會堆疊組態，並提示必要值。新增後，執行 agentcore deploy以佈建。

深入探討您可以連接的功能：

檢視日誌和追蹤

# Stream recent logs
agentcore logs

# Filter
agentcore logs --since 30m --level error
agentcore logs --query "timeout"

# List recent traces
agentcore traces list

# Get a specific trace
agentcore traces get <trace-id>

疑難排解

許可遭拒錯誤

使用 驗證您的登入資料aws sts get-caller-identity。請確定您的身分具有使用 AgentCore CLI 的許可。

拒絕模型存取

Amazon Bedrock 預設允許存取基礎模型。若要使用非基礎模型，請遵循模型存取步驟。

部署錯誤

執行 agentcore deploy --verbose以顯示資源層級部署事件。CLI 會檢查 AWS CDK 引導狀態。如果需要引導，互動式部署會要求確認。 會在沒有提示的情況下agentcore deploy --yes核准引導操作。

連接埠已在使用中

執行 agentcore dev --port 3000 以使用不同的本機連接埠。

組態驗證錯誤

執行 agentcore validate 以檢查專案組態。

如需詳細資訊，請參閱疑難排解 Amazon Bedrock AgentCore 執行期。

清除

agentcore remove all
agentcore deploy

remove all 會重設組態。追蹤會deploy偵測空白狀態，並縮減您帳戶中的資源。

後續步驟