Orçamentos de recursos para Cortex Agents

Um orçamento de recursos permite que você monitore os gastos dos Cortex Agents em sua conta e tome medidas quando excederem os limites. Isso permite controlar os custos dos Cortex Agents e executar ações automatizadas, como revogar o acesso quando os gastos excedem os limites configurados. Os orçamentos de recursos dão a você controle sobre os créditos consumidos em um nível agregado para um determinado agente.

Como funcionam os orçamentos de recursos

Os orçamentos de recursos usam o modelo de atribuição de custos com base em tags do Snowflake. Você cria e aplica uma tag a um objeto do Cortex Agent e, depois disso, associa essa tag a um orçamento. O Snowflake rastreia o consumo de crédito do objeto marcado e avalia os gastos em relação ao limite de orçamento periodicamente. O orçamento de recursos é útil para limitar os gastos do objeto do Cortex Agent.

O Snowflake aplica os orçamentos de recursos com o seguinte fluxo:

  1. Você cria uma tag.

  2. Você aplica a tag ao objeto do Cortex Agent.

  3. Você cria um orçamento e especifica a tag para rastrear os gastos. Como parte da criação do orçamento, você também define um limite de gastos mensal em créditos.

  4. Você adiciona um procedimento armazenado a ser executado quando os gastos atingem um limite configurado do orçamento. Por exemplo, você pode invocar um procedimento armazenado para enviar um alerta ao atingir 80% e outro procedimento armazenado para revogar o acesso ao atingir 100%.

  5. O Snowflake rastreia o consumo de crédito do objeto marcado.

  6. Quando os gastos atingem um limite configurado do orçamento, como 80% ou 100%, o Snowflake executa o procedimento armazenado definido para esse limite.

O Snowflake calcula o uso, avalia os limites e aciona periodicamente as ações configuradas. Depois que o orçamento é excedido, pode levar até oito horas com o orçamento padrão (ou duas horas com a opção de latência otimizada) para que o orçamento seja aplicado.

Crie uma tag

  1. Crie uma tag para identificar o centro de custo associado ao objeto do 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. Aplique a tag ao objeto do Cortex Agent para associá-lo a um centro de custo:

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

Configurar um orçamento de recursos

Você pode usar o Snowsight ou o SQL para criar um orçamento e associá-lo a um objeto do Cortex Agent.

  1. Faça login no Snowsight.

  2. No menu de navegação, selecione Admin » Cost management.

  3. Selecione Budgets.

  4. Selecione + Budget.

  5. Em Location to store, selecione o nome do banco de dados e do esquema em que você deseja criar o orçamento.

  6. Para Name, use my_budget:

  7. Em Budget (credits per month), insira um valor, como 10000, para o limite de gastos do orçamento.

  8. Para diminuir o intervalo de atualização do orçamento para que você possa monitorar os gastos em mais detalhes, selecione Enable low latency budget.

  9. Em Threshold, insira um valor, como 80, para o limite de notificação.

  10. Em Notify, insira os endereços de e-mail para receber as mensagens de notificação.

  11. Selecione Next.

  12. Em Budget scope, adicione a tag no objeto do Cortex Agent ao orçamento de recursos.

  13. Selecione Create.

Agora o Snowflake rastreia o consumo de crédito de my_agent em relação ao orçamento my_budget com um limite mensal de 10.000 créditos.

Configurar ações de limite

Você pode anexar procedimentos armazenados que são executados quando os gastos atingem limites específicos, que são expressos como uma porcentagem do limite de gastos e aplicados ao período de orçamento mensal. Para obter mais informações, consulte Ações personalizadas para orçamentos.

Enviar notificações

Você pode enviar notificações quando os gastos atingirem um limite. Para obter mais informações, consulte Notificações sobre orçamentos.

  1. Defina o e-mail para o qual enviar as notificações:

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

  2. Defina o limite de notificação:

    CALL my_budget!SET_NOTIFICATION_THRESHOLD(80);

Revogar acesso

  1. Crie um procedimento armazenado que revogue o acesso aos Cortex Agents. No procedimento armazenado, você pode limitar o acesso a uma função específica para revogar USAGE para essa função.

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

    Importante

    Assegure que role_name e o usuário não tenham acesso aos Cortex Agents por meio de outras funções. Para obter orientação sobre como configurar corretamente as funções e os privilégios, consulte Privilégios de usuário e controle de acesso.

  2. Defina uma ação personalizada que bloqueie o acesso quando 100% do orçamento tiver sido gasto. Você também pode usar ações personalizadas para notificações.

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

Nota

Você também pode usar ações personalizadas para executar uma ação quando há previsão de que os gastos vão exceder o limite de orçamento. Para obter mais informações, consulte Ações personalizadas para orçamentos.

Tratando as exceções aos limites de gastos

Em alguns casos, talvez seja necessário restabelecer o acesso após o limite de orçamento ter sido atingido, por exemplo, durante o período de balanço financeiro ou outras temporadas de pico. Você pode configurar limites acima de 100%, até 500%, para abordar esses cenários de exceção.

O fluxo de trabalho pressupõe que o acesso seja revogado usando o procedimento armazenado configurado quando os gastos atingirem um limite de orçamento. O administrador restabelece um subconjunto de usuários e concede o acesso novamente. Quando os gastos atingem 200%, o procedimento de revogação é executado novamente como uma parada obrigatória.

  1. Crie um procedimento armazenado para restabelecer o acesso à função:

    -- 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. Configure um limite acima de 100% com um procedimento armazenado que restabeleça o acesso. Isso permite aumentar o orçamento efetivo nos períodos de exceção. O acesso é revogado novamente quando os gastos atingem 200% do orçamento:

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

Restabelecer o acesso

Para garantir que os usuários possam acessar os Cortex Agents novamente no início do próximo período de orçamento, defina o seguinte procedimento armazenado para ser chamado quando o ciclo orçamentário for reiniciado.

  1. Crie um procedimento armazenado para restabelecer o acesso à função:

    -- 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. Defina a ação de início do ciclo para o orçamento:

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

Configurando alertas com base em gastos projetados

Para receber um alerta ou executar uma ação com base nos gastos previstos em vez dos gastos reais, você pode definir o tipo de acionador como PROJECTED. Por exemplo, para chamar um procedimento armazenado chamado alert_team quando o consumo projetado atingir 75% do limite de orçamento, execute o seguinte comando:

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

Listar ações personalizadas

  • Para listar todas as ações personalizadas configuradas em um orçamento, use o método GET_CUSTOM_ACTIONS:

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

Para obter mais informações, consulte Ações personalizadas para orçamentos.

Monitorar o uso

  • Para visualizar o consumo de crédito por objeto do Cortex Agent, use o método de relatório de uso do orçamento:

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

    A saída inclui as seguintes colunas:

    Coluna

    Descrição

    Tipo de serviço

    A categoria de serviço (AI)

    Tipo de entidade

    O tipo de objeto (CORTEX_AGENT)

    ID da entidade

    O identificador exclusivo do objeto do Cortex Agent

    Nome

    O nome de exibição do objeto do Cortex Agent

    Créditos utilizados

    O total de créditos consumidos durante o período especificado

    Nuvem de créditos

    Número de créditos de serviço de nuvem usados

Latência da aplicação do orçamento

Os cálculos de orçamento e a aplicação de limites são realizados periodicamente:

  1. O Snowflake calcula o consumo de crédito do objeto do Cortex Agent marcado.

  2. O sistema avalia os gastos em relação a todos os limites configurados.

  3. Se um limite for atingido, o procedimento armazenado associado será executado.

  4. Os painéis de uso são atualizados com os números mais recentes.

Se você habilitou o orçamento de baixa latência, seus orçamentos são aplicados em duas horas depois que o orçamento é excedido. Caso contrário, a aplicação poderá levar até oito horas depois que o orçamento for excedido. Você pode acionar a execução do orçamento com mais frequência, como a cada 60 minutos, para reduzir o intervalo de atualização.

Aviso

Há um atraso inerente entre o momento em que os créditos são consumidos e o momento em que o sistema de orçamento detecta a violação de limite. Durante o intervalo de aplicação, os gastos podem exceder o limite configurado antes que a ação seja executada. Planeje seus limites de acordo com isso. Por exemplo, defina um alerta quando atingir 80% para que você tenha tempo de responder antes que a ação de 100% seja executada.

Limitações

As seguintes limitações se aplicam aos orçamentos de recursos dos Cortex Agents:

  • Somente recursos de equipe única: os orçamentos de recursos se aplicam ao objeto inteiro do Cortex Agent.

  • Latência de aplicação: a aplicação do orçamento é executada em um ciclo periódico e pode levar até oito horas depois que o orçamento é excedido para aplicar o orçamento. Os gastos podem exceder um limite durante o intervalo antes que a ação seja acionada.

  • Revogação de acesso baseada em função: para revogar o acesso a um limite, é necessário criar uma função dedicada para o objeto do Cortex Agent.

  • Período mensal: os orçamentos operam em um ciclo mensal. Não é possível configurar períodos de orçamento de recursos.

  • Latência de tag: quando você altera uma tag em um objeto, pode levar até oito horas para que a alteração seja refletida nos orçamentos que usam a tag. Para obter mais informações, consulte Orçamentos personalizados.

  • O ponto de entrada determina a atribuição: se uma solicitação começar no Snowflake Intelligence e invocar um Cortex Agent, esse uso será atribuído ao Snowflake Intelligence. Como resultado, um orçamento com um escopo que inclui apenas recursos marcados pelo Cortex Agent (por exemplo, tags aplicadas apenas a agentes) não captura créditos de solicitações iniciadas no Snowflake Intelligence, mesmo quando essas solicitações invocam um Cortex Agent. Para cobrir esse uso, inclua recursos do Snowflake Intelligence no escopo do orçamento ou configure um orçamento de recursos do Snowflake Intelligence separado (consulte Orçamentos de recursos para o Snowflake Intelligence). Entretanto, observe que os orçamentos com escopo do Snowflake Intelligence se aplicam a todos os usos atribuídos aos objetos do Snowflake Intelligence no escopo, não apenas às solicitações que invocam um Cortex Agent específico.