Ressourcenbudgets für Cortex Agents¶

Ein Ressourcenbudget ermöglicht die Überwachung der Cortex Agents-Ausgaben für Ihr Konto und das Ergreifen von Maßnahmen, wenn die Ausgabenschwellenwerte überschritten werden. So können Sie die Kosten für Cortex Agents kontrollieren und automatische Aktionen ausführen, wie z. B. das Widerrufen des Zugriffs, wenn die Ausgaben Ihre konfigurierten Limits überschreiten. Ressourcenbudgets geben Ihnen die Kontrolle über die Credits, die auf aggregierter Ebene für diesen spezifischen Agenten verbraucht werden.

Funktionsweise von Ressourcenbudgets¶

Ressourcenbudgets verwenden das Tag-basierte Kostenzuordnungsmodell von Snowflake. Sie erstellen ein Tag, wenden es auf ein Cortex Agent-Objekt an, und verknüpfen anschließend dieses Tag mit einem Budget. Snowflake verfolgt den Credit-Verbrauch für das getaggte Objekt und wertet die Ausgaben regelmäßig anhand des Budgetlimits aus. Das Ressourcenbudget ist nützlich, um die Ausgaben für das Cortex Agent-Objekt zu begrenzen.

Snowflake setzt Ressourcenbudgets mit dem folgenden Ablauf durch:

Sie erstellen ein Tag.
Sie wenden das Tag auf das Cortex Agent-Objekt an.
Sie erstellen ein Budget und geben das Tag an, für das die Ausgaben verfolgt werden sollen. Im Rahmen der Erstellung des Budgets legen Sie auch ein monatliches Ausgabenlimit für Credits fest.
Sie fügen eine gespeicherte Prozedur hinzu, die ausgeführt wird, wenn die Ausgaben einen konfigurierten Schwellenwert des Budgets erreichen. Sie können zum Beispiel eine gespeicherte Prozedur zum Alarmieren bei 80 % aufrufen und eine andere gespeicherte Prozedur zum Widerrufen des Zugriffs bei 100 % aufrufen.
Snowflake verfolgt den Credit-Verbrauch für das getaggte Objekt.
Wenn die Ausgaben einen konfigurierten Schwellenwert des Budgets erreichen, z. B. 80 % oder 100 %, führt Snowflake die für diesen Schwellenwert definierte gespeicherte Prozedur aus.

Snowflake berechnet die Nutzung, bewertet die Schwellenwerte und löst in regelmäßigen Abständen alle konfigurierten Aktionen aus. Nachdem das Budget überschritten wurde, kann es beim Standardbudget bis zu acht Stunden (oder zwei Stunden mit der für die Latenz optimierten Option) dauern, bis das Budget durchgesetzt ist.

Erstellen Sie einen Tag.¶

Erstellen Sie ein Tag, um die mit dem Cortex Agent-Objekt verbundene Kostenstelle zu identifizieren:

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

Wenden Sie das Tag auf das Cortex Agent-Objekt an, um es mit einer Kostenstelle zu verknüpfen:

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

Ein Ressourcenbudget einrichten¶

Sie können entweder Snowsight oder SQL verwenden, um ein Budget zu erstellen und es mit einem Cortex Agent-Objekt zu verknüpfen.

Melden Sie sich bei Snowsight an.
Wählen Sie im Navigationsmenü die Option Admin » Cost management aus.
Wählen Sie Budgets aus.
Wählen Sie + Budget aus.
Wählen Sie für Location to store den Namen der Datenbank und des Schemas aus, wo Sie das Budget erstellen möchten.
Für Name verwenden Sie my_budget:
Geben Sie für Budget (credits per month) einen Wert, wie beispielsweise 10000, als Ausgabenlimit des Budgets ein.
Um das Budgetaktualisierungsintervall zu verringern, damit Sie die Ausgaben genauer überwachen können, wählen Sie Enable low latency budget aus.
Geben Sie für Threshold einen Wert, wie beispielsweise 80, als Benachrichtigungsschwellenwert ein.
Geben Sie für Notify die E-Mail-Adressen ein, die Benachrichtigungs-E-Mails erhalten sollen.
Wählen Sie Next aus.
Für Budget scope fügen Sie das Tag auf dem Cortex Agent-Objekt zum Ressourcenbudget hinzu.
Wählen Sie Create aus.

Erstellen Sie eine Budgetinstanz in dem Schema, in dem Sie Budgets verwalten:

-- Create a budget instance
USE SCHEMA budgets_db.budgets_schema;

CREATE SNOWFLAKE.CORE.BUDGET my_budget();

Legen Sie für das Budget das monatliche Credit-Ausgabenlimit fest:
```
-- Set a 10000-credit monthly spending limit
CALL my_budget!SET_SPENDING_LIMIT(10000);
```

Fügen Sie das Tag zum Budget hinzu, damit Snowflake die Ausgaben für das getaggte Objekt anhand dieses Budgets verfolgt:

-- Associate the cost center tag with the budget
CALL budgets_db.budgets_schema.my_budget!SET_RESOURCE_TAGS(
   [
      [(SELECT SYSTEM$REFERENCE('TAG',
         'cost_mgmt_db.tags.cost_center',
         'SESSION',
         'applybudget')),
         'org-level']
   ],
   'UNION');

Jetzt verfolgt Snowflake den Credit-Verbrauch für my_agent anhand des my_budget-Budgets mit einem monatlichen Limit von 10.000 Credits.

Schwellenwert-Aktionen konfigurieren¶

Sie können gespeicherte Prozeduren anhängen, die ausgeführt werden, wenn die Ausgaben bestimmte Schwellenwerte erreicht haben, die als Prozentsatz der Ausgabenbeschränkung ausgedrückt werden und für den monatlichen Budgetzeitraum gelten. Weitere Informationen dazu finden Sie unter Kundenspezifische Aktionen für Budgets.

Benachrichtigungen senden¶

Sie können Benachrichtigungen senden, wenn die Ausgaben einen Schwellenwert erreichen. Weitere Informationen dazu finden Sie unter Benachrichtigungen für Budgets.

Legen Sie die E-Mail-Adresse fest, an die Benachrichtigungen gesendet werden sollen:

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

Legen Sie den Schwellenwert für die Benachrichtigung fest:
```
CALL my_budget!SET_NOTIFICATION_THRESHOLD(80);
```

Zugriff entziehen¶

Erstellen Sie eine gespeicherte Prozedur, die den Zugriff auf Cortex Agents widerruft. In der gespeicherten Prozedur können Sie den Zugriff auf eine bestimmte Rolle beschränken, um USAGE für diese Rolle zu widerrufen.
```
-- 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;
```
Wichtig

Stellen Sie sicher, dass der role_name und der Benutzende keinen Zugriff auf Cortex Agents durch andere Rollen haben. Eine Anleitung zur korrekten Konfiguration von Rollen und Berechtigungen finden Sie unter Benutzerberechtigungen und Zugriffssteuerung.

Legen Sie eine kundenspezifische Aktion fest, die den Zugriff blockiert, wenn 100 % des Budgets ausgegeben wurden. Sie können auch kundenspezifische Aktionen für Benachrichtigungen verwenden.

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

Bemerkung

Sie können auch kundenspezifische Aktionen verwenden oder Maßnahmen ergreifen, wenn die Ausgaben voraussichtlich das Budgetlimit überschreiten werden. Weitere Informationen dazu finden Sie unter Kundenspezifische Aktionen für Budgets.

Ausnahmen für Ausgabenlimits¶

In einigen Fällen müssen Sie den Zugang nach Erreichen der Budgetbeschränkung möglicherweise wiederherstellen, z. B. während der Einnahmenphase oder zu anderen Spitzenzeiten. Sie können Schwellenwerte über 100 % bis zu 500 % konfigurieren, um diese Ausnahmeszenarios zu verwalten.

Der Workflow geht davon aus, dass der Zugriff mit der konfigurierten gespeicherten Prozedur widerrufen wird, wenn die Ausgaben einen Schwellenwert für das Budget erreicht haben. Der Benutzende mit Administratorrechten stellt eine Teilmenge der Benutzenden wieder her und gewährt wieder Zugriff. Wenn die Ausgaben 200 % erreicht haben, wird das Widerrufsverfahren erneut als harter Stopp ausgeführt.

Erstellen Sie eine gespeicherte Prozedur, um den Zugriff auf die Rolle wiederherzustellen:

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

Konfigurieren Sie einen Schwellenwert von über 100 % mit einer gespeicherten Prozedur, die den Zugriff wiederherstellt. Auf diese Weise können Sie das effektive Budget für Ausnahmezeiträume erhöhen. Der Zugriff wird erneut widerrufen, wenn die Ausgaben 200 % des Budgets erreicht haben:

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

Zugriff wiederherstellen¶

Um sicherzustellen, dass Benutzende zu Beginn des nächsten Budgetzeitraums erneut auf Cortex Agents zugreifen können, stellen Sie die folgende gespeicherte Prozedur ein, die aufgerufen wird, wenn der Budgetzyklus neu gestartet wird.

Erstellen Sie eine gespeicherte Prozedur, um den Zugriff auf die Rolle wiederherzustellen:

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

Legen Sie die Zyklusstartaktion für das Budget fest:

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

Einrichten von Benachrichtigungen auf Grundlage der voraussichtlichen Ausgaben¶

Um eine Benachrichtigung zu erhalten oder eine Aktion auszuführen, die auf den prognostizierten Ausgaben und nicht auf den tatsächlichen Ausgaben basiert, können Sie den Auslösetyp auf PROJECTED festlegen. Um beispielsweise eine gespeicherte Prozedur mit dem Namen alert_team aufzurufen, wenn der projizierte Verbrauch 75 % des Budgetlimits erreicht hat, führen Sie den folgenden Befehl aus:

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

Kundenspezifische Aktionen auflisten¶

Um alle für ein Budget konfigurierten kundenspezifischen Aktionen aufzulisten, verwenden Sie die Methode GET_CUSTOM_ACTIONS:
-- View all custom actions on the budget CALL budgets_db.budgets_schema.my_budget!GET_CUSTOM_ACTIONS();

Weitere Informationen dazu finden Sie unter Kundenspezifische Aktionen für Budgets.

Nutzung überwachen¶

Um den Credit-Verbrauch pro Cortex Agent-Objekt anzuzeigen, verwenden Sie die Nutzungsberichtsmethode des Budgets:

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

Die Ausgabe enthält die folgenden Spalten:

Spalte

Beschreibung

Typ des Dienstes

Die Dienstkategorie (AI)

Entitätstyp

Der Objekttyp (CORTEX_AGENT)

Entitäts-ID

Der eindeutige Bezeichner des Cortex Agent-Objekts

Name

Der Anzeigename des Cortex Agent-Objekts

Verwendete Credits

Die Gesamtzahl der Credits, die während des angegebenen Zeitraums verbraucht wurden

Credits-Cloud

Anzahl der verwendeten Credits für Clouddienste

Spalte	Beschreibung
Typ des Dienstes	Die Dienstkategorie (AI)
Entitätstyp	Der Objekttyp (CORTEX_AGENT)
Entitäts-ID	Der eindeutige Bezeichner des Cortex Agent-Objekts
Name	Der Anzeigename des Cortex Agent-Objekts
Verwendete Credits	Die Gesamtzahl der Credits, die während des angegebenen Zeitraums verbraucht wurden
Credits-Cloud	Anzahl der verwendeten Credits für Clouddienste

Latenz für die Durchsetzung des Budgets¶

Die Budgetberechnungen und die Durchsetzung von Schwellenwerten werden in regelmäßigen Abständen durchgeführt:

Snowflake berechnet den Credit-Verbrauch für das getaggte Cortex Agent-Objekt.
Das System evaluiert die Ausgaben anhand aller konfigurierten Schwellenwerte.
Wenn ein Schwellenwert erreicht ist, wird die zugehörige gespeicherte Prozedur ausgeführt.
Die Nutzungs-Dashboards werden mit den neuesten Zahlen aktualisiert.

Wenn Sie das Budget mit niedriger Latenz aktiviert haben, werden Ihre Budgets innerhalb von zwei Stunden nach Überschreitung des Budgets durchgesetzt. Andernfalls kann es bis zu acht Stunden dauern, nachdem das Budget zur Durchsetzung überschritten wurde. Sie können die Ausführung des Budgets häufiger auslösen, z. B. alle 60 Minuten, um das Aktualisierungsintervall zu reduzieren.

Warnung

Es gibt eine inhärente Verzögerung zwischen dem Verbrauch von Credits und dem Zeitpunkt, an dem das Budgetsystem die Schwellenwertüberschreitung feststellt. Während des Durchsetzungsintervalls können die Ausgaben den konfigurierten Schwellenwert überschreiten, bevor die Aktion ausgeführt wird. Planen Sie Ihre Schwellenwerte entsprechend. Legen Sie zum Beispiel eine Benachrichtigung auf 80 % fest, um Ihnen Zeit zu geben, zu reagieren, bevor die 100 %-Aktion ausgelöst wird.

Einschränkungen¶

Die folgenden Einschränkungen gelten für Ressourcenbudgets für Cortex Agents:

Nur Ressourcen für einzelne Teams: Ressourcenbudgets gelten für das gesamte Cortex Agent-Objekt.
Durchsetzungslatenz: Die Durchsetzung des Budgets erfolgt in einem periodischen Zyklus, und es kann nach dem Überschreiten des Budgets bis zu acht Stunden dauern, bis das Budget durchgesetzt ist. Die Ausgaben können während des Intervalls einen Schwellenwert überschreiten, bevor die Aktion ausgelöst wird.
Rollenbasierte Zugriffssperre: Um den Zugriff an einem Schwellenwert zu widerrufen, müssen Sie eine eigene Rolle für das Cortex Agent-Objekt erstellen.
Monatlicher Zeitraum: Budgets arbeiten mit einem monatlichen Zyklus. Sie können keine Zeiträume für Ressourcenbudgets konfigurieren.
Tag-Latenz: Wenn Sie ein Tag von einem Objekt ändern, kann es bis zu acht Stunden dauern, bis die Änderung in den Budgets berücksichtigt wird, die Tags verwenden. Weitere Informationen dazu finden Sie unter Kundenspezifische Budgets.
Einstiegspunkt bestimmt die Zuordnung: Wenn eine Anfrage in Snowflake Intelligence beginnt und einen Cortex Agent aufruft, wird diese Nutzung Snowflake Intelligence zugeordnet. Infolgedessen erfasst ein Budget, dessen Geltungsbereich nur von Cortex Agent getaggte Ressourcen umfasst (z. B. Tags, die nur auf Agenten angewendet werden), keine Credits von Anfragen, die in Snowflake Intelligence initiiert wurden, auch wenn diese Anfragen einen Cortex Agent aufrufen. Um diese Nutzung abzudecken, fügen Sie Snowflake Intelligence-Ressourcen im Budgetbereich hinzu, oder konfigurieren Sie ein separates |sf-intelligence|Ressourcenbudget (siehe :doc:`/user-guide/snowflake-cortex/snowflake-intelligence/si-resource-budgets`). Beachten Sie jedoch, dass |sf-intelligence|-bereichsbezogene Budgets für die gesamte Nutzung gelten, die den bereichsbezogenen Snowflake Intelligence-Objekten zugeordnet ist, und nicht nur für Anfragen, die einen bestimmten Cortex Agent aufrufen.