本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 政策入门 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)
## 先决条件
在开始之前，请确保您具备以下条件：
+ Amazon 已配置凭据的@@ **账户**。要配置凭据，您可以按照 [Amazon CLI 入门](https://docs.amazonaws.cn/cli/latest/userguide/cli-chap-getting-started.html)中的步骤安装和使用 Amazon 命令行界面。
+ Node.js 已@@ **安装 20 多个**
+ 用于创建角色、Lambda 函数、策略引擎和使用 Amazon Bedrock 的 IA@@ **M 权限** AgentCore
+ **用于处理退款请求的 Lambda 函数**。您可以使用现有函数或为本教程创建一个函数。记下在步骤 2 中使用的函数 ARN。
在部署期间， AgentCore CLI 会检查 CDK 引导堆栈。如果需要引导，交互式部署会要求进行确认。`agentcore deploy --yes`用于自动授权。
## 步骤 1：设置和安装
安装 C AgentCore LI：
```
npm install -g @aws/agentcore
```
创建新 AgentCore 项目：
**Example**
1.
```
agentcore create --name PolicyDemo --language Python --framework Strands \
--model-provider Bedrock --memory none
cd PolicyDemo
```
这些选项创建了一个使用 Amazon Bedrock 且不使用内存的 Python Strands 代理。该`cd`命令将移到必须运行后续命令的项目目录中。
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 函数注册为网关目标。在项目目录中创建一个包含以下内容的`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"]
}
}
]
```
**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. 创建引擎，然后使用以下`ENFORCE`模式将其连接到网关`update-gateway`：
```
aws bedrock-agentcore-control create-policy-engine --name RefundPolicyEngine
```
有关附加请求，请参阅[使用策略引擎更新现有网关](update-gateway-with-policy.md)。
1.
```
import boto3
client = boto3.client('bedrock-agentcore-control')
engine = client.create_policy_engine(name='RefundPolicyEngine')
client.get_waiter('policy_engine_active').wait(
policyEngineId=engine['policyEngineId']
)
print(engine['policyEngineId'], engine['policyEngineArn'])
```
然后附上`update_gateway`，通过`policyEngineConfiguration={'arn': engine['policyEngineArn'], 'mode': 'ENFORCE'}`。
1. 运行`agentcore`打开 TUI，然后选择**添加**并选择**策略引擎**：
1. 输入策略引擎名称：
1. 选择要将策略引擎连接到的网关：
1. 选择强制模式。选择**强制**：
**创建 Cedar 政策**
直接提供 Cedar 政策文件。
命名特定操作的策略还必须命名特定的网关 ARN，即不受限制的资源将被拒绝。在网关存在之前，您才知道 ARN，因此需要进行**两次部署**：一次用于创建网关，另一次用于附加策略。完整序列，从头到尾：
1. `agentcore deploy`— 创建网关、目标和策略引擎。
1. `agentcore status`— 从输出中读取网关 ARN。
1. 使用替换的 ARN `refund_policy.cedar` 进行创建，如下所示。
1. `agentcore add policy --source refund_policy.cedar`— 在您的项目中记录策略。
1. `agentcore deploy`再说一遍 — 在您的账户中创建政策。
步骤 1 和步骤 5 都是[步骤 3：部署中描述的部署](#policy-getting-started-run-setup)；您运行了两次。以下是步骤 3 和 4 的详细介绍：
1. 在您的项目目录中创建一个`refund_policy.cedar`文件，将网关 AR `agentcore status` N 替换为：
```
permit(principal,
action == AgentCore::Action::"RefundTarget___process_refund",
resource == AgentCore::Gateway::"")
when {
context.input.amount < 1000
};
```
1. 添加策略并重新部署：
```
agentcore add policy --name RefundLimit \
--engine RefundPolicyEngine \
--source refund_policy.cedar
agentcore deploy
```
知道网关 ARN 后，您可以直接在 Amazon CLI 和 boto3 上创建策略：
**Example**
1.
```
aws bedrock-agentcore-control create-policy \
--policy-engine-id RefundPolicyEngine-a1b2c3d4e5 \
--name RefundLimit \
--definition '{
"policy": {
"statement": "permit (principal, action == AgentCore::Action::\"RefundTarget___process_refund\", resource == AgentCore::Gateway::\"\") when { context.input.amount < 1000 };"
}
}'
```
1.
```
import boto3
client = boto3.client('bedrock-agentcore-control')
statement = (
'permit (principal, '
'action == AgentCore::Action::"RefundTarget___process_refund", '
'resource == AgentCore::Gateway::"") '
'when { context.input.amount < 1000 };'
)
response = client.create_policy(
policyEngineId='RefundPolicyEngine-a1b2c3d4e5',
name='RefundLimit',
definition={'policy': {'statement': statement}},
)
# CreatePolicy returns 202 - wait for the terminal status
client.get_waiter('policy_active').wait(
policyEngineId='RefundPolicyEngine-a1b2c3d4e5',
policyId=response['policyId'],
)
```
或者，在步骤 3 中部署资源后，您可以根据自然语言描述生成 Cedar 策略：
```
agentcore add policy --name RefundLimit \
--engine RefundPolicyEngine \
--generate "Only allow refunds under 1000 dollars" \
--gateway PolicyGateway
```
该`--generate`标志要求首先部署网关，因为它调用的 Amazon 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 是一种开源策略语言，由开发 Amazon 用于编写授权策略。**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：部署
将所有资源部署到 Amazon：
```
agentcore deploy
```
AgentCore CLI 创建网关、注册 Lambda 目标并配置策略引擎。如果您提供了 ARN-based Cedar 策略文件，请在此部署之后添加该文件，然后再次运行 **agentcore de** ploy 来附加它。每次部署此过程大约需要 2-3 分钟。
部署完成后，您可以验证资源的状态：
```
agentcore status
```
## 步骤 4：测试策略
通过向网关发送请求来测试策略。由于网关使用`--authorizer-type NONE`，因此您可以直接使用 **curl** 发送请求。
**代理核心状态**输出中显示的网关 URL 是基本终端节点。MCP 请求会转到该端点上的`/mcp`路径，因此请在发送请求之前附加`/mcp`到 URL。
**测试 1：退款 500 美元（应允许）**
500 美元的退款金额低于 1000 美元的限额，因此政策引擎允许以下请求：
```
curl -X POST ++++/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 美元（应被拒绝）**
2000美元的退款金额超过了1000美元的限额，因此策略引擎拒绝了该请求：
```
curl -X POST ++++/mcp \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"RefundTarget___process_refund","arguments":{"amount":2000}}}'
```
**注意**
``替换为 **agentcore 状态**输出中显示的网关 URL，然后追加。`/mcp`
## 你建造了什么
通过本教程，您创建了：
+ **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`。