CREATE EXTERNAL AGENT

在当前模式或指定模式中创建新的外部代理对象。在 Snowflake 中，外部代理代表生成式 AI 应用程序，用于 AI 可观察性。外部代理对象存储应用程序和评估元数据（例如应用程序名称、版本名称或运行名称），并管理对跟踪信息和评估结果的访问。

备注

当您注册应用程序或运行评估时，外部代理对象通常由 TruLens SDK 自动创建。您通常不需要使用 SQL 手动创建它们。有关更多信息，请参阅 Snowflake Cortex 中的 AI 可观察性。

另请参阅：

ALTER EXTERNAL AGENT、DROP EXTERNAL AGENT、SHOW EXTERNAL AGENTS、DESCRIBE EXTERNAL AGENT

语法

CREATE [ OR REPLACE ] EXTERNAL AGENT [ IF NOT EXISTS ] <name>
  [ WITH VERSION <version_name> ]
  [ COMMENT = '<comment>' ]

必填参数

name

指定外部代理标识符（即名称）的字符串；在创建外部代理的模式中必须唯一。

此外，标识符必须以字母字符开头，且不能包含空格或特殊字符，除非整个标识符字符串放在双引号内（例如，"My object"）。放在双引号内的标识符也区分大小写。

有关更多信息，请参阅 标识符要求。

可选参数

WITH VERSION version_name

指定为外部代理创建的初始版本的名称。版本表示应用程序的不同实现，例如不同的检索器、提示、LLMs 或推理配置。

COMMENT = comment

指定外部代理描述的字符串。

访问控制要求

用于执行此操作的 角色 必须至少具有以下 权限：

权限

对象

备注

CREATE EXTERNAL AGENT

架构

这是在模式中创建外部代理所必需的。

对架构中的对象进行操作至少需要父数据库的一项权限和父架构的一项权限。

有关创建具有指定权限集的自定义角色的说明，请参阅 创建自定义角色。

有关对 安全对象 执行 SQL 操作的相应角色和权限授予的一般信息，请参阅 访问控制概述。

使用说明

  • OR REPLACE 和 IF NOT EXISTS 子句互斥。它们不能同时用于同一条语句中。

  • CREATE OR REPLACE <object> 语句是原子的。也就是说，当对象被替换时，旧对象将被删除，新对象将在单个事务中创建。

  • 外部代理对象与 模型 对象共享命名空间。您无法创建与同一模式中现有模型同名的外部代理，反之亦然。如果发生名称冲突，您必须重命名或删除冲突的对象。

  • 当您调用 TruApp()``（或特定于框架的包装器 ``TruChain、TruGraph、TruLlama）为 AI 可观察性注册应用程序时，TruLens SDK 会自动创建外部代理对象。如果尚不存在指定应用程序名称的外部代理，运行评估也可以创建一个。

  • 关于元数据：

    注意

    客户应确保在使用 Snowflake 服务时，不会将个人数据（用户对象除外）、敏感数据、出口管制数据或其他受监管数据作为元数据输入。有关更多信息，请参阅 Snowflake 中的元数据字段。

示例

创建外部代理：

CREATE EXTERNAL AGENT my_rag_app;

创建带有初始版本的外部代理：

CREATE EXTERNAL AGENT my_rag_app WITH VERSION "v1";

仅在外部代理不存在时创建：

CREATE EXTERNAL AGENT IF NOT EXISTS my_rag_app WITH VERSION "v1";

替换现有的外部代理：

CREATE OR REPLACE EXTERNAL AGENT my_rag_app WITH VERSION "v2";