View a markdown version of this page

AgentCore 中的政策入門 - Amazon Bedrock AgentCore
先決條件步驟 1：設定和安裝步驟 2：使用政策引擎新增閘道步驟 3：部署步驟 4：測試政策您已建置的內容疑難排解清除

AgentCore 中的政策入門

在本教學課程中，您將了解如何在 AgentCore 中設定政策，並使用 AgentCore CLI 將其與 Amazon Bedrock AgentCore Gateway 整合。您將使用 Cedar 政策建立退款處理工具，以強制執行退款金額的業務規則。

先決條件

開始之前，請確定您有下列項目：

  • AWS 已設定登入資料的帳戶。若要設定登入資料，您可以依照 CLI AWS 入門中的步驟安裝和使用 AWS 命令列界面。

  • 已安裝 Node.js 18+

  • 建立角色、Lambda 函數、政策引擎和使用 Amazon Bedrock AgentCore 的 IAM 許可

  • 處理退款請求的 Lambda 函數。您可以使用現有的 函數，或為此教學課程建立一個函數。請注意用於步驟 2 的函數 ARN。

步驟 1：設定和安裝

安裝 AgentCore CLI：

npm install -g @aws/agentcore

建立新的 AgentCore 專案：

範例
AgentCore CLI

  1. agentcore create --name PolicyDemo --defaults
cd PolicyDemo

    --defaults 旗標會使用預設 Python Strands 代理程式建立專案。cd 命令會移至必須執行後續命令的專案目錄。

Interactive

  1. 您也可以agentcore create在沒有旗標的情況下執行 ，以使用互動式精靈。精靈會引導您選取專案名稱、客服人員架構、模型提供者和其他選項。建立專案後，請使用 cd PolicyDemo 將 變更為專案目錄。

步驟 2：使用政策引擎新增閘道

使用 AgentCore CLI 將閘道、Lambda 函數目標和政策引擎新增至您的專案。

新增閘道

建立沒有傳入授權的閘道 （為了簡化本教學課程），並將您的代理程式連接到閘道：

範例
AgentCore CLI

  1. agentcore add gateway --name PolicyGateway --authorizer-type NONE --runtimes PolicyDemo
Interactive

  1. 執行 agentcore以開啟 TUI，然後選取新增，然後選擇閘道 ：

  2. 輸入閘道名稱：

    閘道精靈：輸入名稱

  3. 選取授權方類型。在本教學課程中，選擇 NONE ：

    閘道精靈：選取 NONE 授權方

  4. 設定進階選項或接受預設值：

    閘道精靈：進階組態

  5. 檢閱組態，然後按 Enter 鍵確認：

    閘道精靈：檢閱組態

使用退款工具新增 Lambda 函數目標

使用定義退款處理工具的工具結構描述，將您的 Lambda 函數註冊為閘道目標：

範例
AgentCore CLI

  1. agentcore add gateway-target --name RefundTarget --type lambda-function-arn \
  --lambda-arn ++<YOUR_LAMBDA_ARN>++ \
  --tool-schema-file refund_tools.json \
  --gateway PolicyGateway

    <YOUR_LAMBDA_ARN> 將 取代為 Lambda 函數的 ARN。refund_tools.json 檔案會定義退款工具的工具結構描述。

Interactive

  1. 執行 agentcore以開啟 TUI，然後選取新增，然後選擇閘道目標 ：

  2. 輸入目標名稱。

  3. 選取 Lambda 函數做為目標類型：

    閘道目標精靈：選取 Lambda 函數

  4. 輸入 Lambda ARN 和工具結構描述檔案路徑，然後確認。

新增政策引擎

建立政策引擎，並以 ENFORCE 模式將其連接至閘道：

範例
AgentCore CLI

  1. agentcore add policy-engine --name RefundPolicyEngine \
  --attach-to-gateways PolicyGateway \
  --attach-mode ENFORCE
Interactive

  1. 執行 agentcore以開啟 TUI，然後選取新增，然後選擇政策引擎 ：

  2. 輸入政策引擎名稱：

    政策引擎精靈：輸入名稱

  3. 選取要連接政策引擎的閘道：

    政策引擎精靈：連接閘道

  4. 選擇強制執行模式。選取 ENFORCE：

    政策引擎精靈：選取強制執行模式

建立 Cedar 政策

直接提供 Cedar 政策檔案：

agentcore add policy --name RefundLimit \
  --engine RefundPolicyEngine \
  --source refund_policy.cedar
注意

參考 resource 欄位中特定閘道 ARNs Cedar 政策 （如以下範例所示） 需要兩階段部署：先在沒有政策的情況下部署，以建立閘道，然後從 agentcore 狀態擷取閘道 ARN、更新 Cedar 檔案，並在重新部署之前新增政策。Cedar 不允許政策陳述式中的萬用字元資源。

或者，在步驟 3 部署資源之後，您可以從自然語言描述產生 Cedar 政策：

agentcore add policy --name RefundLimit \
  --engine RefundPolicyEngine \
  --generate "Only allow refunds under 1000 dollars" \
  --gateway PolicyGateway

--generate 旗標需要先部署閘道，因為它會呼叫需要閘道 ARN 才能將自然語言轉換為 Cedar 的 AWS API。此方法會自動解析閘道 ARNs，使其成為建立政策的最簡單路徑。

了解設定

上面的 CLI 命令會在 AgentCore 專案中設定數個資源。以下是每個元件的詳細說明。

建立閘道

agentcore add Gateway 命令會建立閘道，做為您的 MCP 伺服器端點。設定 會--authorizer-type NONE停用本教學課程中的傳入授權，以求簡化。在生產環境中，使用 IAM 或 JWT 授權來保護您的閘道。

新增 Lambda 目標

agentcore add gateway-target 命令會將 Lambda 函數註冊為閘道中的目標。工具結構描述檔案定義代理程式可以傳遞給函數的輸入，例如退款金額。

建立政策引擎

agentcore add policy-engine 命令會建立政策引擎，這是評估和授權客服人員工具呼叫的 Cedar 政策集合。政策引擎會在閘道界限攔截所有請求，並根據定義的政策決定是否允許或拒絕每個動作。這可在代理程式程式碼之外提供確定性授權，無論代理程式的實作方式為何，都能確保一致的安全強制執行。

建立 Cedar 政策

Cedar 是一種開放原始碼政策語言，由 開發 AWS ，用於撰寫授權政策。agentcore add policy 命令會建立 Cedar 政策，透過閘道管理工具呼叫。您可以使用 從自然語言描述產生政策--generate，或直接使用 提供 Cedar 政策檔案--source。

以下是允許低於 1000 USD 退款的 Cedar 政策範例：

permit(principal,
  action == AgentCore::Action::"RefundTarget___process_refund",
  resource == AgentCore::Gateway::"<gateway-arn>")
when {
  context.input.amount < 1000
};

政策使用：

  • permit – 允許動作 (Cedar 也支援forbid拒絕動作）

  • principal – 提出請求的實體

  • action – 正在呼叫的特定工具 (RefundTarget___process_refund)

  • resource – 套用政策的閘道執行個體

  • when 條件 – 其他需求 （金額必須 < 1000 美元）

將政策連接至閘道

agentcore 新增政策引擎命令上的 --attach-to-gateways和 --attach-mode ENFORCE旗標會以 ENFORCE 模式將政策引擎連接至閘道。在此模式中：

  • 系統會針對所有政策攔截和評估每個工具呼叫

  • 根據預設，除非明確允許，否則所有動作都會遭到拒絕

  • 如果任何forbid政策相符，則會拒絕存取 （禁止wins 語意）

  • 政策決策會記錄到 CloudWatch 以進行監控和合規

這可確保透過閘道執行的所有代理程式操作都受您的安全政策管理。

步驟 3：部署

將所有資源部署到 AWS：

agentcore deploy

AgentCore CLI 會建立閘道、註冊 Lambda 目標、佈建政策引擎，以及連接 Cedar 政策。此程序大約需要 2-3 分鐘。

部署完成後，您可以驗證資源的狀態：

agentcore status

步驟 4：測試政策

透過傳送請求到閘道來測試政策。由於閘道使用 --authorizer-type NONE ，您可以直接使用 curl 傳送請求。

測試 1：退款 500 美元 （應允許）

500 USD 的退款金額低於 1000 USD 的限制，因此政策引擎允許請求：

curl -X POST ++<GATEWAY_URL>++ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"RefundTarget___process_refund","arguments":{"amount":500}}}'

測試 2：退款 2000 美元 （應拒絕）

2000 USD 的退款金額超過 1000 USD 的限制，因此政策引擎拒絕請求：

curl -X POST ++<GATEWAY_URL>++ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"RefundTarget___process_refund","arguments":{"amount":2000}}}'
注意

<GATEWAY_URL> 將 取代為 agentcore 狀態輸出中顯示的閘道 URL。

您已建置的內容

透過本教學課程，您已建立：

  • MCP 伺服器 （閘道） – 工具的受管端點

  • Lambda 目標 – 在閘道中註冊的退款處理工具

  • 政策引擎 – 以 Cedar 為基礎的政策評估系統

  • Cedar 政策 – 允許低於 1000 美元的退款的控管規則

疑難排解

如果您在設定或測試期間遇到問題，請參閱下列常見問題和解決方案：

問題 解決方案

「AccessDeniedException」

檢查 bedrock-agentcore 的 IAM 許可：*

閘道未回應

部署後等待 30-60 秒以進行 DNS 傳播

部署失敗

執行 agentcore 狀態以檢查資源狀態並檢閱錯誤訊息

政策未強制執行

透過執行 agentcore 狀態，確認政策引擎已連接在 ENFORCE 模式中

部署期間的雪松驗證錯誤

Cedar 政策必須使用特定資源 ARNs — 萬用字元資源 （例如 permit(principal, action, resource); ) 會遭到拒絕。在 Cedar 政策的 resource 欄位中使用來自 agentcore 狀態的閘道 ARN。

工具呼叫意外遭拒

政策引擎正在強制執行，且 Cedar 政策拒絕請求。確認政策的 action和 resource 欄位符合正在進行的工具呼叫。

部署失敗並出現政策驗證錯誤

預設驗證模式會同時FAIL_ON_ANY_FINDINGS執行結構描述檢查和語意驗證，如果其中一個模式產生問題清單，則會拒絕政策。如果您不需要語意驗證，您可以將驗證模式設定為僅IGNORE_ALL_FINDINGS執行結構描述檢查。針對生產，修正 Cedar 政策以同時通過結構描述檢查和語意驗證。

清除

若要移除本教學課程中建立的資源，請同時移除閘道和政策引擎，然後重新部署：

agentcore remove gateway --name PolicyGateway
agentcore remove policy-engine --name RefundPolicyEngine
agentcore deploy

移除閘道不會自動移除其連接的政策引擎。您必須使用 分別移除政策引擎agentcore remove policy-engine。