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.

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

  1. 规划：应用程序通常需要在结构化与非结构化数据源之间切换处理。以设计用于回答用户查询的对话式应用程序为例。企业用户可能首先查询按收入排序的顶级分销商（结构化数据），随后转向询问合同细节（非结构化数据）。Cortex Agents 可以解析请求以编排计划并得出解决方案或响应。

    1. 探索选项：当用户提出模糊查询时（例如“请介绍 Acme Supplies”），代理程序会考量不同衍生维度（产品、地理位置或销售人员）以消除歧义并提升准确性。

    2. 拆分为子任务：Cortex代理程序可将任务或请求（例如“Acme Supplies 与 Acme Stationery 的合同条款有何差异？”）拆分为多个部分，以提供更精准的响应。

    3. 跨工具路由：代理会精准选择工具 Cortex Analyst 或 Cortex Search，以确保受控访问并符合企业策略。

  2. 工具使用：制定计划后，代理可以有效地检索数据。Cortex Search 从非结构化来源中提取见解，而 Cortex Analyst 生成 SQL 以处理结构化数据。全面的工具识别与工具执行支持，可实现基于企业数据的复杂应用程序交付。

  3. 反射：在每次工具调用后，代理会评估结果以确定后续步骤，包括请求澄清、迭代处理或生成最终响应。通过这种编排机制，代理可在 Snowflake 安全边界内处理复杂数据查询，同时确保准确性与合规性。

  4. 监控和迭代：部署后，客户可以跟踪指标、分析性能并优化行为以实现持续改进。客户端应用程序开发人员可使用 TruLens 监控代理的交互过程。通过持续监控和完善治理控制，企业可以自信地进行扩展 AI 代理，同时保持安全性和合规性。

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

备注

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

访问控制要求

要通过 agent:run API 向 Cortex Agent 发出请求，您可以使用被授予 SNOWFLAKE.CORTEX_USER 或 SNOWFLAKE.CORTEX_AGENT_USER 角色的角色。CORTEX_USER 提供对包括 Cortex Agents 在内的所有涵盖的 AI 功能的访问权限，而 CORTEX_AGENT_USER 提供对 Agents 功能的访问权限。

要将 Cortex Agents 和语义模型结合使用，您还需要以下权限：

权限

对象

USAGE

The Cortex Search services mentioned in the Cortex Agents request

USAGE

The database, schema, and tables referenced in the Cortex Agents semantic model

向 Cortex Agents API 发出的请求必须包含授权令牌。有关如何对 API 进行身份验证的详细信息，请参阅 使用 Snowflake 对 Snowflake REST APIs 进行身份验证。请注意，本主题中的示例使用会话令牌对 Snowflake 账户进行身份验证。

限制访问特定角色

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

要提供对 Cortex Agents 的选择性访问权限，以便只有一部分用户可以访问该功能，请使用 CORTEX_AGENTS_USER 角色。

使用 Cortex Agents 用户角色限制访问权限

要为特定用户提供对 Cortex Agents 的选择性访问权限，请使用 SNOWFLAKE.CORTEX_AGENT_USER 数据库角色。此角色包括调用 Cortex Agent API 所需的权限。

重要

如果您的用户角色拥有 CORTEX_USER 角色，则必须撤销对 CORTEX_USER 角色的访问权限。要从用户角色中撤销 CORTEX_USER 数据库角色，请使用 ACCOUNTADMIN 角色运行以下命令：

REVOKE DATABASE ROLE SNOWFLAKE.CORTEX_USER FROM ROLE agent;
Copy

要提供对 Cortex Agents 的访问权限，请使用 ACCOUNTADMIN 角色执行以下操作：

  1. 向自定义角色授予 SNOWFLAKE.CORTEX_AGENT_USER 数据库角色。

  2. 将此自定义角色分配给用户。

备注

您不能直接向用户授予数据库角色。有关更多信息，请参阅 GRANT DATABASE ROLE。

以下示例：

  1. 创建自定义角色，cortex_agent_user_role。

  2. 向它授予 CORTEX_AGENT_USER 数据库角色。

  3. 将此角色分配给 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

您还可以通过现有角色授予对 Cortex Agents 的访问权限。例如，如果您有 agent 角色由组织中的代理使用，则可以使用单个 GRANT 语句授予访问权限：

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.

Cortex Agent Concepts

Cortex Agents 使用 Cortex Analyst、Cortex Search 和自定义工具来计划任务和生成响应。您可以通过指令来影响编排。您还可以指定属性，根据业务逻辑动态选择工具。

在交互过程中，Agents 使用线程来维护上下文。线程可以轻松检索整个对话上下文，以用于应用程序逻辑。

在不断迭代和完善代理时，您可以收集最终用户的反馈。明确的反馈机制（正面/负面评级）加上主观反馈（文本）允许您在代理的整个生命周期中捕获用户的意见。

代理对象

代理配置包括存储在代理对象中的所有元数据、编排设置和工具详细信息。您可以使用代理对象与代理进行交互。

线程对象

线程会保留您与代理交互的上下文，因此您不必在客户端应用程序上维护上下文。要使用线程，您需要创建一个线程对象并在代理交互中引用线程 ID。

编排

Cortex Agents 使用基于 LLM 的编排来计划任务和生成响应。您可以使用以下设置来控制编排：

模型

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

  • llama3.1-70b

  • llama3.3-70b

  • mistral-large2

  • claude-3-5-sonnet

  • claude-3-7-sonnet

  • claude-4-0-sonnet

  • openai-gpt-5

说明

响应说明允许您根据自己的偏好设置品牌和语气来配置代理响应。

示例问题

您可以使用这些问题在客户端应用程序中开启对话。这些常见问题可以让用户开始互动。

工具

Cortex Agents 可以协调结构化和非结构化数据。此外，自定义工具允许代理与其他后端系统交互或实现自定义逻辑。

Cortex Analyst 语义视图

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

Cortex Search Service

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

备注

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

自定义工具

您可以使用存储过程和用户定义函数 (UDF) 将自定义业务逻辑作为工具来实现。有关更多信息，请参阅 和 用户定义的函数概述。

思考和反思

代理在整个交互过程中发出事件，提供对推理过程的见解。这些步骤包括任务的初始拆分、按子任务排序以及为子任务选择工具。此外，代理还展示了其对工具结果的反思，以及这些结果如何影响进一步的编排。

监控和迭代

您可以收集最终用户的反馈作为评级（正面/负面），也可以收集任何主观输入（文本）。它们可用于在整个生命周期中完善和改进代理。

与代理互动

Cortex Agents 支持两种不同的方法，通过 REST API 与代理进行交互：

  • 配置代理对象以与代理交互：使用此方法，您首先配置一个可在整个交互中重复使用的代理对象。配置代理对象可简化客户端代码，并为企业级应用程序启用 CI/CD。

  • 在没有代理对象的情况下进行交互：使用此方法，您必须将代理配置作为每个交互请求的一部分进行传递。没有代理对象的交互使您可以快速尝试用例并尝试不同的场景。

For information about these methods, see 配置并与 Agents 进行交互.

语言: 中文