Surveiller les requêtes des Agents Cortex¶

Les Agents Cortex enregistrent des traces détaillées de toutes les conversations à des fins d’audit et de débogage. Grâce à la surveillance, vous pouvez accéder à l’historique de conversation d’un agent déployé via Snowflake Intelligence ou l’API d’agents. Outre l’historique des conversations, vous pouvez examiner le traçage détaillé du processus de planification des agents, de la sélection des outils, des résultats d’exécution et de la génération finale des réponses.

Informations collectées dans les journaux des Agents Cortex¶

Les journaux des Agents Cortex comprennent les informations suivantes :

Historique de conversation associé à un thread
Trace d’exécution des agents avec des spans incluant :
- Planification LLM
- Exécution de l’outil (Cortex Search, Cortex Analyst, recherche web)
- Génération de réponses LLM
- Exécution SQL
- Génération de graphiques
Entrées et sorties associées à chaque span
Commentaires de l’utilisateur pour chaque réponse d’agent

Accéder aux journaux des Agents Cortex¶

Pour voir les journaux de conversation des Agents Cortex dans Snowsight, procédez comme suit :

Connectez-vous à Snowsight.
Dans le menu de navigation, sélectionnez AI & ML » Agents.
Sélectionnez l’agent dont vous souhaitez voir les journaux.
Naviguez jusqu’au panneau de la vue Monitoring de l’agent.

Les journaux de surveillance associés à l’agent sont stockés dans le tableau des événements SNOWFLAKE.LOCAL.AI_OBSERVABILITY_EVENTS. Les entrées de cette table ne peuvent pas être modifiées.

Le rôle d’application SNOWFLAKE.AI_OBSERVABILITY_READER accorde un accès en lecture seule pour interroger cette table. La suppression de lignes n’est pas autorisée. Les administrateurs avec le rôle d’application SNOWFLAKE.AI_OBSERVABILITY_ADMIN peuvent supprimer des entrées dans SNOWFLAKE.LOCAL.AI_OBSERVABILITY_EVENTS. Pour plus de détails, voir Données d’observabilité.

Note

Champs non édités dans la surveillance et les résultats UDTF

Un privilège au niveau du compte, READ UNREDACTED AI OBSERVABILITY EVENTS TABLE, contrôle si les rôles peuvent voir le contenu non masqué de``AI_OBSERVABILITY_EVENTS`` (entrées et sorties de l’outil complet, texte de la conversation complet et texte de retour de l’utilisateur) lorsque vous utilisez la Surveillance Cortex Agent dans Snowsight et lorsque vous appelez les fonctions de table définies par l’utilisateur observabilité**``SNOWFLAKE.LOCAL`` (les UDTFs) qui lisent ce tableau d’événements. Sans l’attribution, les rôles peuvent toujours lire les métadonnées dans ces chemins (noms des outils, utilisation des jetons, latence, résumés des traces d’évaluation, nom du modèle et gravité des erreurs). Cela ne modifie pas l’exécution des tâches d’évaluation Cortex Agent, la notation ou l’expérience Évaluations. Un administrateur de compte doit accorder le privilège pour voir le contenu non masqué ; pour plus de détails, voir Privilège de compte READ UNREDACTED AI OBSERVABILITY EVENTS TABLE.

Interroger les événements d’observabilité AI avec SQL¶

Les données de surveillance d’un agent sont stockées dans``SNOWFLAKE.LOCAL.AI_OBSERVABILITY_EVENTS``. Pour lire ces lignes de manière programmatique, utilisez la fonction de table GET_AI_OBSERVABILITY_EVENTS. Indiquez le nom de la base de données, le nom du schéma, le nom de l’objet et le type d’agent CORTEX AGENT pour un Cortex Agent ou EXTERNAL AGENT pour un Agent externe utilisé avec l’observabilité AI (voir Commandes External Agent). Le résultat a les mêmes :doc:` colonnes de tableau d’événements </developer-guide/logging-tracing/event-table-columns>` comme table sous-jacente (par exemple RECORD, RECORD_ATTRIBUTES, VALUE, TRACE et horodatages). Vous pouvez filtrer avec WHERE pour privilégier des types d’événements, des plages de temps ou des attributs spécifiques.

Lorsque agent_type est EXTERNAL AGENT, USAGE sur cet Agent externe est suffisant pour appeler la fonction ; MONITOR ne s’applique pas. OWNERSHIP sur l’Agent externe est nécessaire pour modifier ou détruire l’objet avec SQL.

L’exemple suivant renvoie tous les événements d’observabilité pour un agent :

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

Pour les exécutions d’évaluation, les avertissements et les lignes de journal structurées, vous pouvez également utiliser GET_AI_OBSERVABILITY_LOGS et les fonctions spécifiques à l’évaluation décrites dans Évaluations Cortex Agent. Pour savoir comment l’observabilité AI utilise le tableau des événements dans les produits, voir Données d’observabilité.

Afficher les commentaires fournis par les utilisateurs¶

Les commentaires de l’utilisateur final sont stockés en tant qu’événements d’observabilité. Pour renvoyer uniquement les événements de commentaire, filtrez par nom d’enregistrement 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';

Les lignes résultantes contiennent des informations sur l’agent, l’utilisateur qui a fourni les commentaires, le texte des commentaires et le caractère positif ou négatif du retour de ceux-ci. Pour les détails complets sur les arguments et les accès, voir GET_AI_OBSERVABILITY_EVENTS (SNOWFLAKE.LOCAL).

Contrôle d’accès et autorisations¶

Astuce

Un utilisateur avec le rôle ACCOUNTADMIN peut ajouter le rôle d’application SNOWFLAKE.AI_OBSERVABILITY_READER à n’importe quel rôle afin que les utilisateurs puissent exécuter des requêtes en lecture seule sur SNOWFLAKE.LOCAL.AI_OBSERVABILITY_EVENTS pour la surveillance de Cortex Agent.

Pour voir les journaux des Agents Cortex, les utilisateurs doivent disposer des privilèges suivants :

Les privilèges OWNERSHIP ou MONITOR sur l’objet AGENT
Le rôle de base de données CORTEX_USER

L’exemple suivant utilise le rôle ACCOUNTADMIN pour créer un nouveau rôle agent_monitoring_user_role avec les autorisations requises pour voir les journaux des Agents Cortex. Ce nouveau rôle est ensuite attribué à 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;

Accorder l’accès à la surveillance aux futurs agents¶

Pour accorder un accès de surveillance du rôle sur de futurs agents créés dans un schéma, utilisez la commande SQL suivante :

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