CREATE EXTERNAL AGENT¶

Creates a new external agent object in the current or specified schema. External agents represent generative AI applications in Snowflake for use with AI Observability. The external agent object stores application and evaluation metadata (such as the application name, version name, or run name) and governs access to traces and evaluation results.

Note

External agent objects are typically created automatically by the TruLens SDK when you register an application or run an evaluation. You generally do not need to create them manually using SQL. For more information, see AI Observability in Snowflake Cortex.

See also:: ALTER EXTERNAL AGENT, DROP EXTERNAL AGENT, SHOW EXTERNAL AGENTS, DESCRIBE EXTERNAL AGENT

Syntax¶

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

Required parameters¶

name

String that specifies the identifier (i.e. name) for the external agent; must be unique for the schema in which the external agent is created.

In addition, the identifier must start with an alphabetic character and cannot contain spaces or special characters unless the entire identifier string is enclosed in double quotes (for example, "My object"). Identifiers enclosed in double quotes are also case-sensitive.

For more information, see Identifier requirements.

Optional parameters¶

WITH VERSION version_name: Specifies the name of the initial version to create for the external agent. Versions represent different implementations of the application, such as different retrievers, prompts, LLMs, or inference configurations.
COMMENT = comment: String that specifies a description for the external agent.

Access control requirements¶

A role used to execute this operation must have the following privileges at a minimum:


Privilege	Object	Notes
CREATE EXTERNAL AGENT	Schema	Required to create the external agent in a schema.

Operating on an object in a schema requires at least one privilege on the parent database and at least one privilege on the parent schema.

For instructions on creating a custom role with a specified set of privileges, see Creating custom roles.

For general information about roles and privilege grants for performing SQL actions on securable objects, see Overview of Access Control.

Usage notes¶

The OR REPLACE and IF NOT EXISTS clauses are mutually exclusive. They can’t both be used in the same statement.
CREATE OR REPLACE <object> statements are atomic. That is, when an object is replaced, the old object is deleted and the new object is created in a single transaction.

External agent objects share a namespace with model objects. You cannot create an external agent with the same name as an existing model in the same schema, and vice versa. If a name collision occurs, you must rename or drop the conflicting object.
The TruLens SDK automatically creates external agent objects when you call TruApp() (or the framework-specific wrappers TruChain, TruGraph, TruLlama) to register an application for AI Observability. Running an evaluation can also create an external agent if one does not already exist for the specified application name.
Regarding metadata:

Attention

Customers should ensure that no personal data (other than for a User object), sensitive data, export-controlled data, or other regulated data is entered as metadata when using the Snowflake service. For more information, see Metadata fields in Snowflake.

Examples¶

Create an external agent:

CREATE EXTERNAL AGENT my_rag_app;

Create an external agent with an initial version:

CREATE EXTERNAL AGENT my_rag_app WITH VERSION "v1";

Create an external agent only if it does not already exist:

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

Replace an existing external agent:

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