Categories:: Table functions (Cortex Agents)

GET_AI_RECORD_TRACE (SNOWFLAKE.LOCAL)¶

Retrieve a single trace record from a Cortex Agent evaluation run.

Call this function when you want to inspect a single record from a complete Cortex Agent evaluation. For more information, see Cortex Agent evaluations.

See also:: EXECUTE_AI_EVALUATION , GET_AI_EVALUATION_DATA (SNOWFLAKE.LOCAL) , GET_AI_OBSERVABILITY_LOGS (SNOWFLAKE.LOCAL)

Syntax¶

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

Arguments¶

database: Name of the database containing the agent.
schema: Name of the schema containing the agent.
agent_name: Name of the agent to retrieve a record for.
agent_type: The string constant CORTEX AGENT. This value is case-insensitive.
record_id: The record identifier to retrieve.

Returns¶

A table containing information for the requested trace, with the following columns:


Column	Data type	Description
RECORD_ID	VARCHAR	The unique identifier assigned by Snowflake for this evaluation record.
INPUT_ID	VARCHAR	The unique identifier assigned by Snowflake for this evaluation input.
REQUEST_ID	VARCHAR	The unique identifier assigned by Snowflake for this request.
TIMESTAMP	TIMESTAMP_TZ	The time (in UTC) at which the request was made.
DURATION_MS	INT	The amount of time, in milliseconds, that it took for the agent to return a response.
INPUT	VARCHAR	The query string used as input for this evaluation record.
OUTPUT	VARCHAR	The response returned by the Cortex Agent for this evaluation record.
ERROR	VARCHAR	Information about any errors that occurred during the request.
GROUND_TRUTH	VARCHAR	The ground truth information used to evaluate this record’s Cortex Agent output.
METRIC_NAME	VARCHAR	The name of the metric evaluated for this record.
EVAL_AGG_SCORE	NUMBER	The evaluation score assigned for this record.
METRIC_TYPE	VARCHAR	The type of metric being evaluated. For built-in metrics, the value is `system`. For custom metrics, the value is `custom`.
METRIC_STATUS	VARIANT	A map containing information about the agent’s HTTP response for this record, with the following keys: `status`: The HTTP status code of the response. `message`: The HTTP message sent in the status response.
METRIC_CALLS	ARRAY	An array of VARIANT values that contain information about the the computed metric. Each array entry contains the metric’s criteria, an explanation of the metric score, and metadata. The keys of each entry are: `criteria`: The criteria used by an LLM judge to evaluate response correctness. `explanation`: An explanation of why the score was assigned. `full_metadata`: A VARIANT value that contains metadata and information about this metric’s processing by the LLM judge. The keys of this map include: `completion_tokens`: The number of output tokens generated by the LLM for this metric evaluation call. `guard_tokens`: The number of tokens consumed by Cortex Guard for this metric evaluation call. `normalized_score`: The original evaluation score normalized to the range [0.0, 1.0], rounded to two decimal places. `original_score`: The original score assigned by this metric evaluation for the record. `prompt_tokens`: The number of tokens taken up by the prompt provided to the LLM judge. `total_tokens`: The total number of tokens used by the LLM judge for this computation.
TOTAL_INPUT_TOKENS	INT	The total number of tokens used to process the input query.
TOTAL_OUTPUT_TOKENS	INT	The total number of output tokens produced by the Cortex Agent.
LLM_CALL_COUNT	INT	Counts the number of times any LLM was called, either by the agent or an evaluation judge.

Access control requirements¶

A role used to execute this operation must have the following privileges at a minimum:


Privilege	Object	Notes
CORTEX_USER	Database role
USAGE	Cortex Agent
MONITOR	Cortex Agent

Operating on an object in a schema requires at least one privilege on the parent database and at least one privilege on the parent schema.

For instructions on creating a custom role with a specified set of privileges, see Creating custom roles.

For general information about roles and privilege grants for performing SQL actions on securable objects, see Overview of Access Control.

For the full access control permissions required by Cortex Agent evaluations, see Cortex Agent evaluations – Access control requirements.

Examples¶

The following example displays the trace for the record 9346efc3-5dd6-4038-9b1a-72ca3d3b768c, where the agent is named evaluated_agent stored on the schema eval_db.eval_schema:

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