代理的用户访问和设置¶

本主题提供有关用户与 Snowflake Intelligence 中代理交互所需权限的信息，以及 Snowflake Intelligence 界面和高级访问控制功能的可用设置。

如果您还没有可用于 Snowflake Intelligence 的代理，请使用构建代理指南创建一个。

自定义 Snowflake Intelligence 界面¶

要自定义用户通过 Cortex Agent 交互的 Snowflake Intelligence 界面，请执行以下步骤：

登录 Snowsight。
在导航菜单中，选择 AI & ML » Agents。
选择 Open settings。
在 Snowflake Intelligence 下，修改以下设置：
- Display name：选择使用时默认使用的角色和仓库。向用户显示的 Snowflake Intelligence 界面的名称。
- Welcome message：选择使用时默认使用的角色和仓库。用户首次打开 Snowflake Intelligence 界面时显示的消息。
- Color theme：选择使用时默认使用的角色和仓库。Snowflake Intelligence 界面的颜色主题。
  您可以提供十六进制格式的自定义原色。
- Full-length logo 和 Compact logo：分别在导航窗格展开或折叠时显示的徽标。
- Compact logo：选择使用时默认使用的角色和仓库。浏览器选项卡中显示的图标。
选择 Save。

用户权限和访问控制¶

用户必须具有以下权限才能在 Snowflake Intelligence 中查看代理：

权限	对象	备注
USAGE	数据库、架构	查看代理所必需。
USAGE	代理	查询 Cortex Agent 以生成响应所必需。

要访问附加到代理的工具，用户必须具有以下权限：

权限	对象	备注
USAGE	数据库、架构	访问与要附加到代理的任何工具相关联的对象所必需。
USAGE	Cortex Search Service	需要在 Cortex Agents 请求中运行 Cortex Search Service。
SELECT	表	访问代理的语义视图/模型中引用的对象时需要。
USAGE	工具	访问代理可用来生成响应的所有自定义工具所必需。例如，如果自定义工具是存储过程，则用户必须对该过程具有 USAGE 权限。
USAGE	语义视图/模型	访问代理引用的语义视图/模型所必需。

限制特定角色的访问权限

CORTEX_USER 角色允许用户访问所有 Cortex 功能，包括代理。默认情况下，此角色被授予 PUBLIC 角色，该角色会自动授予所有用户和角色。如果您不希望所有用户都拥有此权限，则可从 PUBLIC 角色中撤销该权限，然后仅将访问权限授予特定角色。有关更多信息，请参阅 Cortex LLM privileges。

在从 PUBLIC 角色撤销 CORTEX_USER 角色后，您可以授予 CORTEX_AGENT_USER 角色。此角色仅允许用户访问 Cortex Agent API，他们可以使用 Snowflake Intelligence，但无法使用其他 Cortex 功能。

要提供对 Cortex Agent 的选择性访问权限，以便只有一部分用户可以访问该功能，请先撤销对 PUBLIC 角色的访问权限，然后将 CORTEX_AGENT_USER 角色授予特定用户：
```
GRANT DATABASE ROLE SNOWFLAKE.CORTEX_AGENT_USER TO ROLE <role_name>;
```
Copy

有关更多信息，请参阅访问控制要求。

使用专用连接配置 Snowflake Intelligence¶

Snowflake Intelligence 支持与 AWS Privatelink 和 Azure 专用链接集成，以在您的虚拟私有云 (VPC) 或虚拟网络 (VNet) 与 Snowflake Intelligence 之间建立专用连接。配置专用连接需设置正确的 DNS 解析，以通过此专用连接将流量定向至 Snowflake Intelligence 服务。

请注意，AWS PrivateLink 和 Azure 专用链接不是 Snowflake 提供的服务。它们分别是 AWS 服务和 Microsoft 服务，Snowflake 支持与您的 Snowflake 账户一起使用。

先决条件¶

在使用专用连接连接 Snowflake Intelligence 前，请完成以下先决条件。

执行下列操作之一：
- 要设置 AWS PrivateLink，请按照 AWS PrivateLink 和 Snowflake 中的说明进行操作。
- 要设置 Azure 专用链接，请按照 Azure 专用链接和 Snowflake 中的说明进行操作。
要确保 regionless-snowsight-privatelink-url 可用，请使用 ACCOUNTADMIN 系统角色调用 SYSTEM$GET_PRIVATELINK_CONFIG 函数。

重要

Snowflake Intelligence 仅支持使用无区域 URL 格式访问专用连接。与 Snowflake 使用的其他专用连接 URLs 不同，主机名中不应包含区域标识符（如 us-west-2,）。任何尝试使用区域特定 URL 进行连接的行为都将失败。

设置 Snowflake Intelligence¶

通过配置 Snowflake Intelligence 的 DNS 以使用子域名连接 Snowflake Intelligence。

在您的私有 DNS 区域 privatelink.snowflakecomputing.cn 中创建一个 CNAME 记录，将以下 URL 映射到 VPC 或 VNET 端点的 DNS 名称。
```
si-<org-acct>.privatelink.snowflakecomputing.cn
```
Copy

完成配置后，您网络内的用户可以通过访问以下 URL 来使用 Snowflake Intelligence：

https://si-<org-acct>.privatelink.snowflakecomputing.cn

Copy

该连接将通过专用连接进行安全路由。

使用专用连接进行用户身份验证¶

通过专用连接访问 Snowflake Intelligence 的用户使用标准 Snowflake 身份验证流程，需在登录页面提供其账户标识符、用户名和密码。

将用户重定向到您的身份提供商¶

账户管理员可以配置所有用户 URLs，以便在未通过身份验证的用户访问 Snowflake Intelligence 时重定向到您的身份提供商 (IdP)。此过程减少了用户登录流程中的一个步骤。

要将未验证用户从 URLs 重定向到您的 IdP，请执行以下 SQL 命令，并将 your_security_integration 替换为您的 IdP 配置的安全集成名称：
```
ALTER ACCOUNT SET LOGIN_IDP_REDIRECT = (SNOWFLAKE_INTELLIGENCE = <your_security_integration>);
```
Copy

备注

要在通过专用连接访问 Snowflake Intelligence 时使用 IdP 重定向，必须配置 DNS 以使用以下 URL 格式将流量定向到 Snowflake Intelligence 服务：
```
https://si-<org-acct>.privatelink.snowflakecomputing.cn
```
Copy

有关更多信息，请参阅使用专用连接配置 Snowflake Intelligence。

有关配置 Snowflake 账户以使用 IdP 的更多信息，请参阅以下主题：

将用户的访问权限限制为仅访问 Snowflake Intelligence¶

要限制用户只能访问 Snowflake Intelligence 并阻止其访问 Snowflake 的其他部分，可以使用 ALTER USER SQL 命令或 allowedInterfaces SCIM 属性。如果使用任一方法指定了除 ALL 以外的值，则用户只能访问指定的界面，且无法与指定界面之外的任何 Snowflake 数据进行交互。

要限制用户只能访问 Snowflake Intelligence，请使用 ALTER USER SQL 命令：
ALTER USER <user_name> SET ALLOWED_INTERFACES = (SNOWFLAKE_INTELLIGENCE);
Copy
如果您正在使用 SCIM APIs 配置用户，要设置相同的限制，请使用自定义属性 allowedInterfaces。

有关 SCIM 自定义属性的更多信息，请参阅自定义属性。

限制¶

Snowflake Intelligence 目前仅对 Snowflake Intelligence 用户有以下限制：

自定义品牌徽标和图标对仅 Snowflake Intelligence 用户无效，将默认显示 Snowflake 徽标和图标。
仅限使用 Snowflake Intelligence 的用户无法上传文件。

Snowflake Intelligence 对象¶

Snowflake Intelligence 对象是一个账户级对象，用于管理 Snowflake Intelligence 中的所有代理及其在您账户中的设置。Snowflake Intelligence 对象具有以下优势：

灵活性： 在账户中的任何位置创建和管理代理，无需将它们集中在单个架构中。
代理可见性管理： 使用单个对象控制向所有用户显示哪些代理。
改进的权限管理： 将创建代理的能力与控制哪些代理显示在 Snowflake Intelligence 中的能力分开。

备注

使用 Snowflake Intelligence 对象是高级配置选项，在 Snowflake Intelligence 中管理代理并非必须使用。如果账户有 Snowflake Intelligence 对象，则必须将代理添加到该对象中才能可见。如果未添加，则只能使用直接链接或 Snowsight UI 进行访问。

设置 Snowflake Intelligence 对象¶

备注

角色必须拥有 CREATE SNOWFLAKE INTELLIGENCE ON ACCOUNT 权限才能创建 Snowflake Intelligence 对象。

要为用户设置 Snowflake Intelligence 对象，请遵循以下流程（详见后文）：

创建 Snowflake Intelligence 对象。Snowflake Intelligence 对象是用于管理账户中与 Snowflake Intelligence 一起使用的所有代理的单一对象。您的账户中只能拥有一个 Snowflake Intelligence 对象。
将代理添加到 Snowflake Intelligence 对象。
GRANT 对 Snowflake Intelligence 对象的 USAGE 权限。

创建 Snowflake Intelligence 对象¶

您可以使用 Snowsight 或 SQL 创建一个 Snowflake Intelligence 对象。

当您首次修改 Snowflake Intelligence 设置时，Snowflake 会自动创建 Snowflake Intelligence 对象。使用 UI 创建时，Snowflake Intelligence 对象的名称为 SNOWFLAKE_INTELLIGENCE_OBJECT_DEFAULT。您不能指定其他名称。

登录 Snowsight。

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

在 Snowflake Intelligence 选项卡上，选择 Open settings。如果 Snowflake Intelligence 对象尚不存在，系统会自动创建。然后，您可以向对象添加代理。
– 要创建 Snowflake Intelligence 对象，请使用以下命令：
CREATE SNOWFLAKE INTELLIGENCE SNOWFLAKE_INTELLIGENCE_OBJECT_DEFAULT;
Copy

添加代理¶

Snowflake Intelligence 对象是包含代理列表的账户级对象。您可以向此对象添加或从中移除代理，以便为用户创建精选代理列表。有关添加或移除代理的更多信息，请参阅在 Snowflake Intelligence 中配置代理的可见性。

授予 Snowflake Intelligence 权限¶

以下权限控制对 Snowflake Intelligence 对象的访问：

账户的 CREATE SNOWFLAKE INTELLIGENCE 权限： 允许创建 Snowflake Intelligence 对象的权限。默认向 ACCOUNTADMIN 授予此权限。

要将此权限授予其他角色，请运行以下命令：
```
GRANT CREATE SNOWFLAKE INTELLIGENCE ON ACCOUNT TO ROLE <role_name>;
```
Copy
USAGE Snowflake Intelligence 对象上的权限： 允许用户查看已添加到 Snowflake Intelligence 对象的代理列表并查看配置值的权限。

要授予此权限，请运行以下命令：
```
GRANT USAGE ON SNOWFLAKE INTELLIGENCE SNOWFLAKE_INTELLIGENCE_OBJECT_DEFAULT TO ROLE <role_name>;
```
Copy
Snowflake Intelligence 对象上的 MODIFY 权限： 允许用户从 Snowflake Intelligence 对象中添加或删除代理并更改配置值的权限。默认情况下，账户管理员具有此权限。

要授予此权限，请运行以下命令：
```
GRANT MODIFY ON SNOWFLAKE INTELLIGENCE SNOWFLAKE_INTELLIGENCE_OBJECT_DEFAULT TO ROLE <role_name>;
```
Copy
要使 Snowflake Intelligence 对象对所有用户可见，请将该对象的 USAGE 权限授予 PUBLIC 角色：
```
GRANT USAGE ON SNOWFLAKE INTELLIGENCE SNOWFLAKE_INTELLIGENCE_OBJECT_DEFAULT TO ROLE PUBLIC;
```
Copy

如果您正在使用 ACCOUNTADMIN 角色，您还拥有 Snowflake Intelligence 对象的 MODIFY 权限。这允许您在对象中添加或移除代理，以便为用户创建精选的代理列表。

要为用户设置 Snowflake Intelligence，必须配置代理权限。有关代理所需权限的信息，请参阅访问控制要求。

重要

默认情况下，Snowflake Intelligence 使用用户的默认角色和默认仓库。当您邀请其他人使用 Snowflake Intelligence 时，确保他们具有默认角色和仓库。

备注

来自 Snowflake Intelligence 的所有查询都使用用户的凭据。与用户关联的所有基于角色的访问控制和数据掩码策略都会自动应用于与代理的所有互动和对话。

在 Snowflake Intelligence 中配置代理的可见性¶

在某些情况下，您可能希望限制用户可以在 Snowflake Intelligence 中看到的代理：例如，您可能只想显示与特定用户或用户组相关的代理。

如果您还没有创建 Snowflake Intelligence 对象并向其添加代理，用户会自动看到他们在账户中有权访问的所有代理。

要控制哪些代理在 Snowflake Intelligence 界面中对所有用户显示，请通过将代理添加到 Snowflake Intelligence 对象来创建精选代理列表。

验证 Snowflake Intelligence 对象¶

要查看账户中是否已创建 Snowflake Intelligence 对象，请使用以下命令：
```
SHOW SNOWFLAKE INTELLIGENCES;
```
Copy

备注

只有一个 Snowflake Intelligence 对象可以存在于账户中。

通过 Snowflake Intelligence 对象管理代理¶

要将代理添加到 Snowflake Intelligence 对象，请使用以下命令：

ALTER SNOWFLAKE INTELLIGENCE SNOWFLAKE_INTELLIGENCE_OBJECT_DEFAULT ADD AGENT <db.schema.agent_name>;

Copy

要从 Snowflake Intelligence 对象中移除代理，请使用以下命令：

ALTER SNOWFLAKE INTELLIGENCE SNOWFLAKE_INTELLIGENCE_OBJECT_DEFAULT DROP AGENT <db.schema.agent_name>;

Copy

备注

任何具有正确数据库和架构权限的用户或管理员都可以创建代理。但是，代理不会自动添加到 Snowflake Intelligence 对象：要将代理添加到 Snowflake Intelligence 对象，用户必须具有 Snowflake Intelligence 对象的 ALTER 权限，以及对该代理的 USAGE 权限。

管理员必须拥有代理的 USAGE 权限，才能将其添加到 Snowflake Intelligence 对象。

将代理可见性管理从 SNOWFLAKE_INTELLIGENCE.AGENTS 架构迁移到 Snowflake Intelligence 对象¶

重要

不建议再将 SNOWFLAKE_INTELLIGENCE.AGENTS 架构作为管理代理可见性的机制。如果您当前正在使用此架构，建议您迁移到 Snowflake Intelligence 对象。

如果您使用的是 SNOWFLAKE_INTELLIGENCE.AGENTS 架构，您的代理将继续工作，详见在 Snowflake Intelligence 中配置代理的可见性。但是，迁移到 Snowflake Intelligence 对象提供以下优势：

灵活性： 在账户中的任何位置创建和管理代理，无需将它们集中在单个架构中。

改进的权限管理： 将创建代理的能力与使其在 Snowflake Intelligence 中可见的能力分开。

更少的命名冲突： 消除与 SNOWFLAKE_INTELLIGENCE.AGENTS 架构名称的潜在冲突。

更轻松的代理可见性管理： 使用单个对象来控制向所有用户显示哪些代理。

在迁移代理之前，您必须先创建一个 Snowflake Intelligence 对象。有关创建 Snowflake Intelligence 对象的信息，请参阅 Snowflake Intelligence 对象。

要将代理添加到 Snowflake Intelligence 对象，请使用以下代码：

ALTER SNOWFLAKE INTELLIGENCE SNOWFLAKE_INTELLIGENCE_OBJECT_DEFAULT ADD AGENT SNOWFLAKE_INTELLIGENCE.AGENTS.<agent_name>;

Copy

访问代理¶

创建代理后，您可以向其提问，以通过数据获得见解。代理可以回答以下问题：

上一季度的平均销售额是多少？
上个月哪种产品销量最高？
能告诉我去年的销售趋势吗？

它还可以提供以下可视化内容：

条形图
折线图
饼状图
散点图

要使用代理，请按照以下步骤操作：

要在没有专用连接的情况下访问 Snowflake Intelligence，请前往以下 URL：
https://ai.snowflake.com
Copy
要通过专用连接访问 Snowflake Intelligence，请前往以下 URL：
https://si-<org-acct>.snowflakecomputing.cn
Copy
要通过直接链接访问 Snowflake Intelligence，请执行以下步骤：

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

从代理列表中，选择您想要访问的代理。

选择 Preview in Snowflake Intelligence。

复制 URL。

备注

您可以在同一对话线程中的代理之间切换，以便在代理交互过程中保留上下文。

监控代理使用情况和反馈¶

您可以查看代理日志，了解用户与代理交互的详细情况。日志中包含的信息包括用户发送给代理的提示、代理的回复以及发生的任何错误。有关查看代理日志的更多信息，请参阅监控 Cortex Agent 请求。

当组织中的用户与代理交互时，他们可以提供关于代理所生成响应的反馈。这些反馈能提供关于用户满意度的概括性见解。要查看代理的用户反馈，请参阅监控 Cortex Agent 请求。