监控 Cortex Agent 请求

Cortex Agent 会记录所有对话的详细跟踪信息，以便进行审计和调试。启用监控后，您可以访问通过 Snowflake Intelligence 或 Agent API 部署的代理的对话历史。除了对话历史外，您还可以查看代理的详细跟踪信息，包括其规划过程、工具选择、执行结果以及最终响应生成。

Cortex Agent 日志中收集的信息

Cortex Agent 日志包含以下信息：

  • 与线程关联的对话历史记录

  • 代理的执行跟踪，跨度包括：

    • LLM 规划

    • 工具执行（Cortex Search、Cortex Analyst、网页搜索）

    • LLM 响应生成

    • SQL 执行

    • 图表生成

  • 与每个跨度相关的输入与输出

  • 用户对每条代理响应的反馈

访问 Cortex Agent 日志

要在 Snowsight 中查看 Cortex Agent 对话日志，请执行以下步骤：

  1. 登录 Snowsight。

  2. 在导航菜单中，选择 AI & ML » Agents。

  3. 选择要查看其日志的代理。

  4. 进入代理视图中的 Monitoring 面板。

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 可观察性数据.

备注

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 账户权限 READ UNREDACTED AI OBSERVABILITY EVENTS TABLE.

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 外部代理命令). 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 评估. For how AI Observability uses the event table across products, see 可观察性数据.

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

访问控制与权限

小技巧

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.

要查看 Cortex Agent 日志，用户必须具备以下权限：

  • 对 AGENT 对象的 OWNERSHIP 或 MONITOR 权限

  • CORTEX_USER 数据库角色

以下示例展示了如何使用 ACCOUNTADMIN 角色创建一个新角色 agent_monitoring_user_role，并授予其查看 Cortex Agent 日志所需的权限。然后将这个新角色分配给 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>;