Cortex Agent-Anfragen überwachen¶

Cortex Agents protokollieren detaillierte Ablaufverfolgungen aller Konversationen zu Überwachungs- und Debugging-Zwecken. Bei der Überwachung können Sie auf den Konversationsverlauf eines Agenten zugreifen, der über Snowflake Intelligence oder die Agent-API bereitgestellt wird. Zusätzlich zum Konversationsverlauf können Sie die detaillierte Ablaufverfolgung des Planungsprozesses des Agenten, die Auswahl des Tools, die Ausführungsergebnisse und die letztendliche Antworterstellung überprüfen.

In Cortex Agent-Protokollen erfasste Informationen¶

Die Cortex Agent-Protokolle enthalten die folgenden Informationen:

Konversationsverlauf, der mit einem Thread verbunden ist
Ablaufverfolgung der Agentenausführung in folgenden Bereichen:
- LLM-Planung
- Ausführung des Tools (Cortex Search, Cortex Analyst, Websuche)
- LLM-Antworterstellung
- SQL-Ausführung
- Diagrammerstellung
Ein- und Ausgaben, die mit jedem Bereich verbunden sind
Benutzerfeedback zu jeder Antwort des Agenten

Zugriff auf Cortex Agent-Protokolle¶

Um die Cortex Agent-Konversationsprotokolle auf der Snowsight anzuzeigen, gehen Sie wie folgt vor:

Melden Sie sich bei Snowsight an.
Wählen Sie im Navigationsmenü die Option AI & ML » Agents aus.
Wählen Sie den Agenten aus, dessen Protokolle Sie einsehen möchten.
Navigieren Sie zum Bereich Monitoring der Agent-Ansicht.

Die Überwachungsprotokolle zu dem Agenten werden in der Ereignistabelle SNOWFLAKE.LOCAL.AI_OBSERVABILITY_EVENTS gespeichert. Die Einträge in dieser Tabelle können nicht geändert werden.

Die SNOWFLAKE.AI_OBSERVABILITY_READER-Anwendungsrolle gewährt nur Lesezugriff auf die Abfrage dieser Tabelle. Das Löschen von Zeilen ist nicht zulässig. Administratoren mit der SNOWFLAKE.AI_OBSERVABILITY_ADMIN-Anwendungsrolle können Einträge in SNOWFLAKE.LOCAL.AI_OBSERVABILITY_EVENTS löschen. Weitere Details dazu finden Sie unter Observability-Daten.

Bemerkung

Nicht ausgeblendete Felder in der Überwachung und UDTF-Ergebnisse

Eine Berechtigung auf Kontoebene, READ UNREDACTED AI OBSERVABILITY EVENTS TABLE, steuert, ob Rollen nicht redigierte Inhalte aus AI_OBSERVABILITY_EVENTS (vollständige Tool-Eingaben und -Ausgaben, vollständiger Konversationstext und Benutzerfeedback-Text) sehen können, wenn Sie Cortex Agent-Monitoring in Snowsight verwenden und wenn Sie die ``SNOWFLAKE.LOCAL`` Observability-benutzerdefinierten Tabellenfunktionen (UDTFs) aufrufen, die diese Ereignistabelle lesen. Ohne die Berechtigung können Rollen immer noch Metadaten in diesen Pfaden lesen (Toolnamen, Token-Nutzung, Latenz, Zusammenfassungen der Auswertungsablaufverfolgungen, Modellname und Schweregrad des Fehlers). Dies ändert nicht die Ausführung von ** Cortex Agent Evaluation**-Jobs oder die Evaluations-Erfahrung. Ein Kontoadministrator muss die Berechtigung erteilen, um nicht ausgeblendete Inhalte anzuzeigen. Weitere Details dazu finden Sie unter Kontoberechtigung READ UNREDACTED AI OBSERVABILITY EVENTS TABLE.

AI-Beobachtbarkeitsereignisse mit SQL abfragen¶

Die Überwachungsdaten für einen Agenten werden in SNOWFLAKE.LOCAL.AI_OBSERVABILITY_EVENTS gespeichert. Um diese Zeilen programmatisch zu lesen, verwenden Sie die GET_AI_OBSERVABILITY_EVENTS-Tabellenfunktion. Übergeben Sie den Datenbanknamen, Schemanamen, Objektnamen und den Agententyp CORTEX AGENT für einen Cortex Agent oder EXTERNAL AGENT für einen externen Agenten, der mit AIObservability </user-guide/snowflake-cortex/ai-observability>`verwendet wird (siehe :doc:/sql-reference/commands-external-agent`). Das Ergebnis hat dieselben Ereignistabellenspalten wie die zugrunde liegende Tabelle (zum Beispiel RECORD, RECORD_ATTRIBUTES, VALUE, TRACE und Zeitstempel). Sie können mit WHERE filtern, um sich auf bestimmte Arten von Ereignissen, Zeitbereiche oder Attribute zu konzentrieren.

Wenn agent_type EXTERNAL AGENT ist, reicht USAGE für diesen externen Agenten aus, um die Funktion aufzurufen; MONITOR gilt nicht. OWNERSHIP für den externen Agenten ist erforderlich, um das Objekt mit SQL zu ändern oder zu löschen.

Das folgende Beispiel gibt alle Beobachtbarkeitsereignisse für einen Agenten zurück:

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

Für Auswertungsausführungen, Warnungen und strukturierte Protokollzeilen können Sie auch GET_AI_OBSERVABILITY_LOGS und die auswertungsspezifischen Funktionen verwenden, die in Cortex Agent-Evaluierungen beschrieben sind. Informationen dazu, wie AI Observability die Ereignistabelle produktübergreifend verwendet, finden Sie unter Observability-Daten.

Von Benutzenden bereitgestelltes Feedback anzeigen¶

Das Feedback von Benutzern wird als Beobachtbarkeitsereignis gespeichert. Um nur Feedback-Ereignisse zurückzugeben, filtern Sie nach dem Namen des Datensatzes``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';

Die resultierenden Zeilen enthalten Informationen über den Agenten, den Benutzer, der das Feedback gegeben hat, den Feedbacktext sowie die Angabe, ob das Feedback positiv oder negativ war. Vollständige Argument- und Zugriffsdetails finden Sie unter GET_AI_OBSERVABILITY_EVENTS (SNOWFLAKE.LOCAL).

Zugriffssteuerung und Berechtigungen¶

Tipp

Ein Benutzer mit der ACCOUNTADMIN-Rolle kann die SNOWFLAKE.AI_OBSERVABILITY_READER-Anwendungsrolle zu jeder Rolle hinzufügen, sodass Benutzer schreibgeschützte Abfragen auf SNOWFLAKE.LOCAL.AI_OBSERVABILITY_EVENTS für das Cortex Agent-Monitoring ausführen können.

Um die Cortex Agent-Protokolle einsehen zu können, müssen Benutzer über die folgenden Berechtigungen verfügen:

OWNERSHIP- oder MONITOR-Berechtigungen für das AGENT-Objekt
Die Datenbankrolle CORTEX_USER

Im folgenden Beispiel wird die Rolle ACCOUNTADMIN verwendet, um eine neue agent_monitoring_user_role-Rolle mit den erforderlichen Berechtigungen zum Anzeigen der Cortex Agent-Protokolle zu erstellen. Diese neue Rolle wird dann some_user zugewiesen.

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;

Gewähren von Überwachungszugriff auf zukünftige Agenten¶

Um einer Rolle die Überwachung von Zugriff auf zukünftige Agenten zu gewähren, die in einem Schema erstellt wurden, verwenden Sie folgenden SQL-Befehl:

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