Categories:: Table functions (Cortex Agents)

GET_AI_OBSERVABILITY_EVENTS (SNOWFLAKE.LOCAL)¶

Return AI Observability events from the AI_OBSERVABILITY_EVENTS table in the LOCAL schema. Pass CORTEX AGENT as agent_type for a Cortex Agent, or EXTERNAL AGENT for an External Agent object used with AI Observability (see External Agent commands). Each row uses the event table column layout (including RECORD, RECORD_ATTRIBUTES, VALUE, and trace fields). Events can represent conversation activity, spans (planning, tools, response generation), logs, user feedback, and other telemetry written for the agent or application.

For Snowsight workflows and examples of filtering events (including feedback), see Monitor Cortex Agent requests. For how AI Observability stores data in the event table, see Observability data.

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

Syntax¶

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

Arguments¶

database: Name of the database containing the agent.
schema: Name of the schema containing the agent.
agent_name: Name of the agent whose observability events you want to retrieve.
agent_type: The agent type string. Use CORTEX AGENT for a Cortex Agent (see Monitor Cortex Agent requests) or EXTERNAL AGENT for an External Agent object (see External Agent commands). This value is case-insensitive.

Returns¶

A table of observability events. Column definitions follow the event table schema. Filter and project with standard SQL (for example on RECORD:name, RECORD_ATTRIBUTES, or severity fields inside RECORD) to narrow to specific event kinds.

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 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`.

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.

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 typical Cortex Agent monitoring setup (including grants for future agents), see Monitor Cortex Agent requests. For External Agent access to observability data, see Observability data.

Examples¶

Return observability events for an agent:

SELECT *
  FROM TABLE(SNOWFLAKE.LOCAL.GET_AI_OBSERVABILITY_EVENTS(
    'my_database',
    'my_schema',
    'my_agent',
    'CORTEX AGENT'
  ));

To list only user feedback events, filter on the event name (see View feedback provided by users):

SELECT *
  FROM TABLE(SNOWFLAKE.LOCAL.GET_AI_OBSERVABILITY_EVENTS(
    'my_database',
    'my_schema',
    'my_agent',
    'CORTEX AGENT'
  ))
  WHERE RECORD:name = 'CORTEX_AGENT_FEEDBACK';

The same function works for an externally instrumented application by passing EXTERNAL AGENT as agent_type and the External Agent object name in agent_name (see Observability data).