カテゴリ：: :doc:`/sql-reference/functions-table`（Cortex Agents）

GET_AI_RECORD_TRACE (SNOWFLAKE.LOCAL)¶

Cortex Agentの評価実行から単一のトレース記録を取得します。

Cortex Agentの完全な評価から単一の記録を確認する場合は、この関数を呼び出します。詳細については、 Cortex Agentの評価をご参照ください。

こちらもご参照ください。: EXECUTE_AI_EVALUATION、 GET_AI_EVALUATION_DATA (SNOWFLAKE.LOCAL)、 GET_AI_OBSERVABILITY_LOGS (SNOWFLAKE.LOCAL)

構文¶

SNOWFLAKE.LOCAL.GET_AI_RECORD_TRACE( <database> , <schema> , <agent_name> , <agent_type> , <record_id> )

引数¶

database: エージェントが含まれるデータベースの名前。
schema: エージェントが含まれるスキーマの名前。
agent_name: 記録を取得するエージェントの名前。
agent_type: 文字列定数``CORTEX AGENT``。この値では大文字と小文字が区別されません。
record_id: 取得する記録識別子。

戻り値¶

要求されたトレースに関する情報を含むテーブルで、次の列があります。


列	データ型	説明
RECORD_ID	VARCHAR	この評価記録に対してSnowflakeによって割り当てられた一意の識別子。
INPUT_ID	VARCHAR	この評価入力に対してSnowflakeによって割り当てられた一意の識別子。
REQUEST_ID	VARCHAR	このリクエストに対してSnowflakeによって割り当てられた一意の識別子。
TIMESTAMP	TIMESTAMP_TZ	リクエストが実行された時間（UTC）。
DURATION_MS	INT	エージェントが応答を返すまでにかかった時間（ミリ秒単位）。
INPUT	VARCHAR	この評価記録の入力として使用されたクエリ文字列。
OUTPUT	VARCHAR	この評価記録に対してCortex Agentが返した応答。
ERROR	VARCHAR	リクエスト中に発生したエラーに関する情報。
GROUND_TRUTH	VARCHAR	この記録のCortex Agentの出力を評価するために使用されるグランドトゥルースの情報。
METRIC_NAME	VARCHAR	この記録で評価されたメトリックの名前。
EVAL_AGG_SCORE	NUMBER	この記録に割り当てられた評価スコア。
METRIC_TYPE	VARCHAR	評価対象のメトリックの型。組み込みメトリックの場合、値は``system``。カスタムメトリックの場合、値は``custom``。
METRIC_STATUS	VARIANT	この記録のエージェントのHTTP応答に関する情報を含むマップ。以下のキーがある。 `status`:応答のHTTPステータスコード。 `message`:ステータス応答で送信されたHTTPメッセージ。
METRIC_CALLS	ARRAY	計算されたメトリックに関する情報を含むVARIANT値の配列。各配列エントリには、メトリックの基準、メトリックスコアの説明、メタデータが含まれる。各エントリのキーは以下のとおり。 `criteria`:LLMジャッジが応答の正確性を評価するために使用する基準。 `explanation`:スコアが割り当てられた理由の説明。 `full_metadata`:このメトリックのLLMジャッジによる処理に関するメタデータと情報を含むVARIANT値。このマップのキーは以下のとおり。 `completion_tokens`:このメトリック評価呼び出しのためにLLMによって生成された出力トークン数。 `guard_tokens`:このメトリック評価呼び出しのためにCortex Guardが消費したトークン数。 `normalized_score`:元の評価スコアを範囲[0.0, 1.0]に正規化し、小数点以下2桁に四捨五入した値。 `original_score`:このメトリック評価で記録に割り当てられた元のスコア。 `prompt_tokens`:LLMジャッジに提供されたプロンプトによって消費されたトークン数。 `total_tokens`:この計算でLLMジャッジによって使用されたトークン総数。
TOTAL_INPUT_TOKENS	INT	入力クエリの処理に使用されたトークン総数。
TOTAL_OUTPUT_TOKENS	INT	Cortex Agentによって生成された出力トークンの総数。
LLM_CALL_COUNT	INT	エージェントと評価ジャッジのいずれかによってLLMが呼び出された回数の合計。

アクセス制御の要件¶

この操作の実行に使用されるロールには、少なくとも次の権限が必要です。


権限	オブジェクト	メモ
CORTEX_USER	データベースロール
USAGE	Cortex Agent
MONITOR	Cortex Agent

スキーマ内のオブジェクトを操作するには、親データベースの少なくとも1つの権限と、親スキーマの少なくとも1つの権限が必要です。

指定された権限のセットを使用してカスタムロールを作成する手順については、カスタムロールの作成をご参照ください。

セキュリティ保護可能なオブジェクトに対して SQL アクションを実行するためのロールと権限付与に関する一般的な情報については、アクセス制御の概要をご参照ください。

Cortex Agent評価に必要な完全なアクセス制御権限について詳しくは、:ref:`Cortex Agent評価 -- アクセス制御要件<label-agent_evaluation_access_control>`をご参照ください。

例¶

次の例では、``eval_db.eval_schema``スキーマに格納されている``evaluated_agent``という名前のエージェントについて、記録``9346efc3-5dd6-4038-9b1a-72ca3d3b768c``のトレースを表示します。

SELECT * FROM TABLE(SNOWFLAKE.LOCAL.GET_AI_RECORD_TRACE(
  'eval_db',
  'eval_schema',
  'evaluated_agent',
  'CORTEX AGENT',
  '9346efc3-5dd6-4038-9b1a-72ca3d3b768c'
));