【Tips】Snowflake Intelligence에 Cortex Agent를 공개하는 절차와 권한 에러 해결 가이드

• Snowflake의 AI 서비스인 Cortex 시리즈를 이용하여 AI 서비스 개발을 실시하고 있습니다.
• 생성한 Agent를 Snowflake Intelligence(Agent 이용 창구와 같은 기능)를 이용하여 공개 및 이용하고 있습니다.
• 이 Snowflake Intelligence에 Agent를 공개할 때 권한 등 해결해야 할 포인트 등을 정리하였으므로 공유합니다.

상정 독자: Snowflake Intelligence를 이용하여 조직 내에서 AI Agent 개발 및 이용을 추진하고 싶은 분

"애초에 Cortex 시리즈는 어떤 서비스인가요?"라는 분들을 위해 기사도 게시하였으니,

괜찮으시다면 그쪽도 확인해 주시기 바랍니다.

【사용해 보았다】Snowflake Cortex 시리즈 철저 해설: Agent/Analyst/Search의 특징과 구분 사용, 비용 관리까지

이번 주제인 Snowflake Intelligence와 Cortex Agent에 대해 소개하겠습니다.

Snowflake Intelligence를 이용하여 에이전트의 공개 및 이용을 제어하는 장점도 기재하였습니다.

조직에서 생성한 에이전트의 공개 및 액세스 창구가 되는 기능입니다.

아래에 기재된 Cortex Agent를 작성한 후 본 기능에 등록함으로써, Agent를 많은 사용자에게 공개하는 것이 가능해집니다.

본 기능을 이용하여 에이전트를 공개할 경우 다음과 같은 장점이 있습니다.

• Cortex Agent 작성 후 설정 화면에서 에이전트 공개를 클릭하는 것만으로 공개/비공개를 간단히 설정 가능.
• 본 기능으로 공개한 에이전트는 Snowflake Intelligence 화면에서 쉽게 찾을 수 있음.

Snowflake Intelligence 오브젝트를 계정(Account)에서 생성함으로써 에이전트의 등록 및 공개 등을 할 수 있게 됩니다.

(이전에는 특정 Database, Schema(SNOWFLAKE_INTELLIGENCE.AGENTS)에 에이전트를 배치해야 했습니다.)

Cortex Agent의 작성 및 공개에 대해 다음을 제어할 수 있습니다.

• Agent를 임의의 Database, Schema에 작성 가능.
• Agent의 작성과 공개를 분리하는 것이 가능.
• Agent의 이용 권한을 제어함으로써 공개 범위 제어 가능.

Snowflake가 제공하는 에이전트 기능입니다.

Agent에 툴(Tool)로서 각 기능을 등록함으로써, Agent가 수행할 수 있는 태스크(Task)가 확장됩니다.

툴에는 Cortex Analyst, Cortex Search, 커스텀 툴(Custom Tool)을 등록할 수 있습니다.

Cortex Analyst나 Cortex Search에 대해서는 아래 기사에서 소개하고 있으니, 괜찮으시다면 그쪽도 확인해 주시기 바랍니다.

Snowflake Intelligence 화면상에서 사원 정보 문의 Agent를 공개 및 이용할 수 있는 상태로 만듭니다.

본 Agent는 툴로서 Cortex Analyst를 이용할 수 있으며, (가상의) 사원 정보를 사용하여 답변할 수 있는 에이전트가 됩니다.

Snowflake Intelligence 상에서 사원 정보 문의 Agent에 문의를 실시하고 있는 화면

이하 3단계로 필요한 권한과 그것을 부여하기 전후의 상태를 설명하겠습니다.

전제로, 계정에서 Snowflake Intelligence 오브젝트 생성을 부탁드립니다.

오브젝트 생성 방법은 아래를 확인해 주십시오.

Snowflake Intelligence 오브젝트를 생성한다

Agent 개발자에게 다음 권한이 있으면 Agent를 Snowflake Intelligence에 등록하는 것이 가능해집니다.

• Cortex Agent가 저장되어 있는 Database, Schema에 대한 Usage 권한.
• Cortex Agent 자체에 대한 Usage 권한.
• Snowflake Intelligence 오브젝트(SNOWFLAKE_INTELLIGENCE_OBJECT_DEFAULT)에 대한 Modify 권한.

-- Snowflake Intelligence 오브젝트에 대한 MODIFY 권한을 부여한다
GRANT MODIFY ON SNOWFLAKE INTELLIGENCE SNOWFLAKE_INTELLIGENCE_OBJECT_DEFAULT TO ROLE <role_name>;

Agent의 등록은 GUI에서도 가능하며, 아래 쿼리를 실행하여 등록할 수도 있습니다.

-- Snowflake Intelligence에 Agent를 등록하기
ALTER SNOWFLAKE INTELLIGENCE SNOWFLAKE_INTELLIGENCE_OBJECT_DEFAULT ADD AGENT <db_name>.<schema_name>.<agent_name>;

반면 이용자에게는 아래 권한을 부여함으로써, Snowflake Intelligence 상에 해당 에이전트가 표시됩니다.

• Cortex Agent가 저장되어 있는 Database, Schema에 대한 Usage 권한.
• Cortex Agent 자체에 대한 Usage 권한.
• Snowflake Intelligence 오브젝트(SNOWFLAKE_INTELLIGENCE_OBJECT_DEFAULT)에 대한 Usage 권한.

-- Snowflake Intelligence 오브젝트에 대한 USAGE 권한을 부여하기
GRANT USAGE ON SNOWFLAKE INTELLIGENCE SNOWFLAKE_INTELLIGENCE_OBJECT_DEFAULT TO ROLE <role_name>;

이용자에게 Snowflake Intelligence의 참조만을 허용한 상태

이번에 공개하려는 Agent가 화면에 표시되지 않음

이용자에게 공개하려는 Agent에 대한 각종 권한을 부여한 상태

공개하려는 Agent가 화면에 표시됨

#1을 실시함으로써, Agent를 Snowflake Intelligence에 공개할 수 있었습니다.

하지만 이 상태에서 Agent를 이용하려고 해도 아래와 같이 에러가 발생합니다.

이는 Agent가 이용하고 있는 툴(이번의 경우 Semantic View)에 대한 권한이 부족한 것이 원인입니다.

따라서, 이용자에게 아래 권한을 부여함으로써 에러를 해소할 수 있습니다.

• Semantic View가 저장되어 있는 Database, Schema에 대한 Usage 권한.
• Semantic View 자체에 대한 Select 권한.

이용자에게 Agent가 이용하는 툴에 대한 각종 권한을 부여한 상태

Agent가 질의를 처리하고 있음

사실 #2를 실시한 후 Agent에 데이터와 관련된 질의를 하면 에러는 발생하지 않지만, 정상적인 답변이 돌아오지 않습니다.

Cortex Analyst를 이용할 경우 Semantic View에 대한 Select 권한뿐만 아니라,

Semantic View의 베이스가 되는 테이블에 대해서도 Select 권한이 필요합니다.

Cortex Analyst는 질의에 대해 아래 2가지 쿼리를 생성합니다.

특히 두 번째 쿼리는 Semantic View의 베이스가 되는 테이블에 대한 쿼리이며,

이를 실행하기 위해 베이스 테이블에 대한 Select 권한이 필요합니다.

• 논리 쿼리 (Logical Query): Semantic View의 정보를 바탕으로 작성된 쿼리. 질의에 대한 해석을 쿼리로 구현한 결과임.
• 물리 쿼리 (Physical Query): 실제로 실행되는 쿼리. 상기 논리 쿼리를 바탕으로 Snowflake의 실제 테이블명, 컬럼명을 이용한 쿼리로 변환한 후 쿼리가 실행됨.

실제로 Cortex Analyst의 Playground에서 질의를 실행하면 2종류의 쿼리가 생성됩니다.

-- 논리 쿼리
SELECT
id,
...

-- 물리 쿼리
WITH __employee AS (
SELECT
...

베이스 테이블에 대한 Select 권한 부여 후 다시 에이전트에 질의를 실시한 결과, 정상적으로 답변이 생성되었습니다.

보충하자면, 베이스 테이블로부터 View를 생성하고 그것을 바탕으로 Semantic View를 작성하면, 베이스 테이블에 직접 Select 권한을 주지 않고

View에 대한 Select 권한을 주는 것만으로도 정상적으로 Cortex Analyst가 작동합니다.

-- 물리 쿼리
WITH __employee_view AS (
SELECT
...

Snowflake Intelligence에서 Agent를 안전하게 공개 및 이용하기 위해 필요한 권한의 전체 모습입니다.

구축 시나 에러 발생 시 체크리스트로 활용해 주세요.

역할	대상 오브젝트	필요한 권한	목적・용도
개발자	SNOWFLAKE_INTELLIGENCE_OBJECT_DEFAULT	MODIFY	Intelligence에 Agent 등록 및 공개 관리
대상의 Database / Schema / Agent	USAGE	Agent 생성・관리 및 참조
이용자	SNOWFLAKE_INTELLIGENCE_OBJECT_DEFAULT	USAGE	Intelligence 화면에서의 Agent 포털 참조
대상의 Database / Schema / Agent	USAGE	Agent 자체의 표시 및 실행
Semantic View가 속한 DB / Schema	USAGE	툴 (Cortex Analyst) 이용 권한
Semantic View 자체	SELECT	툴 (Cortex Analyst) 이용 권한
베이스 테이블 (또는 View)	SELECT	물리 쿼리 실행 (실제 데이터 취득)

주의사항

Cortex Analyst를 이용할 경우, 이용자의 롤 (Role)에 '베이스 테이블에 대한 SELECT 권한'이 부족하면, Agent 자체는 구동되더라도 데이터를 가져올 수 없는 (빈 응답이 되거나 에러가 발생하는) 현상이 발생합니다.

잊지 말고 권한을 부여하거나, 데이터를 숨기고 싶은 경우에는 뷰 (View)를 사이에 두는 등의 대책을 마련해 주세요.

마지막으로 제가 작업하면서 막혔던 점을 QA 형식으로 공유합니다.

#1. Agent의 등록과 공개 (Intelligence/Agent의 권한)

Snowflake Intelligence 오브젝트에 대한 Modify 권한이 부족할 가능성이 높습니다.

아래를 참고하여 개발자가 이용 중인 롤 (Role)을 재검토해 주세요.

이용자는 주로 다음과 같은 권한이 필요합니다.

• Snowflake Intelligence 오브젝트에 대한 Usage 권한
• (저장된 DB, Schema를 포함하여) Agent에 대한 Usage 권한 ⇐ 여기까지 부여하면 표시됩니다.
• (저장된 DB, Schema를 포함하여) Agent의 툴에 대한 Usage 권한 ⇐ 여기까지 부여하면 에러가 해소됩니다.

아래를 참고하여 이용자가 이용 중인 롤 (Role)을 재검토해 주세요.

#2. 툴 이용 에러 해소 (Semantic View의 권한)

Agent가 Cortex Analyst를 이용하고 있는 경우,

Semantic View뿐만 아니라 Semantic View의 베이스가 되는 테이블에 대한 Select 권한도 필요합니다.

아래는 Cortex Analyst가 Semantic View를 사용하여 쿼리를 실행할 때의 동작에 관한 참고 사항입니다.

#3. 데이터 미취득 문제 해소 (베이스 테이블의 권한)

여담이지만, Cortex Search에 대해서는 Cortex Search가 검색 대상으로 하는 Table, View에 대한 Select 권한은 불필요합니다.

Snowflake에는 PUBLIC 롤이라고 불리는, 계정 내 모든 Snowflake 사용자에게 기본적으로 부여되는 롤이 있습니다.

앞서 언급한 내용을 바탕으로 이 롤에 각종 권한을 부여해 주세요.

단, PUBLIC 롤에 대한 권한 부여는 신중하게 진행해야 합니다.

특히 Cortex Analyst를 이용할 경우, Q3에서 기술한 바와 같이 Semantic View뿐만 아니라 Semantic View의 베이스가 되는 테이블에 대한 Select 권한도 필요합니다.

만약 베이스 테이블에 직접 Select 권한을 부여하고 싶지 않다면, 뷰 (View)를 하나 생성하여 해당 뷰에 대해 Select 권한을 부여하는 방법도 가능합니다.

필요에 따라 이 방법도 검토해 보세요.