CREATE EXTERNAL AGENT

Crée un nouvel objet d’agent externe dans le schéma actuel ou spécifié. Les agents externes représentent les applications AI génératives dans Snowflake à utiliser avec l’observabilité AI. L’objet d’agent externe stocke les métadonnées d’application et d’évaluation (telles que le nom de l’application, le nom de la version ou le nom de l’exécution) et régit l’accès aux traces et aux résultats de l’évaluation.

Note

Les objets d’agent externes sont généralement créés automatiquement par le SDK TruLens lorsque vous enregistrez une application ou que vous exécutez une évaluation. Il n’est généralement pas nécessaire de les créer manuellement à l’aide de SQL. Pour plus d’informations, voir AI Observability dans Snowflake Cortex.

Voir aussi :

ALTER EXTERNAL AGENT, DROP EXTERNAL AGENT, SHOW EXTERNAL AGENTS, DESCRIBE EXTERNAL AGENT

Syntaxe

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

Paramètres requis

name

Chaîne qui indique l’identificateur (c’est-à-dire le nom) de l’agent externe ; doit être unique pour le schéma dans lequel l’agent externe est créé.

De plus, l’identificateur doit commencer par un caractère alphabétique et ne peut pas contenir d’espaces ou de caractères spéciaux à moins que toute la chaîne d’identificateur soit délimitée par des guillemets doubles (par exemple, "My object"). Les identificateurs entre guillemets doubles sont également sensibles à la casse.

Pour plus d’informations, voir Exigences relatives à l’identificateur.

Paramètres facultatifs

WITH VERSION version_name

Spécifie le nom de la version initiale à créer pour l’agent externe. Les versions représentent différentes implémentations de l’application, telles que différents récupérateurs, différentes invites,LLMs ou configurations d’inférence.

COMMENT = comment

Chaîne qui spécifie une description de l’agent externe.

Exigences en matière de contrôle d’accès

Un rôle utilisé pour exécuter cette opération doit au minimum disposer des privilèges suivants :

Privilège

Objet

Remarques

CREATE EXTERNAL AGENT

Schéma

Obligatoire pour créer l’agent externe dans un schéma.

Pour effectuer une opération sur un objet dans un schéma, il est nécessaire de disposer d’au moins un privilège sur la base de données parente et d’au moins un privilège sur le schéma parent.

Pour obtenir des instructions sur la création d’un rôle personnalisé avec un ensemble spécifique de privilèges, voir Création de rôles personnalisés.

Pour des informations générales sur les rôles et les privilèges accordés pour effectuer des actions SQL sur des objets sécurisables, voir Aperçu du contrôle d’accès.

Notes sur l’utilisation

  • Les clauses OR REPLACE et IF NOT EXISTS s’excluent mutuellement. Elles ne peuvent pas être utilisées dans la même instruction.

  • Les instructions CREATE OR REPLACE <objet> sont atomiques. En d’autres termes, lorsqu’un objet est remplacé, l’ancien objet est supprimé et le nouvel objet est créé dans une seule transaction.

  • Les objets d’agent externes partagent un espace de noms avec des objets modèle. Vous ne pouvez pas créer un agent externe portant le même nom qu’un modèle existant dans le même schéma, et vice versa. En cas de collision de noms, vous devez renommer ou détruire l’objet conflictuel.

  • Le SDK TruLens crée automatiquement des objets d’agent externes lorsque vous appelez TruApp() (ou les wrappers spécifiques au framework TruChain, TruGraph et TruLlama) pour enregistrer une application pour l’observabilité AI. L’exécution d’une évaluation peut également créer un agent externe s’il n’en existe pas déjà un pour le nom d’application spécifié.

  • Concernant les métadonnées :

    Attention

    Les clients doivent s’assurer qu’aucune donnée personnelle (autre que pour un objet utilisateur), donnée sensible, donnée à exportation contrôlée ou autre donnée réglementée n’est saisie comme métadonnée lors de l’utilisation du service Snowflake. Pour plus d’informations, voir Champs de métadonnées dans Snowflake.

Exemples

Créer un agent externe :

CREATE EXTERNAL AGENT my_rag_app;

Créer un agent externe avec une version initiale :

CREATE EXTERNAL AGENT my_rag_app WITH VERSION "v1";

Créer un agent externe uniquement s’il n’existe pas déjà :

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

Remplacez un agent externe existant :

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