Cortex Agentのリクエストのモニター

Cortex Agentは、監査とデバッグの目的で、すべての会話の詳細なトレースをログ記録します。モニタリングにより、Snowflake IntelligenceまたはAgent API を介してデプロイされたAgentの会話履歴にアクセスできます。会話履歴に加えて、エージェントの計画プロセス、ツールの選択、実行結果、最終的な応答生成の詳細なトレースを精査できます。

Cortex Agentログで収集される情報

Cortex Agentのログには以下の情報が含まれます。

  • スレッドに関連する会話履歴

  • 次を含むスパンによるエージェントの実行トレース。

    • LLM 計画

    • ツール実行（Cortex Search、Cortex Analyst、ウェブ検索）

    • LLM 応答生成

    • SQL 実行

    • チャート生成

  • 各スパンに関連付けられた入出力

  • 各エージェントの応答に対するユーザーのフィードバック

Cortex Agentログにアクセスする

Snowsight でCortex Agentの会話ログを表示するには、次の操作を実行します。

  1. Snowsight にサインインします。

  2. ナビゲーションメニューで AI & ML » Agents を選択します。

  3. ログを表示するAgentを選択します。

  4. Agentビューの Monitoring ページに移動します。

Agentに関連付けられたモニタリングログは、 イベントテーブル SNOWFLAKE.LOCAL.AI_OBSERVABILITY_EVENTS に格納されます。このテーブルのエントリは変更できません。

SNOWFLAKE.AI_OBSERVABILITY_READER アプリケーションロールは、そのテーブルをクエリするための読み取り専用アクセスを付与します。行の削除は許可されません。SNOWFLAKE.AI_OBSERVABILITY_ADMIN アプリケーションロールを持つ管理者は、 SNOWFLAKE.LOCAL.AI_OBSERVABILITY_EVENTS のエントリーを削除できます。詳細については、 観測可能データ をご参照ください。

注釈

モニタリングの編集されていないフィールドと UDTF 結果

アカウントレベルの権限である READ UNREDACTED AI OBSERVABILITY EVENTS TABLE は、 Cortex Agentモニタリング を Snowsight で使用する場合と、そのイベントテーブルを読み取る ``SNOWFLAKE.LOCAL`` 可観測性 ユーザー定義テーブル関数 （ UDTFs ）を呼び出す場合に、ロールが AI_OBSERVABILITY_EVENTS の 編集されていない コンテンツ（完全なツールの入出力、完全な会話テキスト、ユーザーフィードバックテキスト）を表示できるかどうかを制御します。付与なしでも、ロールはこれらのパスの メタデータ （ツール名、トークンの使用状況、レイテンシ、評価トレースの概要、モデル名、エラーの重大度）を読み取ることができます。これは、 Cortex Agent評価 ジョブの実行、スコアリング、 評価 エクスペリエンスを変更 しません 。アカウント管理者は、編集されていないコンテンツを表示するための権限を付与する必要があります。詳細については、 アカウント権限 READ UNREDACTED AI OBSERVABILITY EVENTS TABLE をご参照ください。

SQL を使用したクエリ AI 可観測性イベント

エージェントのデータのモニタリングは SNOWFLAKE.LOCAL.AI_OBSERVABILITY_EVENTS に保存されます。これらの行をプログラムで読み取るには、 GET_AI_OBSERVABILITY_EVENTS テーブル関数を使用します。データベース名、スキーマ名、オブジェクト名、エージェントタイプ（Cortex Agentの場合は CORTEX AGENT 、 AI 可観測性 で使用される外部エージェントの場合は EXTERNAL AGENT ）を渡します（ 外部エージェントコマンド 参照）。結果には、基になるテーブルと同じ イベントテーブル列 があります（例: RECORD 、 RECORD_ATTRIBUTES 、 VALUE 、 TRACE およびタイムスタンプ）。WHERE でフィルタリングして、特定のイベントの種類、時間範囲、または属性に焦点を当てることができます。

agent_type が EXTERNAL AGENT である場合、外部エージェントに対する USAGE は関数を呼び出すのに十分です。 MONITOR は適用されません。外部エージェントに対する OWNERSHIP は、 SQL でオブジェクトを変更またはドロップするために必要です。

次の例は、エージェントのすべての可観測性イベントを返します。

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

評価実行、警告、構造化されたログ行の場合は、 GET_AI_OBSERVABILITY_LOGS および Cortex Agentの評価 で説明されている評価固有の関数も使用できます。AI 可観測性による製品全体でのイベントテーブルの使用方法については、 観測可能データ をご参照ください。

ユーザーから提供されたフィードバックを表示する

エンドユーザーのフィードバックは可観測性イベントとして保存されます。フィードバックイベント のみ を返すには、記録名 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';

結果の行には、エージェント、フィードバックを提供したユーザー、フィードバックテキスト、フィードバックが肯定的か否定的かに関する情報が含まれます。完全な引数とアクセスの詳細については、 GET_AI_OBSERVABILITY_EVENTS (SNOWFLAKE.LOCAL) をご参照ください。

アクセス制御と権限

Tip

ACCOUNTADMIN ロールを持つユーザーは SNOWFLAKE.AI_OBSERVABILITY_READER アプリケーションロールを任意のロールに追加できます。これにより、ユーザーはCortex Agentのモニタリングのために SNOWFLAKE.LOCAL.AI_OBSERVABILITY_EVENTS に対して読み取り専用のクエリを実行できます。

Cortex Agentのログを表示するには、ユーザーは以下の権限を持っている必要があります。

  • AGENT オブジェクトに対する OWNERSHIP または MONITOR 権限

  • CORTEX_USER データベースロール

次の例では、ACCOUNTADMIN ロールを使用して、Cortex Agentログの表示に必要な権限を持つ新しいロール agent_monitoring_user_role を作成します。この新しいロールは、その後 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;

将来のエージェントにモニタリングアクセス権を付与する

スキーマに将来作成されるエージェントに対してロールのモニタリングアクセス権を付与するには、以下の SQL コマンドを使用します。

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