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

AgentCore 中的政策入門

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

先決條件

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

AgentCore CLI 會在部署期間檢查 CDK 引導堆疊。如果需要引導，互動式部署會要求確認。使用 agentcore deploy --yes 自動授權它。

步驟 1：設定和安裝

安裝 AgentCore CLI：

npm install -g @aws/agentcore

建立新的 AgentCore 專案：

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

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

新增閘道

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

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

使用定義退款處理工具的工具結構描述，將您的 Lambda 函數註冊為閘道目標。在專案目錄中建立包含下列內容refund_tools.json的檔案：

[
  {
    "name": "process_refund",
    "description": "Process a customer refund request for a given dollar amount",
    "inputSchema": {
      "type": "object",
      "description": "Input for processing a refund",
      "properties": {
        "amount": {
          "type": "integer",
          "description": "The refund amount in dollars"
        }
      },
      "required": ["amount"]
    }
  }
]

新增政策引擎

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

建立 Cedar 政策

直接提供 Cedar 政策檔案。Cedar 不允許政策陳述式中的萬用字元資源。這需要兩階段部署：先在沒有政策的情況下部署，以建立閘道，然後擷取閘道 ARN。然後新增政策並重新部署。

或者，在步驟 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
};

政策使用：

將政策連接至閘道

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

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

步驟 3：部署

將所有資源部署到 AWS：

agentcore deploy

AgentCore CLI 會建立閘道、註冊 Lambda 目標，以及佈建政策引擎。如果您提供以 ARN 為基礎的 Cedar 政策檔案，請在此部署之後新增它，然後再次執行 agentcore 部署以連接它。此程序每次部署大約需要 2-3 分鐘。

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

agentcore status

步驟 4：測試政策

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

Agentcore 狀態輸出中顯示的閘道 URL 是基本端點。MCP 請求會前往該端點上的/mcp路徑，因此請在傳送請求之前附加/mcp到 URL。

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

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

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

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

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

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

您已建置的內容

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

疑難排解

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

清除

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

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

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