Monitor Cortex Agent requests¶

Use this topic for Cortex Agents deployed through Snowflake Intelligence or the Agent API. Monitoring shows live conversation history and execution traces: planning, tool calls, responses, and user feedback.

For batch test runs and GPA-style metrics, see Cortex Agent evaluations. For custom AI applications (agents, RAG pipelines, AI workflows on Snowflake compute or other hosts) observed with TruLens, see Trace and monitor applications with TruLens.

Monitoring vs evaluations (Cortex Agents)¶

The following table compares live monitoring with batch evaluations for Cortex Agents:

	Monitoring (this topic)	Evaluations
Purpose	Debug and audit production conversations and threads	Score the agent on a dataset before or after deployment
Snowsight	Agent → Monitoring tab	Agent → Evaluations tab
Typical use	Trace planning, tools, latency, feedback on real queries	Answer correctness, logical consistency, custom LLM judges
Documentation	This topic	Cortex Agent evaluations

Terminology¶

Cortex Agent monitoring uses OpenTelemetry-style event data in AI_OBSERVABILITY_EVENTS. The following terms describe how conversations are grouped:

Term	Meaning
Thread	A persisted conversation identified by `thread_id`. The Monitoring pane lists one row per thread. Thread length is the number of turns in that conversation. See Use threads with the Cortex Agent REST API.
Turn	One user message and the agent’s full response for that message (one `agent:run` request). Each turn is a single exchange in a thread.
Trace	The OpenTelemetry trace for one turn. All telemetry for that turn shares the same `trace_id` in the `TRACE` column of `AI_OBSERVABILITY_EVENTS`. One turn = one trace.
Span	One step inside a trace: LLM planning, a tool call, SQL execution, chart generation, response generation, and so on. Many spans make up one trace.
Snowflake session	The platform SQL session context (user, role, warehouse, and related attributes in `RESOURCE_ATTRIBUTES`). A Snowflake session is separate from a conversation thread. One session can include many threads and turns.

Snowflake session
  └── Thread (thread_id)
        └── Turn 1 = Trace 1 (one trace_id)
              └── Spans: planning, tools, response, …
        └── Turn 2 = Trace 2
              └── Spans: …

When you query the event table, filter on TRACE:trace_id to scope results to a single turn. Filter on thread-related attributes or use Snowsight to work at thread level across multiple turns.

Information collected in Cortex Agent logs¶

Cortex Agent logs include the following information:

Conversation history associated with a thread
For each turn, one trace made up of spans, including:
- LLM planning
- Tool execution (Cortex Search, Cortex Analyst, web search, code execution, MCP connector calls, custom tools, and other configured tools)
- LLM response generation
- SQL execution
- Chart generation
Inputs and outputs associated with each span
User feedback for each agent response (one turn)

View Cortex Agent logs in Snowsight¶

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 pane lists each conversation thread with its first input, user feedback, thread length, the user who ran it, and when it was last updated. The Version column shows the agent configuration version that handled each thread, so you can tell which version of the agent produced a given conversation.

Note

By default, the Monitoring pane loads data as your current role and uses your default warehouse. Use the Role and Warehouse selectors to override these defaults and query the monitoring data with a specific role and warehouse.

Query Cortex Agent logs with SQL¶

The same thread, trace, and span data shown in the Monitoring tab is stored in SNOWFLAKE.LOCAL.AI_OBSERVABILITY_EVENTS. Use the SNOWFLAKE.LOCAL observability table functions (UDTFs) below to read rows scoped to a specific agent. Grant MONITOR on the agent to the querying role. Entries in the event table can’t be modified.

For the recommended access model, required object privileges, and when to use AI_OBSERVABILITY_READER for direct table access, see AI_OBSERVABILITY_EVENTS table.

Note

Unredacted fields in monitoring and UDTF results

An account-level privilege, READ UNREDACTED AI OBSERVABILITY EVENTS TABLE, controls whether roles can see unredacted content from AI_OBSERVABILITY_EVENTS (full tool inputs and outputs, full conversation text, and user feedback text) when you use Cortex Agent monitoring in Snowsight and when you call the SNOWFLAKE.LOCAL observability user-defined table functions (UDTFs) that read that event table. Without the grant, roles can still read metadata in those paths (tool names, token usage, latency, evaluation trace summaries, model name, and error severity). This does not change Cortex Agent evaluation job execution, scoring, or the Evaluations experience. An account admin must grant the privilege to see unredacted content; for details, see Account Privilege READ UNREDACTED AI OBSERVABILITY EVENTS TABLE.

Observability table functions¶

Use the following UDTFs to read monitoring and evaluation data. GET_AI_OBSERVABILITY_EVENTS also accepts CORTEX SEARCH SERVICE as agent_type for Cortex Search request logs; see Monitor Cortex Search requests. The other three functions apply to Cortex Agent and External Agent evaluations only.

All four functions take the object database, schema, name, and agent_type (CORTEX AGENT, EXTERNAL AGENT, or CORTEX SEARCH SERVICE for GET_AI_OBSERVABILITY_EVENTS only).

Function	Use when you want to…
GET_AI_OBSERVABILITY_EVENTS	Read production monitoring events: threads, spans, traces, and user feedback
GET_AI_OBSERVABILITY_LOGS	Read structured log lines and warnings from evaluation runs
GET_AI_EVALUATION_DATA	Retrieve evaluation trace data for a named run
GET_AI_RECORD_TRACE	Retrieve one trace record from an evaluation run

For evaluation workflows and examples of the last three functions, see Cortex Agent evaluations (SQL section under evaluation results).

Query monitoring events¶

Monitoring data for an agent is stored in SNOWFLAKE.LOCAL.AI_OBSERVABILITY_EVENTS. To read those rows programmatically, use GET_AI_OBSERVABILITY_EVENTS. Pass the database name, schema name, object name, and agent_type CORTEX AGENT for a Cortex Agent, EXTERNAL AGENT for an External Agent used with AI Observability (see External Agent commands), or CORTEX SEARCH SERVICE for a Cortex Search service (see Monitor Cortex Search requests). 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. When agent_type is CORTEX SEARCH SERVICE, MONITOR (or OWNERSHIP) on the Cortex Search service is required and REQUEST_LOGGING must be enabled. 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 TruLens applications and External Agent examples, see Trace and monitor applications with TruLens and AI_OBSERVABILITY_EVENTS table.

Generate monitoring reports with CoCo CLI¶

Use the agent-observability-report sub-skill of the CoCo cortex-agent skill in the CoCo CLI to generate a report on agent monitoring metrics pulled from SNOWFLAKE.LOCAL.AI_OBSERVABILITY_EVENTS, including usage and adoption, latency percentiles, token economics, tool execution stats, conversation depth and completion, and a breakdown of user feedback. For more information about CoCo skills, see CoCo CLI - Skills.

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¶

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>;