카테고리:: :doc:`/sql-reference/functions-table`(Cortex Agents)

GET_AI_RECORD_TRACE (SNOWFLAKE.LOCAL)¶

Retrieve a single trace record from an evaluation run for a Cortex Agent or for an External Agent application that stores traces in AI_OBSERVABILITY_EVENTS (see External Agent commands).

Call this function when you want to inspect a single record from a complete evaluation. For more information, see Cortex Agent 평가 and Observability 데이터.

참고 항목:: EXECUTE_AI_EVALUATION , GET_AI_EVALUATION_DATA (SNOWFLAKE.LOCAL) , GET_AI_OBSERVABILITY_LOGS (SNOWFLAKE.LOCAL) , GET_AI_OBSERVABILITY_EVENTS (SNOWFLAKE.LOCAL)

구문¶

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

인자¶

database: 에이전트가 포함된 데이터베이스의 이름입니다.
schema: 에이전트가 포함된 스키마의 이름입니다.
agent_name: 레코드를 검색할 에이전트의 이름입니다.
agent_type: The agent type string. Use CORTEX AGENT for a Cortex Agent or EXTERNAL AGENT for an External Agent object. This value is case-insensitive.
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	The ground truth information used to evaluate this record’s Cortex Agent output. This column holds the JSON from your dataset’s ground truth column, serialized as a string. For how `{{ground_truth}}` in custom metrics relates to this value, see the notes under 평가 결과 테이블 형식.
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에 의해 생성된 출력 토큰의 수입니다. `normalized_score`: 원래 평가 점수는 [0.0, 1.0] 범위로 정규화되었으며, 소수점 이하 두 자리까지 반올림됩니다. `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 or External Agent	Required on the object identified by `agent_name`. For `EXTERNAL AGENT`, USAGE on the External Agent is sufficient to call this function (MONITOR does not apply).
MONITOR	Cortex Agent	Required on the Cortex Agent identified by `agent_name` when `agent_type` is `CORTEX AGENT`. Does not apply when `agent_type` is `EXTERNAL AGENT`.

스키마의 오브젝트에 대한 작업을 수행하려면 상위 데이터베이스에 대한 하나 이상의 권한과 상위 스키마에 대한 하나 이상의 권한이 필요합니다.

지정된 권한 세트로 사용자 지정 역할을 만드는 방법에 대한 지침은 사용자 지정 역할 만들기 섹션을 참조하십시오.

보안 오브젝트 에 대해 SQL 작업을 수행하기 위한 역할과 권한 부여에 대한 일반적인 정보는 액세스 제어의 개요 섹션을 참조하십시오.

When agent_type is EXTERNAL AGENT, only USAGE on that object is required to call this function. OWNERSHIP on the External Agent is required to modify or remove the object with ALTER EXTERNAL AGENT or DROP EXTERNAL AGENT.

For the full access control permissions required by Cortex Agent evaluations, see Cortex Agent evaluations – Access control requirements. For External Agent objects, see Observability 데이터.

예¶

다음 예제에서는 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'
));