Cortex Agents¶

概述¶

Cortex Agents orchestrate across both structured and unstructured data sources to deliver insights. They plan tasks, use tools to execute these tasks, and generate responses. Agents use Cortex Analyst (structured) and Cortex Search (unstructured) as tools, along with LLMs, to analyze data. Cortex Search extracts insights from unstructured sources, while Cortex Analyst generates SQL to process structured data. In addition, you can use stored procedures and user defined functions (UDFs) to implement custom tools. A comprehensive support for tool identification and tool execution enables delivery of sophisticated applications grounded in enterprise data.

该工作流涉及四个关键组件：

规划：应用程序通常需要在结构化与非结构化数据源之间切换处理。以设计用于回答用户查询的对话式应用程序为例。企业用户可能首先查询按收入排序的顶级分销商（结构化数据），随后转向询问合同细节（非结构化数据）。Cortex Agents 可以解析请求以编排计划并得出解决方案或响应。
1. 探索选项：当用户提出模糊查询时（例如“请介绍 Acme Supplies”），代理程序会考量不同衍生维度（产品、地理位置或销售人员）以消除歧义并提升准确性。
2. 拆分为子任务：Cortex代理程序可将任务或请求（例如“Acme Supplies 与 Acme Stationery 的合同条款有何差异？”）拆分为多个部分，以提供更精准的响应。
3. 跨工具路由：代理会精准选择工具 Cortex Analyst 或 Cortex Search，以确保受控访问并符合企业策略。
工具使用：制定计划后，代理可以有效地检索数据。Cortex Search 从非结构化来源中提取见解，而 Cortex Analyst 生成 SQL 以处理结构化数据。全面的工具识别与工具执行支持，可实现基于企业数据的复杂应用程序交付。
反射：在每次工具调用后，代理会评估结果以确定后续步骤，包括请求澄清、迭代处理或生成最终响应。通过这种编排机制，代理可在 Snowflake 安全边界内处理复杂数据查询，同时确保准确性与合规性。
监控和迭代：部署后，客户可以跟踪指标、分析性能并优化行为以实现持续改进。客户端应用程序开发人员可使用 TruLens 监控代理的交互过程。通过持续监控和完善治理控制，企业可以自信地进行扩展 AI 代理，同时保持安全性和合规性。

有关帮助您入门的教程，请参阅 Cortex Agents 教程。

备注

尽管 Snowflake 致力于提供高质量响应，但 LLM 生成的响应内容及其引用来源的准确性不作保证。在向用户提供代理 API 生成的答案前，您应当审核所有响应内容。

访问控制要求¶

To make a request to Cortex Agent via agent:run API, you can use a role that has the SNOWFLAKE.CORTEX_USER or SNOWFLAKE.CORTEX_AGENT_USER role granted. The CORTEX_USER provides access to all Covered AI features including Cortex Agents whereas CORTEX_AGENT_USER provides access to the Agents feature.

To use Cortex Agents with a semantic model, you also need the following privileges:

权限	对象	Notes
CREATE AGENT	Schema	Required to create the Cortex Agent.
USAGE	Cortex Search service	Required to run the Cortex Search services in the Cortex Agents request.
USAGE	Database, schema, table	Required for access the objects referenced in the Cortex Agents semantic model.
OWNERSHIP	Agent	OWNERSHIP is a special privilege on an object that is automatically granted to the role that created the object, but can also be transferred using the GRANT OWNERSHIP command to a different role by the owning role (or any role with the MANAGE GRANTS privilege). In a managed access schema, only the schema owner (for example. the role with the OWNERSHIP privilege on the schema) or a role with the MANAGE GRANTS privilege can grant or revoke privileges on objects in the schema, including future grants.
MODIFY	Agent	Required to update the Cortex Agent.
MONITOR	Agent	Required to view threads, logs, and traces of the Cortex Agent.
USAGE	Agent	Required to query the Cortex Agent to generate responses.

Requests to the Cortex Agents API must include an authorization token. For details on how to authenticate to the API, see 使用 Snowflake 对 Snowflake REST APIs 进行身份验证. Note that the example in this topic uses a session token to authenticate to a Snowflake account.

Limiting access to specific roles

默认情况下，CORTEX_USER 角色被授予给 PUBLIC 角色。PUBLIC 角色会自动授予所有用户和角色。如果您不希望所有用户都拥有此权限，则可以撤销对 PUBLIC 角色的访问权限，并授予对特定角色的访问权限。有关更多信息，请参阅所需权限。

To provide selective access to Cortex Agents so that only a subset of users have access to the feature, use the CORTEX_AGENTS_USER role.

Limiting access using the Cortex Agents user role

To provide selective access to Cortex Agents for specific users, use the SNOWFLAKE.CORTEX_AGENT_USER database role. This role includes the privileges needed to call the Cortex Agent API.

重要

If your user roles have the CORTEX_USER role, you must revoke access to the CORTEX_USER role. To revoke the CORTEX_USER database role from your user roles, run the following command using the ACCOUNTADMIN role:

REVOKE DATABASE ROLE SNOWFLAKE.CORTEX_USER FROM ROLE agent;

Copy

To provide access to Cortex Agents, use the ACCOUNTADMIN role to do the following:

Grant the SNOWFLAKE.CORTEX_AGENT_USER database role to a custom role.
Assign this custom role to users.

备注

You can't grant database roles directly to users. For more information, see GRANT DATABASE ROLE.

以下示例：

Creates the custom role, cortex_agent_user_role.
Grants it the CORTEX_AGENT_USER database role.
Assigns this role to example_user.

USE ROLE ACCOUNTADMIN;
CREATE ROLE cortex_agent_user_role;
GRANT DATABASE ROLE SNOWFLAKE.CORTEX_AGENT_USER TO ROLE cortex_agent_user_role;

GRANT ROLE cortex_agent_user_role TO USER example_user;

Copy

You can also grant access to Cortex Agents through existing roles. For example, if you have an agent role used by agents in your organization, you can grant access with a single GRANT statement:

GRANT DATABASE ROLE SNOWFLAKE.CORTEX_AGENT_USER TO ROLE agent;

Copy

身份验证¶

Snowflake REST APIs 支持通过编程访问令牌 (PATs) 进行身份验证、使用 JSON Web 令牌 (JWTs) 进行密钥对身份验证，以及 OAuth。有关详细信息，请参阅使用 Snowflake 对 Snowflake REST APIs 进行身份验证。

重要

Cortex Agents uses models that might not be available in all regions. To access these models, you will have to enable cross-region inference, if feasible. For more information, see Regional availability.

成本注意事项¶

In preview, Cortex Agents doesn't have any cost considerations besides those associated with the underlying Cortex Search and Cortex Analyst functionality. The Cortex Search and Cortex Analyst services incur costs per the details listed in the Snowflake Service Consumption Table. Also, use of custom tools may incur warehouse costs.

模型¶

You can use the following models with Cortex Agents. If the model is not available in the local region, you must use cross-region inference.

claude-4-sonnet
claude-3-7-sonnet
claude-3-5-sonnet
openai-gpt-5

Cortex Agent Concepts¶

Cortex Agents use Cortex Analyst, Cortex Search and custom tools to plan tasks and generate responses. You can influence the orchestration with instructions. You can also specify attributes to dynamically select a tool based on business logic.

During an interaction, Agents use a thread to maintain context. A thread provides an easy retrieval of the entire conversation context for use in application logic.

You can collect feedback from end-users as you continuously iterate and refine the Agent. An explicit feedback mechanism (positive/negative rating) coupled with subjective feedback (text) allows you to capture user inputs throughout the lifecycle of the Agent.

Agent object¶

The agent configuration includes all metadata, orchestration settings, and tool details that are stored in the agent object. You can use the agent object to interact with the agent.

Threads¶

Threads persist the context of your interactions with the agent, so you don't have to maintain context on the client application. To use threads, you create a thread object and reference the thread ID in the agent interactions.

编排¶

Cortex Agents use LLM-based orchestration to plan tasks and generate responses. You can control the orchestration with the following settings:

模型¶

For information about the models you can use with Cortex Agents for orchestration, see 模型.

说明¶

Response instructions allow you to configure the agent responses to a brand and tone of your preference.

Sample questions¶

You can use these questions to seed the conversation in your client application. These are common questions that can get users started with the interaction.

工具¶

Cortex Agents can orchestrate across both structured and unstructured data. Also, custom tools allow agents to interact with other backend systems or implement custom logic.

Cortex Analyst semantic view¶

您可以使用 Cortex Analyst 将自然语言转换为 SQL 查询。要使用 Cortex Analyst，您必须创建一个语义模型。有关更多信息，请参阅创建语义模型。

Cortex Search Service¶

使用 Cortex Search 搜索您的数据。有关更多信息，请参阅 CREATE CORTEX SEARCH SERVICE。

备注

查询用户的 DEFAULT_ROLE 必须对Cortex Search 服务及其所在的数据库和架构拥有 USAGE 权限。

Custom tools¶

You can use stored procedures and user defined functions (UDF) to implement custom business logic as a tool. For more information, see 存储过程概述 and 用户定义的函数概述.

Thinking and reflection¶

The Agent emits events throughout the interaction, providing insights into the reasoning process. These steps cover the initial splitting of tasks, sequencing into sub-tasks, and selection of tools for the sub-task. In addition, the agent also surfaces its reflections about tool results and how these influence further orchestration.

Monitor and iterate¶

You can collect feedback from the end user as a rating (positive/negative), along with any subjective inputs (as text). These can be used to refine and improve the Agent over the lifecycle.

Interact with agents¶

Cortex Agents support two distinct methods of interacting with agents through the REST API:

Configure an agent object to interact with the agent: With this method, you first configure an agent object that can be reused for the entire interaction. Configuring an agent object simplifies client code and enables CI/CD for enterprise-ready applications.
Interact without an agent object: With this method, you must pass the agent configuration as part of every interaction request. Interaction without an agent object allows you to quickly try out use cases and experiment with different scenarios.

For information about these methods, see Configure and interact with Agents.