CREATE EXTERNAL AGENT

CREATE EXTERNAL AGENT

현재 또는 지정한 스키마에 새 외부 에이전트(external agent) 객체를 만드는 명령이에요. 외부 에이전트는 AI Observability에 사용하기 위해 Snowflake 안의 생성형 AI 애플리케이션을 나타내며, 애플리케이션·평가 메타데이터를 저장하고 트레이스와 평가 결과에 대한 접근을 관리해요.

출처: 문서

본문

현재 또는 지정한 스키마에 새 외부 에이전트 객체를 만들어요. 외부 에이전트는 AI Observability에 사용하기 위해 Snowflake 안의 생성형 AI 애플리케이션을 나타내요. 외부 에이전트 객체는 애플리케이션과 평가 메타데이터(예: 애플리케이션 이름, 버전 이름, 실행 이름)를 저장하고 트레이스(trace)와 평가 결과에 대한 접근을 관리해요.

참고: 외부 에이전트 객체는 일반적으로 애플리케이션을 등록하거나 평가를 실행할 때 TruLens SDK가 자동으로 만들어요. SQL로 수동으로 만들 필요는 대개 없어요. 자세한 내용은 Snowflake Cortex용 AI Observability를 참고해요.

함께 보기: 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 외부 에이전트의 식별자(즉 이름)를 지정하는 문자열로, 외부 에이전트가 만들어지는 스키마 안에서 고유해야 해요.

또한 식별자는 반드시 알파벳 문자로 시작해야 하며, 전체 식별자 문자열이 큰따옴표로 묶이지 않는 한 공백이나 특수 문자를 포함할 수 없어요 (예: "My object"). 큰따옴표로 묶인 식별자는 대소문자를 구분해요.

자세한 내용은 식별자 요구 사항(Identifier requirements)을 참고해요.

선택 매개변수 (Optional parameters)

WITH VERSION version_name 외부 에이전트에 만들 초기 버전의 이름을 지정해요. 버전은 애플리케이션의 서로 다른 구현(예: 서로 다른 리트리버(retriever), 프롬프트, LLM, 추론 구성)을 나타내요.

COMMENT = comment 외부 에이전트에 대한 설명을 지정하는 문자열이에요.

접근 제어 요구 사항 (Access control requirements)

이 작업을 실행하는 데 사용하는 역할(role)은 최소한 다음 권한을 가져야 해요.

권한 (Privilege) 객체 (Object) 비고
CREATE EXTERNAL AGENT Schema 스키마에 외부 에이전트를 만드는 데 필요해요.

스키마 안의 객체를 작업하려면 상위 데이터베이스에 대한 권한이 최소 하나, 상위 스키마에 대한 권한이 최소 하나 필요해요.

지정된 권한 집합으로 사용자 지정 역할을 만드는 방법은 사용자 지정 역할 만들기(Creating custom roles)를 참고해요. 보호 가능한 객체에 대해 SQL 작업을 수행하기 위한 역할과 권한 부여의 일반적인 내용은 접근 제어 개요(Overview of Access Control)를 참고해요.

사용 메모 (Usage notes)

OR REPLACE와 IF NOT EXISTS 절은 서로 배타적이에요. 같은 문에서 둘 다 사용할 수 없어요.

CREATE OR REPLACE <object> 문은 원자적(atomic)으로 동작해요. 즉, 객체를 교체할 때 기존 객체는 삭제되고 새 객체는 단일 트랜잭션 안에서 생성돼요.

외부 에이전트 객체는 모델 객체와 네임스페이스를 공유해요. 같은 스키마에서 기존 모델과 같은 이름으로 외부 에이전트를 만들 수 없고, 그 반대도 마찬가지예요. 이름 충돌이 발생하면 충돌하는 객체를 이름을 바꾸거나 삭제해야 해요.

TruLens SDK는 AI Observability용 애플리케이션을 등록하기 위해 TruApp()(또는 프레임워크 특정 래퍼 TruChain, TruGraph, TruLlama)을 호출할 때 외부 에이전트 객체를 자동으로 만들어요. 평가를 실행하는 것도 지정된 애플리케이션 이름에 대한 외부 에이전트가 아직 없으면 만들 수 있어요.

메타데이터에 관해서는 다음 사항에 주의해요.

⚠️ 주의: 고객은 Snowflake 서비스를 사용할 때 (User 객체를 제외하고) 개인 데이터·민감 데이터·수출 통제 데이터·기타 규제 데이터를 메타데이터로 입력하지 않도록 해야 해요. 자세한 내용은 Snowflake의 메타데이터 필드를 참고해요.

예시 (Examples)

외부 에이전트를 만들어요.

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";

더 알아보기 (Learn more)