Monitoramento de solicitações de Cortex Agents

Os Cortex Agents registram em log os rastreamentos detalhados de todas as conversas para fins de auditoria e depuração. Com o monitoramento, você pode acessar o histórico da conversa de um agente implantado via Snowflake Intelligence ou API Agent. Além do histórico da conversa, você pode revisar o rastreamento detalhado do processo de planejamento do agente, seleção de ferramentas, resultados de execução e geração de respostas finais.

Informações coletadas em logs do Cortex Agent

Os logs do Cortex Agent incluem as seguintes informações:

  • Histórico de conversas associado a um thread

  • Rastreamento de execução do agente com intervalos, incluindo:

    • Planejamento de LLM

    • Execução de ferramentas (Cortex Search, Cortex Analyst, pesquisa na Web)

    • Geração de resposta deLLM

    • Execução de SQL

    • Geração de gráficos

  • Entradas e saídas associadas a cada intervalo

  • Feedback do usuário para cada resposta do agente

Acesso aos logs do Cortex Agent

Para visualizar os logs de conversas do Cortex Agent no Snowsight, faça o seguinte:

  1. Faça login no Snowsight.

  2. No menu de navegação, selecione AI & ML » Agents.

  3. Selecione o agente cujos logs você deseja visualizar.

  4. Navegue até o painel Monitoring da exibição do agente.

Os logs de monitoramento associados ao agente são armazenados na tabela de eventos SNOWFLAKE.LOCAL.AI_OBSERVABILITY_EVENTS. As entradas nessa tabela não podem ser modificadas.

A função de aplicativo SNOWFLAKE.AI_OBSERVABILITY_READER concede acesso somente leitura para consultar essa tabela. Ela não permite excluir linhas. Administradores com a função de aplicativo SNOWFLAKE.AI_OBSERVABILITY_ADMIN podem excluir entradas de SNOWFLAKE.LOCAL.AI_OBSERVABILITY_EVENTS. Para obter mais detalhes, consulte Dados de observabilidade.

Nota

Campos não ocultos nos resultados de monitoramento e UDTF

Um privilégio no nível da conta, READ UNREDACTED AI OBSERVABILITY EVENTS TABLE, controla se as funções podem ver o conteúdo não oculto de AI_OBSERVABILITY_EVENTS (entradas e saídas completas de ferramentas, texto completo de conversação e texto de feedback do usuário) quando você usa o monitoramento do Cortex Agent no Snowsight e chama as funções de tabela definidas pelo usuário (User-Defined Table Functions, UDTFs) de observabilidade SNOWFLAKE.LOCAL que leem essa tabela de eventos. Sem a concessão, as funções ainda podem ler os metadados nesses caminhos (nomes de ferramentas, uso de tokens, latência, resumos de rastreamento de avaliação, nome do modelo e gravidade de erros). Isso não altera a execução do trabalho de avaliação do Cortex Agent, a pontuação nem a experiência das avaliações. Um administrador da conta deve conceder o privilégio para ver o conteúdo não oculto. Para obter detalhes, consulte Privilégio de conta READ UNREDACTED AI OBSERVABILITY EVENTS TABLE.

Consultar eventos de observabilidade de AI com SQL

Os dados de monitoramento de um agente são armazenados em SNOWFLAKE.LOCAL.AI_OBSERVABILITY_EVENTS. Para ler as linhas programaticamente, use a função de tabela GET_AI_OBSERVABILITY_EVENTS. Passe o nome do banco de dados, o nome do esquema, o nome do objeto e o tipo de agente CORTEX AGENT para um Cortex Agent, ou EXTERNAL AGENT para um External Agent usado com observabilidade de AI (consulte External Agent commands). O resultado tem as mesmas colunas de tabela de eventos que a tabela subjacente (por exemplo RECORD, RECORD_ATTRIBUTES, VALUE, TRACE e carimbos de data/hora). Você pode filtrar com WHERE para se concentrar em tipos de eventos, intervalos de tempo ou atributos específicos.

Quando agent_type é EXTERNAL AGENT, USAGE nesse External Agent é suficiente para chamar a função. MONITOR não se aplica. OWNERSHIP no External Agent é necessário para modificar ou descartar o objeto com SQL.

O exemplo a seguir retorna todos os eventos de observabilidade de um agente:

SELECT *
  FROM TABLE(SNOWFLAKE.LOCAL.GET_AI_OBSERVABILITY_EVENTS(
    '<database_name>',
    '<schema_name>',
    '<agent_name>',
    'CORTEX AGENT'
  ));

Para execuções de avaliação, avisos e linhas de log estruturadas, você também pode usar GET_AI_OBSERVABILITY_LOGS e as funções específicas de avaliação, conforme descrito em Avaliações do Cortex Agent. Para saber como a observabilidade de AI usa a tabela de eventos nos vários produtos, consulte Dados de observabilidade.

Visualizar o feedback fornecido pelos usuários

O feedback do usuário final é armazenado como evento de observabilidade. Para retornar somente eventos de feedback, filtre pelo nome do registro CORTEX_AGENT_FEEDBACK:

SELECT *
  FROM TABLE(SNOWFLAKE.LOCAL.GET_AI_OBSERVABILITY_EVENTS(
    '<database_name>',
    '<schema_name>',
    '<agent_name>',
    'CORTEX AGENT'
  ))
  WHERE RECORD:name = 'CORTEX_AGENT_FEEDBACK';

As linhas resultantes incluem informações sobre o agente, o usuário que forneceu o feedback, o texto do feedback e se o feedback foi positivo ou negativo. Para obter detalhes completos de acesso e argumento, consulte GET_AI_OBSERVABILITY_EVENTS (SNOWFLAKE.LOCAL).

Controle de acesso e permissões

Dica

Um usuário com a função ACCOUNTADMIN pode adicionar a função de aplicativo SNOWFLAKE.AI_OBSERVABILITY_READER a qualquer função, para que os usuários possam executar consultas somente leitura em SNOWFLAKE.LOCAL.AI_OBSERVABILITY_EVENTS para monitoramento do Cortex Agent.

Para visualizar os logs do Cortex Agent, os usuários devem ter os seguintes privilégios:

  • Privilégios OWNERSHIP ou MONITOR no objeto AGENT

  • A função de banco de dados CORTEX_USER

O exemplo a seguir usa a função ACCOUNTADMIN para criar uma nova função agent_monitoring_user_role com as permissões necessárias para visualizar os logs do Cortex Agent. Essa nova função é então atribuída a some_user.

USE ROLE ACCOUNTADMIN;
CREATE ROLE agent_monitoring_user_role;
GRANT MONITOR ON AGENT my_agent TO ROLE agent_monitoring_user_role;
GRANT DATABASE ROLE SNOWFLAKE.CORTEX_USER TO ROLE agent_monitoring_user_role;
GRANT ROLE agent_monitoring_user_role TO USER some_user;

Conceder acesso de monitoramento a agentes futuros

Para conceder a um função de acesso de monitoramento em agentes futuros criados em um esquema, use o seguinte comando SQL:

GRANT MONITOR ON FUTURE AGENTS IN SCHEMA <database_name>.<schema_name> TO ROLE <role_name>;