“仅限记录” 模式的工作原理仅记录策略和仅限日志策略引擎设置策略的执行模式观察 LOG_ONLY 结果将政策推向执法在 LOG_ONLY 模式下选择阈值注意事项和限制

在 LOG_ONLY 模式下测试策略

使用策略级别的强制模式，您可以在ACTIVE和之间切换LOG_ONLY以回答以下问题：“如果应用此策略，它会对我的流量产生什么影响？” 每策略LOG_ONLY模式允许您在不影响授权决策的情况下根据实际流量测试策略。该策略会像强制执行一样评估每个请求，但仅将结果写入日志。实施模式为的策略不会导致任何内容被阻止或允许LOG_ONLY。一旦你相信结果，就把它推广到ACTIVE。

主题

“仅限记录” 模式的工作原理
仅记录策略和仅限日志策略引擎
设置策略的执行模式
观察 LOG_ONLY 结果
将政策推向执法
在 LOG_ONLY 模式下选择阈值
注意事项和限制

“仅限记录” 模式的工作原理

策略引擎中的每个策略的强制模式均为ACTIVE或LOG_ONLY。默认设置为ACTIVE，因此现有策略以及您在未指定字段的情况下创建的任何新策略都将像以前一样继续执行。当策略引擎评估请求时，它会并排评估您的ACTIVE策略和您的LOG_ONLY政策，但仅对您的策略强制执行。ACTIVE

ACTIVE策略决定返回 AgentCore 网关并强制执行的决定。策略引擎应用 “default-deny” 和 “forbid-wins” 语义，这意味着只有在策略允许的情况下才允许请求，而任何活动策略的单个禁令都会拒绝该请求。

LOG_ONLY策略是根据同一个请求进行评估的，但其结果是分开的。它们以跟踪形式报告并作为 Amazon CloudWatch 指标发布。它们永远不会合并到强制执行的决定中。

执法模式	对每个请求进行了评估？	影响返回的决定？
`ACTIVE`（默认值）	支持	是
`LOG_ONLY`	是	否

对请求的评估分为两个阶段：

策略引擎计算决策。只有ACTIVE政策才会促成这种情况。 LOG_ONLY政策是分开评估和报告的，但从不考虑在内。
如果引擎与处于ENFORCE模式的网关关联，则网关会根据策略引擎的决定允许或拒绝该操作。如果引擎与处于LOG_ONLY模式的网关关联，则网关不采取任何行动；决策会被记录下来，但不会强制执行。

ACTIVE并LOG_ONLY被视为两个孤立的集合；LOG_ONLY保单永远无法改变来电者的体验。请求收到的决定不受任何LOG_ONLY政策的影响。

除了记录与请求匹配的LOG_ONLY策略外，策略引擎还会报告其中哪些策略如果是，则会更改决策ACTIVE。这是评估政策的有效性和安全性（即是否可以推广到该政策ACTIVE）时使用的关键信号。例如，如果LOG_ONLY策略频繁匹配并出现在决策翻转集中，则会在观察窗口期间屏蔽您的流量。每项LOG_ONLY策略都独立于所有其他LOG_ONLY策略进行评估，以确定决策转变策略集。但是，每项LOG_ONLY政策评估都考虑了所有现行ACTIVE政策。

仅记录策略和仅限日志策略引擎

中的策略 AgentCore 有两个单独的控件，它们都使用值 LOG_ONLY。它们在不同的层面运作，回答不同的问题，因此了解你在设置哪个层面很重要。

策略引擎实施模式：控制引擎的整体行为。如果设置为LOG_ONLY，则无论引擎的单个策略模式如何，都不会在引擎中强制执行任何策略。所有决策都会被记录下来。使用CreateGateway或UpdateGateway操作将策略引擎与网关关联policyEngineConfiguration时，使用mode字段进行设置。mode接受的两个值是ENFORCE（默认）和LOG_ONLY。

策略模式控制强制引擎中单个策略的行为。当设置为 LOG_ONLY 时，仍会对该策略进行评估，但其决策会被记录下来，而不是强制执行。引擎中的所有其他ACTIVE策略继续正常执行。enforcementMode接受的两个值是ACTIVE（默认）和LOG_ONLY。

使用策略级别 LOG_ONLY 在生产环境中对新的护栏进行影子测试，而不会影响流量。在启用强制之前，使用引擎级 LOG_ONLY 来观察所有策略的行为。

		策略实施模式
		`ACTIVE`	`LOG_ONLY`
策略引擎实施模式	`ENFORCE`	已评估并强制执行。可以屏蔽或修改请求。	已评估但未强制执行。仅记录决策；引擎中的其他`ACTIVE`策略仍会强制执行。
策略引擎实施模式	`LOG_ONLY`	已评估但未强制执行。仅记录决策。	已评估但未强制执行。仅记录决策。

注意

策略引擎强制模式优先。当策略引擎在 LOG_ONLY 模式下关联时，任何策略都不能拒绝网关操作，即使是处于ACTIVE强制模式的策略也是如此，因为网关根本不会根据策略引擎的决策采取行动。引擎仍在计算决策，但你仍然会收到LOG_ONLY遥测数据；该决定根本没有得到执行。

设置策略的执行模式

创建或更新策略时，可以在策略上设置该字段（即CreatePolicy和UpdatePolicy），该enforcementMode字段由GetPolicy和返回ListPolicies。

在LOG_ONLY模式下创建策略通过在CreatePolicy请求中设置为enforcementMode，LOG_ONLY在LOG_ONLY模式下创建策略。以下示例在政策中创建了一个护栏，禁止超过置信阈值的暴力内容，但只能遵守它。有关政策中的护栏的更多信息，请参阅策略中的护栏。


aws bedrock-agentcore-control create-policy \
--policy-engine-id my-policy-engine-id \
--name "LogOnlyViolenceFilter" \
--enforcement-mode LOG_ONLY \
--validation-mode IGNORE_ALL_FINDINGS \
--definition '{"policy":{"statement":"forbid (principal, action == AgentCore::Action::\"MyTarget\", resource == AgentCore::Gateway::\"arn:aws:bedrock-agentcore:us-east-1:111122223333:gateway/my-gateway\") when guardrails { BedrockGuardrails::ContentFilter([\"VIOLENCE\"], [context.input.userMessage])[\"VIOLENCE\"].confidenceScore.greaterThan(decimal(\"0.7\")) };"}}'

响应以 “EnforcementMode” 回应政策：“LOG_ONLY”。该策略开始根据流量进行评估，从那时起，其匹配项就会出现在跟踪和 CloudWatch 指标中，而不会影响任何决策。

列出策略及其实施模式

ListPolicies enforcementMode在每个策略摘要中都会返回，因此您可以一目了然地看到哪些策略正在遵守，哪些策略正在执行。


aws bedrock-agentcore-control list-policies \
--policy-engine-id my-policy-engine-id \
--query 'policies[].{name:name,enforcementMode:enforcementMode,status:status}'

响应


[
  { "name": "LogOnlyViolenceFilter", "enforcementMode": "LOG_ONLY", "status": "ACTIVE" },
  { "name": "RefundLimit",           "enforcementMode": "ACTIVE",   "status": "ACTIVE" }
]

观察 LOG_ONLY 结果

当呼叫者通过网关发出 tools/call 请求时， AgentCore 网关会先评估所有策略（包括LOG_ONLY策略），然后将 MCP 响应返回给呼叫者。呼叫者的响应永远不会受到LOG_ONLY策略的影响；这些结果仅通过可观察性来报告。

您可以通过追踪和 Amazon CloudWatch 指标来观察LOG_ONLY政策行为：

跟踪和跨度：当您在网关上启用跟踪时，策略评估跨度将包含LOG_ONLY匹配信息。你可以在 Obs AgentCore ervability 控制台中检查这些跨度，看看哪些LOG_ONLY策略是针对给定请求触发的，以及它们是否会推翻决定。有关更多信息，请参阅在 Amazon Bedrock AgentCore 可观测性上观察您的代理应用程序。

CloudWatch AgentCore m@@ etrics：中的策略在 AWS/Bedrock-AgentCore 命名空间下发布指标。以下指标是特定于LOG_ONLY评估的：

指标	它告诉你什么
`ConfidenceScore`（用 PolicyEnforcementMode =`LOG_ONLY`）	护栏为匹配`LOG_ONLY`的保单返回的信心分数。在选择阈值时，使用它来了解流量的分数分布。
`ConfidenceThreshold`（带有 `PolicyEnforcementMode=LOG_ONLY`）	在`LOG_ONLY`策略上配置的阈值。在比较不同策略的分数和阈值时很有用。
`LogOnlyMatches`	`LOG_ONLY`策略触发的请求数。按策略发出，并作为引擎上所有`LOG_ONLY`策略的组汇总发出。
`LogOnlyDecisionFlips`	如果`LOG_ONLY`策略被提升，本来会改变决策的请求数量。这是关键的促销信号：持续的零意味着推广该政策不会阻塞当前的流量。
`LogOnlyEvalIncomplete`	在`LOG_ONLY`评估不完整时发出。使用它来警报持续存在的不完整评估率。

所有指标都包括 PolicyEngine 和用于筛选的 OperationName 维度。 Per-policy 指标还包括带有策略 ID 的策略维度。

有关查看 AgentCore 资源指标的更多信息，请参阅 B edrock AgentCore 生成的可观测性数据。

将政策推向执法

当您对某项LOG_ONLY政策充满信心时，请将其提升为强制执行UpdatePolicy，设置enforcementMode为ACTIVE。无需进行其他更改，并且该策略保留了其 ID、名称和定义。


aws bedrock-agentcore-control update-policy \
--policy-engine-id my-policy-engine-id \
--policy-id LogOnlyViolenceFilter-a1b2c3d4e5 \
--enforcement-mode ACTIVE

反之亦然：你可以将ACTIVE政策向后移动，使其脱LOG_ONLY离执法，同时保持其原位并继续遵守该政策。

因此，典型的生命周期是在中创建策略LOG_ONLY，观察流量和指标，然后将其提升到ACTIVE，如果需要，LOG_ONLY可以在不删除和重新创建策略的情况下将其降级为。

在 LOG_ONLY 模式下选择阈值

LOG_ONLY模式对于护栏策略特别有用，在该策略中，您需要选择一个置信分数阈值，以平衡安全性与合法流量中断之间的关系。阈值过低会阻止合法请求；过高的阈值可能会让威胁通过。

推荐的工作流程：在您认为合理的阈值（例如 0.7）的LOG_ONLY模式下部署护栏。该策略会评估每个请求并对 CloudWatch 指标发出置信度分数，但从不阻止流量。

通过具有代表性的窗口（几天或几周的实际生产流量）积累数据。该 ConfidenceScore 指标（带有 PolicyEnforcementMode =LOG_ONLY）为您提供流量产生的分数分布。

根据真实情况分析分数。如果您有标记的测试集（提示标记为良性或恶意），则可以在每个阈值下计算精度和召回率，然后选择最符合目标的测试集。如果您没有已标记的数据，请从高分范围（例如 0.8—1.0）、低分范围（0—0.2）和模糊的中间区域（0.4—0.7）中采样提示，然后对每个样本进行分类，以建立对阈值选择的信心。使用您选择的阈值更新政策，并将其提升为ACTIVE：


aws bedrock-agentcore-control update-policy \
--policy-engine-id my-policy-engine-id \
--policy-id LogOnlyViolenceFilter-a1b2c3d4e5 \
--enforcement-mode ACTIVE \
--definition '{"policy":{"statement":"forbid (principal, action == AgentCore::Action::\"MyTarget\", resource == AgentCore::Gateway::\"arn:aws:bedrock-agentcore:us-east-1:111122223333:gateway/my-gateway\") when guardrails { BedrockGuardrails::ContentFilter([\"VIOLENCE\"], [context.input.userMessage])[\"VIOLENCE\"].confidenceScore.greaterThan(decimal(\"0.65\")) };"}}'

此工作流程可确保阈值反映您的实际流量模式，而不是一般的默认值。

注意事项和限制

LOG_ONLY政策永远不会影响决策。LOG_ONLY策略不能导致允许或拒绝某项操作。请求收到的决定与在LOG_ONLY政策不存在时收到的决定相同。这是该功能的核心保障。

更改最终是一致的。创建、更新或升级策略将在几秒钟内应用于评估路径。相应地规划您的观察窗口和晋升步骤，而不是指望瞬间切换。

结果列表是有界限的。 LOG_ONLY匹配列表和决策翻转列表每个请求上限为 1,000 个条目。对于拥有大量LOG_ONLY策略的引擎，请依靠这些 CloudWatch 指标来获得完整的汇总计数。

评估可以是部分的。当请求的LOG_ONLY评估未完成时，该请求的LOG_ONLY信号可能缺少条目。强制执行的决定永远不会受到影响。

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

验证和测试策略

验证和分析概述