Budgets de ressources pour les Agents Cortex

Un budget de ressources vous permet de surveiller les dépenses des Agents Cortex pour votre compte et de prendre des mesures lorsqu’elles dépassent les seuils de dépenses. Cela vous permet de contrôler les coûts des Agents Cortex et de prendre des mesures automatisées telles que la révocation de l’accès lorsque les dépenses dépassent vos limites configurées. Les budgets de ressources vous permettent de contrôler les crédits consommés à un niveau agrégé pour un Agent spécifique.

Fonctionnement des budgets de ressources

Les budgets de ressources utilisent le modèle d’attribution des coûts basé sur des balises de Snowflake. Vous créez une balise, vous l’appliquez à un objet d’Agent Cortex, puis vous associez cette balise à un budget. Snowflake suit la consommation de crédit pour l’objet balisé et évalue périodiquement les dépenses par rapport à la limite budgétaire. Le budget de ressources est utile pour limiter les dépenses de l’objet d’Agent Cortex.

Snowflake applique des budgets de ressources avec le flux suivant :

  1. Vous créez une balise.

  2. Vous appliquez la balise à l’objet d’Agent Cortex.

  3. Vous créez un budget et spécifiez la balise pour laquelle suivre les dépenses. Dans le cadre de la création du budget, vous définissez également une limite de dépenses mensuelle en crédits.

  4. Vous ajoutez une procédure stockée à exécuter lorsque les dépenses atteignent un seuil configuré du budget. Par exemple, vous pouvez invoquer une procédure stockée pour déclencher une alerte à 80 % et une autre procédure stockée pour la révocation de l’accès à 100 %.

  5. Snowflake suit la consommation de crédit pour l’objet balisé.

  6. Lorsque les dépenses atteignent un seuil configuré du budget, tel que 80 % ou 100 %, Snowflake exécute la procédure stockée définie pour ce seuil.

Snowflake calcule l’utilisation, évalue les seuils et déclenche périodiquement toutes les actions configurées. Une fois le budget dépassé, l’application du budget peut prendre jusqu’à huit heures avec le budget standard (ou deux heures avec l’option d’optimisation de la latence) pour que le budget soit appliqué.

Création d’une balise

  1. Créez une balise pour identifier le centre de coûts associé à l’objet d’Agent Cortex :

    -- 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. Appliquez la balise à l’objet d’Agent Cortex pour l’associer à un centre de coûts :

    -- 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';

Configurer un budget de ressources

Vous pouvez utiliser Snowsight ou SQL pour créer un budget et l’associer à un objet d’Agent Cortex.

  1. Connectez-vous à Snowsight.

  2. Dans le menu de navigation, sélectionnez Admin » Cost management.

  3. Sélectionnez Budgets.

  4. Sélectionnez + Budget.

  5. Pour Location to store, sélectionnez le nom de la base de données et du schéma dans lesquels vous souhaitez créer le budget.

  6. Pour Name, utilisez my_budget.

  7. Pour Budget (credits per month), saisissez une valeur, telle que 10 000, pour la limite de dépenses du budget.

  8. Pour diminuer l’intervalle d’actualisation du budget afin de pouvoir surveiller les dépenses de plus près, sélectionnez Enable low latency budget.

  9. Pour Threshold, saisissez une valeur, telle que 80, pour le seuil de notification.

  10. Pour Notify, saisissez les adresses e-mail qui recevront les e-mails de notification.

  11. Sélectionnez Next.

  12. Pour Budget scope, ajoutez la balise de l’objet d’Agent Cortex au budget de ressources.

  13. Sélectionnez Create.

Maintenant, Snowflake suit la consommation de crédit pour``my_agent`` par rapport au budget my_budget avec une limite mensuelle de 10 000 crédits.

Configurer les actions de seuil

Vous pouvez joindre des procédures stockées qui sont exécutées lorsque les dépenses atteignent des seuils spécifiques, qui sont exprimés sous forme de pourcentage de la limite de dépenses et s’appliquent à la période budgétaire mensuelle. Pour plus d’informations, voir Actions personnalisées pour les budgets.

Envoyer les notifications

Vous pouvez envoyer des notifications lorsque les dépenses atteignent un seuil. Pour plus d’informations, voir Notifications pour les budgets.

  1. Définissez l’e-mail auquel envoyer les notifications :

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

  2. Définissez le seuil de notification :

    CALL my_budget!SET_NOTIFICATION_THRESHOLD(80);

Révoquer l’accès

  1. Créez une procédure stockée qui révoque l’accès aux Agents Cortex. Dans la procédure stockée, vous pouvez limiter l’accès à un rôle spécifique pour révoquer USAGE pour ce rôle.

    -- 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;

    Important

    Assurez-vous que role_name et l’utilisateur n’ont pas accès aux Agents Cortex via d’autres rôles. Pour obtenir des conseils sur la configuration correcte des rôles et des privilèges, consultez Privilèges utilisateur et contrôle d’accès.

  2. Définissez une action personnalisée qui bloque l’accès lorsque 100 % du budget a été dépensé. Vous pouvez également utiliser des actions personnalisées pour les notifications.

    -- 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);

Note

Vous pouvez également utiliser des actions personnalisées pour prendre des mesures lorsqu’il est prévu que les dépenses dépassent la limite budgétaire. Pour plus d’informations, voir Actions personnalisées pour les budgets.

Traitement des exceptions aux limites de dépenses

Dans certains cas, vous devrez peut-être rétablir l’accès une fois la limite budgétaire atteinte, par exemple pendant la période de facturation ou d’autres périodes de forte activité. Vous pouvez configurer des seuils au-delà de 100 %, jusqu’à 500 %, pour gérer ces scénarios d’exception.

Le workflow suppose que l’accès est révoqué à l’aide de la procédure stockée configurée lorsque les dépenses atteignent un seuil budgétaire. L’administrateur réintègre un sous-ensemble d’utilisateurs et accorde un retour d’accès. Lorsque les dépenses atteignent 200 %, la procédure de révocation s’exécute à nouveau en tant qu’arrêt définitif.

  1. Créez une procédure stockée pour rétablir l’accès au rôle :

    -- 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. Configurez un seuil au-delà de 100 % avec une procédure stockée qui rétablit l’accès. Cela vous permet d’augmenter le budget effectif pour les périodes d’exception. L’accès est à nouveau révoqué lorsque les dépenses atteignent 200 % du budget :

    -- 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
);

Rétablir l’accès

Pour que les utilisateurs puissent accéder de nouveau aux Agents Cortex au début de la période budgétaire suivante, définissez la procédure stockée suivante pour qu’elle soit appelée lors du redémarrage du cycle budgétaire.

  1. Créez une procédure stockée pour rétablir l’accès au rôle :

    -- 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. Définissez une action de début de cycle pour le budget :

    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')
);

Définition d’alertes basées sur les dépenses prévues

Pour recevoir une alerte ou effectuer une action basée sur des dépenses prévues plutôt que sur des dépenses réelles, vous pouvez définir le type de déclencheur sur PROJECTED. Par exemple, pour appeler une procédure stockée nommée``alert_team`` lorsque la consommation projetée atteint 75 % de la limite budgétaire, exécutez la commande suivante :

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);

Lister les actions personnalisées

  • Pour lister toutes les actions personnalisées configurées sur un budget, utilisez la méthode GET_CUSTOM_ACTIONS :

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

Pour plus d’informations, voir Actions personnalisées pour les budgets.

Surveiller l’utilisation

  • Pour afficher la consommation de crédits par objet d’Agent Cortex, utilisez la méthode de reporting de l’utilisation du budget :

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

    La sortie comprend les colonnes suivantes :

    Colonne

    Description

    Type de service

    La catégorie de service (AI)

    Type d’entité

    Le type d’objet (CORTEX_AGENT)

    ID de l’entité

    L’identificateur unique de l’objet d’Agent Cortex

    Nom

    Le nom d’affichage de l’objet d’Agent Cortex

    Crédits utilisés

    Le total des crédits consommés pendant la période spécifiée.

    Cloud de crédits

    Nombre de crédits de services Cloud utilisés

Latence de l’application des budgets

Les calculs de budget et l’application des seuils sont effectués périodiquement :

  1. Snowflake calcule la consommation de crédits pour l’objet d’Agent Cortex balisé.

  2. Le système évalue les dépenses par rapport à tous les seuils configurés.

  3. Si un seuil est atteint, la procédure stockée associée est exécutée.

  4. Les tableaux de bord d’utilisation sont mis à jour avec les dernières chiffres.

Si vous avez activé le budget à faible latence, vos budgets sont appliqués dans les deux heures suivant le dépassement du budget. Dans le cas contraire, l’application peut prendre jusqu’à huit heures après le dépassement du budget. Vous pouvez déclencher l’exécution du budget plus fréquemment, par exemple toutes les 60 minutes, pour réduire les :ref:` intervalle d’actualisation <label-budgets_refresh_interval>`.

Avertissement

Il existe un délai inhérent entre le moment où les crédits sont consommés et le moment où le système budgétaire détecte le dépassement du seuil. Pendant l’intervalle d’application, les dépenses peuvent dépasser le seuil configuré avant l’exécution de l’action. Planifiez vos seuils en conséquence. Par exemple, définissez une alerte à 80 % pour vous donner le temps de répondre avant que l’action de 100 % ne soit déclenchée.

Limitations

Les limites suivantes s’appliquent aux budgets de ressources pour les Agents Cortex :

  • Ressources d’équipe unique uniquement : les budgets de ressources s’appliquent à tout l’objet d’Agent Cortex.

  • Latence d’application : l’application du budget s’exécute selon un cycle périodique et peut prendre jusqu’à huit heures pour appliquer le budget une fois que le budget a été dépassé. Les dépenses peuvent dépasser un seuil pendant l’intervalle précédant le déclenchement de l’action.

  • Révocation d’accès basée sur le rôle : pour révoquer l’accès à un seuil, vous devez créer un rôle dédié pour l’objet d’Agent Cortex.

  • Période mensuelle : les budgets fonctionnent selon un cycle mensuel. Vous ne pouvez pas configurer de périodes de budget de ressources.

  • Latence de balise : lorsque vous modifiez une balise sur un objet, la répercussion du changement dans les budgets qui utilisent des balises peut prendre jusqu’à huit heures. Pour plus d’informations, voir Budgets personnalisés.

  • Le point d’entrée détermine l’attribution : si une requête commence dans Snowflake Intelligence et appelle un Agent Cortex, cette utilisation est attribuée à Snowflake Intelligence. Par conséquent, un budget dont le champ d’application comprend uniquement les ressources balisées par les Agents Cortex (par exemple, les balises appliquées uniquement aux agents) ne capture pas les crédits des requêtes initiées dans Snowflake Intelligence, même lorsque ces requêtes appellent un Agent Cortex. Pour couvrir cette utilisation, consultez les ressources Snowflake Intelligence dans le champ d’application du budget, ou configurez un budget de ressources Snowflake Intelligence distinct (voir Budgets de ressources pour Snowflake Intelligence). Notez toutefois que les budgets de champ d’application Snowflake Intelligence s’appliquent à toutes les utilisations attribuées aux objets de champ d’application Snowflake Intelligence, et pas seulement aux requêtes qui appellent un Agent Cortex spécifique.