Monitor Cortex Agent requests¶

Cortex Agents log detailed traces of all conversations for auditing and debugging purposes. With monitoring, you can access the conversation history of an Agent deployed via Snowflake Intelligence or Agent API. In addition to conversation history, you can review detailed tracing of the agent’s planning process, tool selection, execution results, and final response generation.

Information collected in Cortex Agent logs¶

Cortex Agent logs include the following information:

Conversation history associated with a thread
Agent’s execution trace with spans including:
- LLM planning
- Tool execution (Cortex Search, Cortex Analyst, web search)
- LLM response generation
- SQL execution
- Chart generation
Inputs and outputs associated with each span
User feedback for each Agent response

Access Cortex Agent logs¶

To view Cortex Agent conversation logs in Snowsight, do the following:

Sign in to Snowsight.
In the navigation menu, select AI & ML » Agents.
Select the Agent whose logs you wish to view.
Navigate to the Monitoring pane of the Agent view.

The monitoring logs associated with the Agent are stored in the event table SNOWFLAKE.LOCAL.AI_OBSERVABILITY_EVENTS. Entries in this table can’t be modified.

The SNOWFLAKE.AI_OBSERVABILITY_READER application role grants read-only access to query that table. It does not allow deleting rows. Administrators with the SNOWFLAKE.AI_OBSERVABILITY_ADMIN application role can delete entries in SNOWFLAKE.LOCAL.AI_OBSERVABILITY_EVENTS. For more detail, see Observability data.

Query AI Observability events with SQL¶

Monitoring data for an agent is stored in SNOWFLAKE.LOCAL.AI_OBSERVABILITY_EVENTS. To read those rows programmatically, use the GET_AI_OBSERVABILITY_EVENTS table function. Pass the database name, schema name, object name, and the agent type CORTEX AGENT for a Cortex Agent or EXTERNAL AGENT for an External Agent used with AI Observability (see External Agent commands). The result has the same event table columns as the underlying table (for example RECORD, RECORD_ATTRIBUTES, VALUE, TRACE, and timestamps). You can filter with WHERE to focus on specific event kinds, time ranges, or attributes.

When agent_type is EXTERNAL AGENT, USAGE on that External Agent is sufficient to call the function; MONITOR does not apply. OWNERSHIP on the External Agent is required to modify or drop the object with SQL.

The following example returns all observability events for an agent:

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

For evaluation runs, warnings, and structured log lines, you can also use GET_AI_OBSERVABILITY_LOGS and the evaluation-specific functions described in Cortex Agent evaluations. For how AI Observability uses the event table across products, see Observability data.

View feedback provided by users¶

End-user feedback is stored as observability events. To return only feedback events, filter on the record name 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';

The resulting rows include information about the agent, the user who provided feedback, the feedback text, and whether the feedback was positive or negative. For full argument and access details, see GET_AI_OBSERVABILITY_EVENTS (SNOWFLAKE.LOCAL).

Access control and permissions¶

Tip

A user with the ACCOUNTADMIN role can add the SNOWFLAKE.AI_OBSERVABILITY_READER application role to any role so that users can run read-only queries on SNOWFLAKE.LOCAL.AI_OBSERVABILITY_EVENTS for Cortex Agent monitoring.

To view Cortex Agent logs, users must have the following privileges:

OWNERSHIP or MONITOR privileges on the AGENT object
The CORTEX_USER database role

The following example uses the ACCOUNTADMIN role to create a new role agent_monitoring_user_role with the required permissions to view Cortex Agent logs. This new role is then assigned to 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;

Grant monitoring access to future agents¶

To grant a role monitoring access on future agents created in a schema, use the following SQL command:

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