Overview
Atlas Agent Engine 策略引擎使组织管理员能够对代理执行进行运行时控制。管理员在组织范围、项目范围或两者内制定策略。控制平面将应用于项目的策略合并为单个有效配置，而编排引擎 (OE) 在每次执行时强制执行该配置。
策略控制代理采取的操作，例如调用哪些工具和模型以及单次运行执行的工作量。策略分为两类：
允许列表限制代理可以调用的工具和模型。
执行预算限制了单次执行可以消耗的资源，例如工具调用次数、大语言模型 (LLM) 调用次数和执行持续时间。
策略类型
每个策略类型都有一个种类，它描述了策略值的形状。类型决定了策略引擎如何合并组织和项目策略。可以使用以下策略类型：
策略类型 | Kind | 说明 |
|---|---|---|
| 允许列表 | 代理可以调用的工具设立。 OE 会在每次工具调用之前评估此策略。如果代理调用列表中省略的工具，操作环境将停止执行并返回策略拒绝错误。 |
| 允许列表 | 代理可以调用的模型设立。 OE 在每次调用 LLM 之前评估此策略。如果代理调用列表省略的模型，操作环境将停止执行并返回策略拒绝错误。 |
| Numeric cap | 代理在单次执行中可以调用工具的最大次数。如果代理在执行次数达到上限后尝试调用工具，操作环境将停止执行并返回策略拒绝错误。 |
| Numeric cap | 代理可以在单次执行中进行的 LLM 调用的最大次数。如果代理在执行达到上限后尝试 LLM 调用，则 OE 将停止执行并返回策略拒绝错误。 |
| Numeric cap | 单次执行的最长时间（以毫秒为单位）。 OE 会检查每次工具调用和 LLM 调用之前经过的时间。如果执行已达到限制，OE 将停止执行并返回策略拒绝错误。 OE 不会停止已在进行中的调用。 |
| Numeric cap | 单次执行可以使用的 LLM 令牌的最大数量。如果代理在执行达到上限后尝试 LLM 调用，则 OE 将停止执行并返回策略拒绝错误。 |
| Numeric cap | 一个会话在每次执行中可以消耗的 LLM 令牌的最大数量。如果代理在会话达到上限后尝试 LLM 调用，则 OE 将停止执行并返回策略拒绝错误。 |
令牌总数在每次模型响应之后而不是在 LLM 调用之前累积。有关更多信息，请参阅限制。
如果代理将任务委托给子代理，则子代理将继承父代理的根会话，因此两个代理将在同一会话中运行。他们的总令牌计入一个 MAX_TOKENS_PER_SESSION 总数，而不是每个代理单独的总数。要学习；了解有关代理到代理委派的更多信息，请参阅使用代理到代理通信。
工具和目录匹配
AUTHORIZED_TOOLS 白名单条目与工具名称或发布该工具的目录标识符匹配，例如 stripe/payments。目录标识符将目录发布的每个工具列入白名单，包括目录后来添加的工具。
不附带目录标识符的工具（包括自定义工具）仅按工具名称进行匹配。要允许使用其中一个工具，请将其名称添加到允许列表中。
策略范围和继承
您可以在组织范围或项目范围内编写策略。组织策略适用于组织中的每个项目。每个项目政策必须至少与同类组织政策一样严格。当两个范围定义相同的策略类型时，策略引擎会将它们合并为项目的一个有效值。
合并规则取决于策略类型。下表列出了每种策略及其对应的合并规则：
策略类型 | 合并规则 | 项目约束 |
|---|---|---|
允许列表 | 有效值是组织允许列表和项目允许列表的交集。 | 项目无法添加组织允许列表省略的值。 |
Numeric cap | 有效值为组织上限和项目上限中的较低者。 | 项目设立的上限不能高于组织上限。 |
如果您保存的项目策略的限制性低于同类组织策略，则Atlas Agent Engine 会拒绝该请求。要提高项目的限制或扩大项目的允许名单，组织管理员必须首先更改组织策略。
执法
OE 在每次执行期间的特定检查点评估有效策略：
检查点 | 评估的策略 |
|---|---|
预工具调用 |
|
法学硕士预备课程 |
|
当策略检查失败时，操作环境会停止执行并向调用者返回策略拒绝错误。该错误包括 policy_denied 的 error_code 以及 Policy denied: <reason> 形式的消息，该消息标识拒绝原因。
注意
当没有给定类型的策略应用于执行时，操作环境不会限制相应的动作。没有有效策略的项目运行不受策略限制。
策略传播
创建、更新或删除策略后， Atlas Agent Engine 会在大约一分钟内应用更改。 Atlas Agent Engine 首先为每个受影响的项目重建有效配置，然后将该配置提供给运行项目代理的操作环境。
每次执行在启动时都会拍摄有效策略的快照，并在其整个生命周期中使用该快照。策略更改仅应用于在更改传播后开始的执行。策略更改不会影响正在进行的执行。
如果Atlas Agent Engine 无法交付更改，操作环境将继续实施其收到的最后一次配置。要检查哪些项目尚未收到更改，请参阅检查组织策略部署。
创建和编辑策略
您可以从平台用户界面或REST API创建和编辑策略。
要管理项目策略，请导航到 Manage >项目中的 Policies。要管理组织策略，请导航到组织设置中的 Policies。在任一页面中，您都可以创建、读取、更新和删除每种策略类型的策略。您可以从项目Policies 页面启用或禁用项目策略。平台用户界面不支持启用或禁用组织策略。
注意
面向客户的REST API公开策略操作。请求需要由持有操作所需角色的用户进行持有者身份验证。要学习；了解有关Atlas Agent Engine 中用户角色的更多信息，请参阅管理组织、项目和工作区和查看组织。
下表列出了可用的项目端点：
方法 | 端点 | 所需角色 | 参考 |
|---|---|---|---|
|
|
| |
|
|
| |
|
|
| |
|
|
| |
|
|
|
下表列出了可用的组织端点：
方法 | 端点 | 所需角色 | 参考 |
|---|---|---|---|
|
|
| |
|
|
| |
|
|
| |
|
|
| |
|
|
|
预览组织许可列表
由于允许列表作为交集进行合并，因此从组织允许列表中删除值可能会使项目没有允许的值。在保存对组织策略的更改之前，请使用 ORG_OWNER角色调用以下端点：
POST /api/v1/organizations/{orgId}/policies/preview
API响应列出了有效允许列表为空的每个项目的名称，并显示了该项目当前执行的允许列表。要学习；了解更多信息，请参阅预览受影响的项目。
启用和禁用策略
Atlas Agent Engine 在构建有效配置时会跳过已禁用的策略。组织和项目策略都有 enabled 标志。要启用或禁用策略，请调用策略范围的 PUT API端点并设立enabled 标志。您还可以从平台用户界面启用或禁用项目策略。要学习；了解更多信息，请参阅创建和编辑策略。
禁用策略时， Atlas Agent Engine 会保留策略的配置和历史记录。如果重新启用该策略， Atlas Agent Engine 将恢复相同的配置。
查看有效策略
有效视图显示如何解析项目的组织和项目范围。要检索有效视图，请使用以下具有项目读取角色的项目端点：
GET /api/v1/projects/{projectId}/policies/effective
API响应列出了每种策略类型、OE 执行的合并有效值、每个范围定义的值以及有效的一个或多个范围。 Atlas Agent Engine 代表您读取组织值，因此您无需持有组织角色即可查看继承的基线。要学习；了解详情，请参阅列出有效策略。
检查组织策略部署
在Atlas Agent Engine 中，项目一次接收一个策略更改，而不是一起接收。在组织策略部署过程中，一些项目实施新策略，而另一些项目仍会实施上一个策略。要查看组织策略部署的进度，请使用以下具有 ORG_OWNER 或 ORG_READ_ONLY角色的端点：
GET /api/v1/organizations/{orgId}/policies/rollout
API响应标识了每个延迟的项目、项目未重建或未收到有效配置的原因，以及Atlas Agent Engine 尝试重建或接收有效配置的次数。 API响应省略了Atlas助手引擎在其日志中记录的根本的错误文本。要学习；了解详情，请参阅查看组织策略部署状态。
当项目未收到保存的策略时， Atlas Agent Engine 会重试将策略传递到该项目，并使已收到更改的项目保持不变。如果无法通过重试构建来解决故障（例如策略值无效），则Atlas Agent Engine 会立即停止尝试构建该项目。如果故障是暂时性的，例如无法访问项目，则Atlas Agent Engine 会重试以构建项目，并且两次尝试之间的延迟会增加。在 10 次尝试失败后， Atlas助手引擎停止重试构建项目。
尝试计数将在用户下次编辑策略时重置。如果Atlas Agent Engine 停止重试项目，请更正策略并再次保存，以将项目返回到部署队列。
监控策略拒绝
限制
策略引擎具有以下限制：
新的或更新的策略最多需要一分钟才能生效。策略仅适用于在其传播后开始的执行。护栏几乎立即生效。
OE 可能会因一次调用而超过上限。 OE 在每次调用之前检查持续时间和令牌使用情况。如果该调用尚未达到
MAX_EXECUTION_DURATION_MS或MAX_TOKENS_PER_EXECUTION限制，即使该调用超出了这些限制，也会进行下一次调用。OE 可能会因多次调用而超过会话令牌上限。一个会话会同时运行多个执行。 Atlas Agent Engine 仅在所有进行中的调用完成后才检查会话上限。
MAX_TOKENS_PER_SESSION值可能会超过配置的最大值，其大小取决于这些调用的组合令牌。词元上限不包括内存提取。内存提取消耗的令牌不计入
MAX_TOKENS_PER_EXECUTION或MAX_TOKENS_PER_SESSION值。没有目录的工具仅按名称匹配。不携带目录标识符的工具（例如自定义工具）仅按工具名称匹配
AUTHORIZED_TOOLS策略类型条目。要学习；了解更多信息，请参阅工具和目录匹配。