# 政策入门 AgentCore
在本教程中，您将学习如何使用 AgentCore CLI 在中设置策略 AgentCore 并将其与 Amazon Bedrock AgentCore Gateway 集成。您将使用 Cedar 政策创建退款处理工具，以强制执行退款金额的业务规则。
**Topics**
+ [先决条件](#policy-getting-started-prerequisites)
+ [步骤 1：设置和安装](#policy-getting-started-setup)
+ [步骤 2：添加带有策略引擎的网关](#policy-getting-started-create-script)
+ [步骤 3：部署](#policy-getting-started-run-setup)
+ [步骤 4：测试策略](#policy-getting-started-test)
+ [你建造了什么](#policy-getting-started-results)
+ [问题排查](#policy-getting-started-troubleshooting)
+ [清理](#policy-getting-started-cleanup)
## 先决条件
在开始之前，请确保您具备以下条件：
+ AWS 已配置凭据的@@ **账户**。要配置凭据，您可以按照 [AWS CLI 入门](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html)中的步骤安装和使用 AWS 命令行界面。
+ Node.js 已@@ **安装 18 个以上**
+ 用于创建角色、Lambda 函数、策略引擎和使用 Amazon Bedrock 的 IA@@ **M 权限** AgentCore
+ **用于处理退款请求的 Lambda 函数**。您可以使用现有函数或为本教程创建一个函数。记下在步骤 2 中使用的函数 ARN。
## 步骤 1：设置和安装
安装 C AgentCore LI：
```
npm install -g @aws/agentcore
```
创建新 AgentCore 项目：
**Example**
1.
```
agentcore create --name PolicyDemo --defaults
cd PolicyDemo
```
该`--defaults`标志使用默认 Python Strands 代理创建项目。c **d** 命令移到必须运行后续命令的项目目录中。
1. 您也可以在`agentcore create`没有标志的情况下运行以使用交互式向导。该向导将指导您选择项目名称、代理框架、模型提供者和其他选项。创建项目后，使用 c **d** 进入项目目录 PolicyDemo。
## 步骤 2：添加带有策略引擎的网关
使用 AgentCore CLI 向您的项目添加网关、Lambda 函数目标和策略引擎。
**添加网关**
创建一个没有入站授权的网关（为了简单起见本教程），然后将您的代理附加到该网关：
**Example**
1.
```
agentcore add gateway --name PolicyGateway --authorizer-type NONE --runtimes PolicyDemo
```
1. 运行打开 `agentcore` TUI，然后选择**添加**并选择**网关**：
1. 输入网关名称：
1. 选择授权者类型。在本教程中，请选择 “**无**”：
1. 配置高级选项或接受默认值：
1. 查看配置并按 E **nter** 进行确认：
**使用退款工具添加 Lambda 函数目标**
使用定义退款处理工具的工具架构将您的 Lambda 函数注册为网关目标：
**Example**
1.
```
agentcore add gateway-target --name RefundTarget --type lambda-function-arn \
--lambda-arn ++++ \
--tool-schema-file refund_tools.json \
--gateway PolicyGateway
```
``替换为您的 Lambda 函数的 ARN。该`refund_tools.json`文件定义了退款工具的工具架构。
1. 运行`agentcore`打开 TUI，然后选择**添加**并选择**网关目标**：
1. 输入目标名称。
1. 选择 **Lambda 函数**作为目标类型：
1. 输入 Lambda ARN 和工具架构文件路径，然后进行确认。
**添加策略引擎**
创建策略引擎并在强制模式下将其附加到网关：
**Example**
1.
```
agentcore add policy-engine --name RefundPolicyEngine \
--attach-to-gateways PolicyGateway \
--attach-mode ENFORCE
```
1. 运行`agentcore`打开 TUI，然后选择**添加**并选择**策略引擎**：
1. 输入策略引擎名称：
1. 选择要将策略引擎连接到的网关：
1. 选择强制模式。选择 “**强制**”：
**创建 Cedar 政策**
直接提供 Cedar 政策文件：
```
agentcore add policy --name RefundLimit \
--engine RefundPolicyEngine \
--source refund_policy.cedar
```
**注意**
在`resource`现场引用特定网关 ARN 的 Cedar 策略（如下例所示）需要分两个阶段部署：首先在没有创建网关的策略的情况下进行部署，然后从 **agentcore 状态**检索网关 ARN，更新 Cedar 文件，并在重新部署之前添加策略。Cedar 不允许在政策声明中使用通配符资源。
或者，在步骤 3 中部署资源后，您可以根据自然语言描述生成 Cedar 策略：
```
agentcore add policy --name RefundLimit \
--engine RefundPolicyEngine \
--generate "Only allow refunds under 1000 dollars" \
--gateway PolicyGateway
```
该`--generate`标志要求首先部署网关，因为它调用的 AWS API 需要网关 ARN 将自然语言转换为 Cedar。这种方法可以自动解析网关 ARN，使其成为创建策略的最简单途径。
### 了解设置
上面的 CLI 命令在您的 AgentCore 项目中配置多个资源。以下是每个组件的详细说明。
**Topics**
+ [创建网关](#policy-create-gateway)
+ [添加 Lambda 目标](#policy-add-lambda-target)
+ [创建策略引擎](#policy-create-policy-engine)
+ [创建 Cedar 政策](#policy-create-cedar-policy)
+ [将策略附加到网关](#policy-attach-to-gateway)
#### 创建网关
**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 polic** y 命令创建一个 Cedar 策略，用于管理通过网关进行的工具调用。您可以使用根据自然语言描述生成策略，也可以直接使用`--generate`提供 Cedar 策略文件。`--source`
以下是 Cedar 政策示例，该政策允许退款低于 1000 美元：
```
permit(principal,
action == AgentCore::Action::"RefundTarget___process_refund",
resource == AgentCore::Gateway::"")
when {
context.input.amount < 1000
};
```
该政策使用：
+ `permit`— 允许操作（Cedar 还支持`forbid`拒绝操作）
+ `principal`— 提出请求的实体
+ `action`— 正在调用的特定工具（RefundTarget\_\_\_process\_refund）
+ `resource`— 策略适用的网关实例
+ `when`状况-其他要求（金额必须小于 1000 美元）
#### 将策略附加到网关
**agentcore add policy-engine 命令上的`--attach-to-gateways`和`--attach-mode ENFORCE`标志在强制模式下将策略**引擎附加到网关。在此模式中：
+ 每个工具调用都会被拦截并根据所有策略进行评估
+ 默认情况下，除非明确允许，否则所有操作都将被拒绝
+ 如果有任何`forbid`策略匹配，则访问将被拒绝（禁胜语义）
+ 将策略决策记录在案，以便 CloudWatch 进行监控和合规
这样可以确保通过网关进行的所有代理操作都受您的安全策略的约束。
## 步骤 3：部署
将所有资源部署到 AWS：
```
agentcore deploy
```
AgentCore CLI 创建网关、注册 Lambda 目标、配置策略引擎并附加 Cedar 策略。此过程大约需要 2-3 分钟。
部署完成后，您可以验证资源的状态：
```
agentcore status
```
## 步骤 4：测试策略
通过向网关发送请求来测试策略。由于网关使用`--authorizer-type NONE`，因此您可以直接使用 **curl** 发送请求。
**测试 1：退款 500 美元（应允许）**
500 美元的退款金额低于 1000 美元的限额，因此策略引擎允许该请求：
```
curl -X POST ++++ \
-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 美元的退款金额超过了 1000 美元的限额，因此策略引擎拒绝了该请求：
```
curl -X POST ++++ \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"RefundTarget___process_refund","arguments":{"amount":2000}}}'
```
**注意**
``替换为 **agentcor** e 状态输出中显示的网关 URL。
## 你建造了什么
通过本教程，您已经创建了：
+ **MCP 服务器（网关）**— 工具的托管端点
+ **Lambda 目标** — 在网关中注册的退款处理工具
+ **策略引擎**- Cedar-based 策略评估系统
+ **Cedar 政策** — 允许退款低于 1000 美元的治理规则
## 问题排查
如果您在安装或测试过程中遇到问题，请参阅以下常见问题和解决方案：
| 问题 | 解决方案 |
| --- | --- |
| "AccessDeniedException" | 检查 bedrock-agentcore 的 IAM 权限：\* |
| 网关没有响应 | 部署后等待 30—60 秒进行 DNS 传播 |
| 部署失败 | 运行 **agentcore 状态**以检查资源状态并查看错误消息 |
| 政策未强制执行 | 通过运行 **agentc** ore 状态验证策略引擎是否已在强制模式下连接 |
| 部署期间出现 Cedar 验证错误 | Cedar 策略必须使用特定的资源 ARN — 通配符资源（例如`permit(principal, action, resource);`）将被拒绝。在 Cedar 策略的字段中使用**代理核心状态**中的网关 ARN。`resource` |
| 工具调用意外被拒绝 | 策略引擎正在执行，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`。