Cortex Agent 的资源预算

资源预算可让您监控账户的 Cortex Agents 支出，并在支出超过支出阈值时采取行动。这使您可以控制 Cortex Agent 的成本，并自动采取措施，例如在支出超过配置的限制时撤销访问权限。通过资源预算，您可以控制该特定代理在汇总级别上消耗的 Credit。

资源预算的运作方式

资源预算使用 Snowflake 基于标签的成本归因模型。您创建一个标签，将其应用于 Cortex Agent 对象，然后将该标签与预算相关联。Snowflake 跟踪标记对象的 Credit 使用量，并定期根据预算限额评估支出。资源预算对于限制 Cortex Agent 对象的支出非常有用。

Snowflake 通过以下流程强制执行资源预算：

  1. 创建标签。

  2. 将标签应用于 Cortex Agent 对象。

  3. 创建预算并指定要跟踪支出的标签。在创建预算时，您还可以设置每月支出限额（以 Credit 为单位）。

  4. 添加一个存储过程，该存储过程将在支出达到配置的预算阈值时执行。例如，您可以调用一个存储过程以在 80% 时发出警报，并调用另一个存储过程以在 100% 时撤销访问权限。

  5. Snowflake 跟踪标记对象的 Credit 使用量。

  6. 当支出达到预算的配置阈值（例如 80% 或 100%）时，Snowflake 会执行为该阈值定义的存储过程。

Snowflake 会定期计算使用情况、评估阈值并触发任何配置的操作。超出预算后，使用标准预算可能需要最多 8 小时（使用延迟优化选项需要 2 小时）才能执行预算。

创建标签

  1. 创建标签以标识与 Cortex Agent 对象关联的成本中心：

    -- Create a tag with allowed cost center values
CREATE TAG cost_mgmt_db.tags.cost_center
   ALLOWED_VALUES 'org-level'
   COMMENT = 'cost_center tag';

  2. 将标签应用于 Cortex Agent 对象，将其与成本中心关联：

    -- Apply the cost center tag to the Cortex Agent object
ALTER AGENT IF EXISTS my_agent
  SET TAG cost_mgmt_db.tags.cost_center = 'org-level';

设置资源预算

您可以使用 Snowsight 或 SQL 创建预算并将其与 Cortex Agent 对象关联。

  1. 登录 Snowsight。

  2. 在导航菜单中，选择 Admin » Cost management。

  3. 选择 Budgets。

  4. 选择 + Budget。

  5. 对于 Location to store，选择要在其中创建预算的数据库和架构名称。

  6. 对于 Name，请使用 my_budget。

  7. 对于 Budget (credits per month)，为预算的支出限额输入一个值，例如 10000。

  8. 若要缩短 预算刷新间隔 以便更严密地监控支出，请选择 Enable low latency budget。

  9. 对于 Threshold，输入一个值作为通知阈值，例如 80。

  10. 对于 Notify，输入用于接收通知电子邮件的电子邮件地址。

  11. 选择 Next。

  12. 对于 Budget scope，将 Cortex Agent 对象上的标签添加到资源预算中。

  13. 选择 Create。

现在，Snowflake 会跟踪 my_agent 的 Credit 使用量，同时设置每月限额为 10,000 Credit 的 my_budget 预算。

配置阈值操作

您可以附加在支出达到特定阈值时执行的存储过程，这些阈值以支出限额的百分比表示，适用于每月预算期。有关更多信息，请参阅 预算的自定义操作。

发送通知

您可以在支出达到阈值时发送通知。有关更多信息，请参阅 预算通知。

  1. 设置用于发送通知的电子邮件地址：

    CALL my_budget!SET_EMAIL_NOTIFICATIONS(
  'budgets_notification_integration',
   'costadmin@example.com, budgetadmin@example.com'
);

  2. 设置通知阈值：

    CALL my_budget!SET_NOTIFICATION_THRESHOLD(80);

撤消访问权限

  1. 创建一个存储过程，用于撤销对 Cortex Agent 的访问权限。在存储过程中，您可以限制对特定角色的访问权限，以撤销该角色的 USAGE。

    -- Create a stored procedure that revokes access to the Cortex Agent object
CREATE OR REPLACE PROCEDURE budgets_db.budgets_schema.sp_revoke_agent_access(
   agent_name STRING, role_name STRING
)
RETURNS STRING
LANGUAGE SQL
AS
BEGIN
   EXECUTE IMMEDIATE 'REVOKE ROLE agent_' || agent_name || '_role FROM ROLE ' || role_name;
   RETURN 'Access revoked for ' || agent_name;
END;

    重要

    确保 role_name 和用户无权通过其他角色访问 Cortex Agents。有关正确配置角色和权限的指南，请参阅 用户权限和访问控制。

  2. 设置自定义操作，在预算使用达到 100% 时阻止访问。您还可以对通知使用自定义操作。

    -- Provide access to the stored procedures
GRANT USAGE ON DATABASE budgets_db TO APPLICATION SNOWFLAKE;
GRANT USAGE ON SCHEMA budgets_db.budgets_schema TO APPLICATION SNOWFLAKE;
GRANT USAGE ON PROCEDURE budgets_db.budgets_schema.sp_revoke_agent_access(STRING, STRING)
   TO APPLICATION SNOWFLAKE;

-- Block access at 100% of the budget
CALL budgets_db.budgets_schema.my_budget!ADD_CUSTOM_ACTION(
   SYSTEM$REFERENCE('PROCEDURE',
      'budgets_db.budgets_schema.sp_revoke_agent_access(string, string)'),
   ARRAY_CONSTRUCT('AGENT_NAME', 'ROLE_NAME'),
   'ACTUAL',
   100);

备注

您还可以使用自定义操作，在预计支出超过预算限额时采取行动。有关更多信息，请参阅 预算的自定义操作。

处理支出限额的例外情况

在某些情况下，您可能需要在达到预算限制后恢复访问权限，例如在财报季或其他高峰期。您可以将阈值配置为超过 100%（最高可达 500%），以处理这些异常情况。

该工作流程假定，当支出达到预算阈值时，使用配置的存储过程撤销访问权限。管理员恢复用户子集并重新授予访问权限。当支出达到 200% 时，撤销过程会再次以硬停止形式运行。

  1. 创建存储过程以恢复对角色的访问权限：

    -- Create a stored procedure that reinstates access to the Cortex Agent object
CREATE OR REPLACE PROCEDURE budgets_db.budgets_schema.sp_reinstate_agent_access(
   agent_name STRING, role_name STRING
)
RETURNS STRING
LANGUAGE SQL
AS
BEGIN
   EXECUTE IMMEDIATE 'GRANT ROLE agent_' || agent_name || '_role TO ROLE ' || role_name;
   RETURN 'Access reinstated for ' || agent_name;
END;

  2. 使用恢复访问权限的存储过程配置超过 100% 的阈值。这使您可以提高例外期间的有效预算。当支出达到预算的 200% 时，将再次撤销访问权限：

    -- Add grants for this procedure
GRANT USAGE ON DATABASE budgets_db TO APPLICATION SNOWFLAKE;
GRANT USAGE ON SCHEMA budgets_db.budgets_schema TO APPLICATION SNOWFLAKE;
GRANT USAGE ON PROCEDURE budgets_db.budgets_schema.sp_revoke_agent_access(STRING, STRING)
   TO APPLICATION SNOWFLAKE;

-- Issue a reinstatement for a subset of users
CALL budgets_db.budgets_schema.sp_reinstate_agent_access('my_agent', 'power_user_role');

-- Set another threshold at 200% as a hard stop
CALL budgets_db.budgets_schema.my_budget!ADD_CUSTOM_ACTION(
   SYSTEM$REFERENCE(
      'PROCEDURE',
      'budgets_db.budgets_schema.sp_revoke_agent_access(string, string)'
   ),
   ARRAY_CONSTRUCT('my_agent', 'power_user_role'),
   'ACTUAL',
   200
);

恢复访问权限

为确保用户可以在下一个预算周期开始时再次访问 Cortex Agents，请将以下存储过程设置为在预算周期重新启动时调用。

  1. 创建存储过程以恢复对角色的访问权限：

    -- Create a stored procedure that reinstates access to the Cortex Agent object
CREATE OR REPLACE PROCEDURE budgets_db.budgets_schema.sp_reinstate_agent_access(
   agent_name STRING, role_name STRING
)
RETURNS STRING
LANGUAGE SQL
AS
BEGIN
   EXECUTE IMMEDIATE 'GRANT ROLE agent_' || agent_name || '_role TO ROLE ' || role_name;
   RETURN 'Access reinstated for ' || agent_name;
END;

  2. 设置预算的周期开始操作：

    GRANT USAGE ON DATABASE budgets_db TO APPLICATION SNOWFLAKE;
GRANT USAGE ON SCHEMA budgets_db.budgets_schema TO APPLICATION SNOWFLAKE;
GRANT USAGE ON PROCEDURE budgets_db.budgets_schema.sp_reinstate_agent_access(STRING, STRING)
   TO APPLICATION SNOWFLAKE;

CALL budgets_db.budgets_schema.my_budget!SET_CYCLE_START_ACTION(
   SYSTEM$REFERENCE('PROCEDURE', 'budgets_db.budgets_schema.sp_reinstate_agent_access(string, string)'),
   ARRAY_CONSTRUCT('my_agent', 'power_user_role')
);

根据预计支出设置警报

要根据预测支出而非实际支出接收警报或执行操作，可以将触发器类型设置为 PROJECTED。例如，要在预计消耗达到预算限制的 75% 时调用名为 alert_team 的过程，请运行以下命令：

CALL budget_db.sch1.my_budget!ADD_CUSTOM_ACTION(
   SYSTEM$REFERENCE('PROCEDURE', 'code_db.sch1.alert_team(string, string, string)'),
   ARRAY_CONSTRUCT('admin@example.com', 'Budget Alert', 'Spending at 75% of budget limit'),
   'PROJECTED',
   75);

列出自定义操作

  • 要列出预算上配置的所有自定义操作，请使用 GET_CUSTOM_ACTIONS 方法：

    -- View all custom actions on the budget
CALL budgets_db.budgets_schema.my_budget!GET_CUSTOM_ACTIONS();

有关更多信息，请参阅 预算的自定义操作。

监控使用情况

  • 要查看每个 Cortex Agent 对象的 Credit 使用量，请使用预算的使用情况报告方法：

    -- View usage for the current month
CALL budgets_db.budgets_schema.my_budget!GET_SERVICE_TYPE_USAGE_V2(
   '2026-02',
   '2026-03'
);

    输出包含以下列：

    列

    描述

    服务类型

    服务类别 (AI)

    实体类型

    对象类型 (CORTEX_AGENT)

    实体 ID

    Cortex Agent 对象的唯一标识符

    名称

    Cortex Agent 对象的显示名称

    使用的 Credit

    指定时间段内使用的总 Credit

    Credit 云

    云服务 Credit 使用数量。

预算执行延迟

定期进行预算计算和阈值执行：

  1. Snowflake 计算已标记 Cortex Agent 对象的 Credit 使用量。

  2. 系统根据所有配置的阈值评估支出。

  3. 如果达到阈值，则执行关联的存储过程。

  4. 使用情况仪表板已更新为最新数据。

如果您启用了低延迟预算，则预算将在超出预算后两小时内强制执行。否则，可能需要在超出预算后长达 8 小时才能执行。您可以更频繁地触发预算执行，例如每 60 分钟触发一次，以缩短 刷新间隔。

警告

在 Credit 被消耗和预算系统检测到超出阈值之间存在固有的延迟。在执行间隔期间，在执行操作之前，支出可能会超过配置的阈值。相应地规划阈值。例如，将警报设置为 80%，以便在触发 100% 操作之前给您做出响应的时间。

限制

以下限制适用于 Cortex Agent 的资源预算：

  • 仅限单团队资源： 资源预算适用于整个 Cortex Agent 对象。

  • 执行延迟： 预算执行按周期运行，在超出预算后最多可能需要 8 小时才能执行预算。在操作触发之前的时间间隔内，支出可能超过阈值。

  • 基于角色的访问权限撤销： 要在阈值处撤销访问权限，必须为 Cortex Agent 对象创建专用角色。

  • 每月周期： 预算以月为周期运行。您无法配置资源预算期。

  • 标签延迟： 当您更改对象的标签时，更改最多可能需要 8 个小时才能反映在使用标签的预算中。有关更多信息，请参阅 自定义预算。

  • 入口点确定归因： 如果请求开始于 Snowflake Intelligence 并调用 Cortex Agent，该使用量归因于 Snowflake Intelligence。因此，如果预算的范围仅包括 Cortex 代理标记的资源（例如，仅应用于代理的标签），则不会从 Snowflake Intelligence 中发起的请求捕获 Credit，即使这些请求调用了 Cortex Agent 也一样。要涵盖此用法，请包括预算范围内的 Snowflake Intelligence 资源，或配置单独的 Snowflake Intelligence 资源预算（请参阅 Snowflake Intelligence 资源预算）。但请注意，Snowflake Intelligence 范围内的预算适用于归属范围内 Snowflake Intelligence 对象的所有使用量，而不仅仅是调用特定 Cortex Agent 的请求。