빌드 에이전트¶

에이전트 구조¶

에이전트는 다음 부분으로 구성됩니다.

• 에이전트 동작의 기반을 제공하는 기본 모델

• 의도를 해석하고, 올바른 도구를 선택하며, 일련의 작업을 계획하는 모델(오케스트레이터)

• 에이전트 동작 지침

• 에이전트가 사용할 도구

• 도구에 대한 리소스

다음 섹션에서는 모델 선택 및 도구 구성에 대한 정보를 제공합니다. 이 예제에서는 의미 체계 뷰, Cortex Search Service, 사용자 지정 도구를 사용하여 답변을 제공합니다. 이러한 도구를 전혀 사용하지 않는 기본 에이전트를 생성할 수는 있지만, 해당 기본 에이전트는 답변을 제공하기 위해 기본 모델만 사용할 수 있습니다. 결과적으로 에이전트는 해당 Snowflake 계정 내 데이터에 액세스할 수 없으며 답변을 위한 컨텍스트가 제한됩니다.

에이전트의 다른 구성 요소에 대한 자세한 내용은 Cortex Agents 섹션을 참조하세요.

전제 조건¶

Cortex Agent를 생성하려면 다음 권한이 있는 역할을 사용해야 합니다.

다음 코드는 Cortex Agent를 생성하는 데 필요한 권한을 부여합니다.

GRANT USAGE ON DATABASE <database_name> to ROLE <role_name>;
GRANT USAGE ON SCHEMA <database_name>.<schema_name> to ROLE <role_name>;
GRANT CREATE AGENT ON SCHEMA <database_name>.<schema_name> to ROLE <role_name>;

Copy

Cortex Agent를 생성하는 데 필요한 권한 외에도, 에이전트를 특정 도구에 연결하려면 다음 전제 조건이 필요합니다.

• 에이전트에 연결하기 위한 의미 체계 뷰

  의미 체계 뷰 생성에 대한 자세한 내용은 의미 체계 뷰 개요 섹션을 참조하세요.

• 에이전트에 연결하기 위한 Cortex Analyst 도구

  Cortex Analyst 도구 생성에 대한 자세한 내용은 Cortex Analyst 섹션을 참조하세요.

• 에이전트에 연결할 데이터베이스의 비정형 데이터

• 에이전트에 연결하기 위한 Cortex Search 도구

  Cortex Search 도구 생성 방법에 대한 자세한 내용은 Cortex Search 섹션을 참조하세요.

• 에이전트에 연결하기 위한 사용자 지정 도구

  사용자 정의 함수(UDFs) 및 저장 프로시저를 생성하여 사용자 지정 도구로 사용하는 것에 대한 자세한 내용은 함수와 프로시저로 Snowflake 확장하기 섹션을 참조하세요.

에이전트에 도구를 연결하려면 에이전트를 생성하는 데 사용되는 역할에 다음 권한이 있어야 합니다.

에이전트 구성 기본 사항¶

에이전트를 생성할 때 이름, 설명, 모델 등 에이전트에 대한 정보를 지정해야 합니다. 에이전트가 사용할 수 있는 도구와 에이전트가 액세스할 수 있는 리소스를 지정할 수도 있습니다. 이러한 리소스는 CREATE AGENT 명령의 FROM SPECIFICATION 절에서 YAML 사양으로 전달됩니다.

다음 권장 사항은 해당 구성에 대한 모범 사례를 제공합니다.

에이전트 범위 좁히기: 도구를 추가하거나 지침을 작성하기 전에 에이전트의 존재 이유, 해당 역할, 답변해야 하는 구체적인 질문을 정의합니다. 이 단계는 도구 선택에서 성능 및 신뢰에 이르기까지 모든 후속 단계를 형성합니다. Snowflake는 에이전트의 범위를 구체적이고 가치가 높은 사용 사례로 좁힐 것을 권장합니다.

에이전트가 한 영역에서 신뢰할 수 있는 것으로 입증되면 다른 영역에 대해 패턴을 복제할 수 있습니다. 예를 들어, 매장의 최근 판매 및 마케팅 데이터를 분석하는 에이전트와 소매업체에 제안할 최고의 SKUs를 추천하는 다른 에이전트가 있을 수 있습니다.

신중하게 도구 수 선택: 모든 에이전트는 필요한 도구에만 액세스할 수 있어야 합니다. 이를 확인하려면 에이전트가 목적을 달성하는 데 필요한 문서 또는 데이터를 고려합니다. 에이전트가 비정형 데이터에 액세스해야 하는 경우 Cortex Search 를 사용합니다. 에이전트가 정형 데이터에 액세스해야 하는 경우 Cortex Analyst 를 사용합니다. 에이전트에 다른 도구가 필요한 경우 사용자 지정 도구를 사용할 수 있습니다.

유용한 도구 설명 작성: 이러한 설명은 에이전트가 도구의 기능과 사용 방법을 이해하는 데 도움이 됩니다. 명확하지 않은 도구 설명은 계단식 오류를 발생시키고 “할루시네이션(hallucination)”을 유발할 수 있습니다.

유용한 도구 설명을 생성하려면 다음 지침을 따릅니다.

• 도구의 도메인(“고객”, “영업”)과 함수(“Analytics”, “Search”)를 명시하는 명확하고 구체적인 도구 이름을 추가합니다.

• 에이전트에 다음 사항을 알려주는 목적 중심의 도구 설명을 작성합니다.

  • 도구의 기능

  • 액세스하는 데이터

  • 사용하는 경우

  • 사용하지 않는(NOT) 경우

• 도구의 예상 입력에 대해 명시해야 합니다. 도구에 대한 모호한 입력은 잘못된 도구 호출과 오류로 이어집니다.

  • 구체적으로 설명하십시오.

  • 데이터 형식을 지정합니다.

  • 명확한 데이터 지침을 제공합니다.

  • 기본 지침을 제공합니다.

  • 일관된 용어를 사용합니다.

더 많은 에이전트 구성 권장 사항은 `Cortex Agent 빌드 모범 사례 <https://www.snowflake.com/en/developers/guides/best-practices-to-building-cortex-agents/>`_를 참조하세요.

모델 선택¶

에이전트를 생성할 때 모델에 대해 auto`를 선택하는 것이 좋습니다. 이 옵션을 사용하면 Cortex가 계정에 대해 가장 높은 품질의 모델을 자동으로 선택하며, 새 모델을 사용할 수 있게 되면 품질이 자동으로 향상됩니다. 사용 가능한 모델에 대한 자세한 내용은 :ref:`label_snowflake_intelligence_models 섹션을 참조하세요.

다음 예제에서는 에이전트의 모델을 지정하는 방법을 보여줍니다.

models:
  orchestration: auto

ALTER ACCOUNT SET CORTEX_ENABLED_CROSS_REGION = 'ANY_REGION';

Cortex Analyst를 사용하여 의미 체계 뷰 연결(정형 데이터)¶

Snowflake Intelligence는 에이전트에 데이터를 쿼리하거나 해석하는 방법을 알려주는 지침이 포함된 정형 데이터 유형인 의미 체계 뷰를 지원합니다. Cortex Agent는 Cortex Analyst를 통해 자연어 요청을 SQL 쿼리로 변환하여 의미 체계 뷰에서 정형 데이터를 검색합니다. 에이전트는 여러 의미 체계 뷰에 걸쳐 라우팅하여 응답을 제공할 수 있습니다.

각 의미 체계 뷰는 유사한 테이블 세트를 포함해야 합니다. 지정하지 않은 경우 항상 지난 3개월 동안의 날짜 필터를 추가하거나 항상 내부 계정을 제외하는 등 데이터별 기본값을 설정할 수 있습니다.

의미 체계 뷰를 도구 리소스의 일부로 지정하여 의미 체계 뷰를 에이전트에 연결할 수 있습니다. 다음 예제에서는 의미 체계 뷰를 에이전트에 연결하는 방법과 의미 체계 뷰에서 정형 데이터를 검색하기 위해 Cortex Analyst 도구를 지정하는 방법을 보여줍니다.

tools:
  - tool_spec:
      type: "cortex_analyst_text_to_sql"
      name: "<your cortex analyst tool name>"
      description: "<clear and specific tool description>"

tool_resources:
  <your cortex analyst tool name>:
    semantic_view: "<db>.<schema>.<semantic_view>"

Cortex Search 연결(비정형 데이터)¶

비정형 데이터를 처리하려면 도구 리소스의 일부로 YAML 사양에서 Cortex Search 도구를 지정하여 Cortex Search 도구를 에이전트에 연결하면 됩니다. Cortex Search 서비스는 의미 체계 검색을 사용하여 비정형 데이터 소스에서 문서와 레코드를 검색합니다. Cortex Search의 두 가지 주요 사용 사례는 RAG(retrieval augmented generation) 및 엔터프라이즈 검색입니다 Cortex Search Service 생성 방법에 대한 정보는 Cortex Search 섹션을 참조하세요. 공유된 Cortex Knowledge Extension(CKE)도 사용할 수 있습니다.

Cortex Search 도구를 에이전트에 연결할 때 매개 변수와 예상 값에 대한 다음 정보를 포함하는 것이 특히 중요합니다.

• 유형 및 형식(예제 포함)

• 필수 또는 선택 사항(기본값 포함)

• 유효한 값 또는 제약 조건(열거형, 범위, 형식)

• 다른 매개 변수와의 관계(종속성, 충돌)

• 값을 얻는 방법(특히 IDs의 경우)

다음 예제에서는 Cortex Search 도구를 에이전트에 연결하는 방법과 YAML 사양에서 Cortex Search 도구를 지정하는 방법을 보여줍니다.

tools:
  - tool_spec:
      type: "cortex_search"
      name: "<your cortex search tool name>"
      description: "<clear and specific tool description>"

tool_resources:
  <your cortex search tool name>:
    name: "<db>.<schema>.<search_service_name>"
    max_results: "5"
    filter:
      "@eq":
        region: "North America"
    title_column: "<title_name>"
    id_column: "<column_name>"

사용자 지정 도구¶

Snowflake Intelligence는 사용자 지정 비즈니스 논리를 구현하는 데 사용할 수 있는 사용자 정의 함수 또는 저장 프로시저인 사용자 지정 도구를 지원합니다. 도구 리소스의 일부로 YAML 사양에서 사용자 지정 도구를 지정하여 사용자 지정 도구를 에이전트에 연결할 수 있습니다.

다음 예제에서는 사용자 지정 도구를 에이전트에 연결하는 방법과 YAML 사양에서 사용자 지정 도구를 지정하는 방법을 보여줍니다.

tools:
  - tool_spec:
      type: "custom_tool"
      name: "<your custom tool name>"
      description: "<clear and specific tool description>"

tool_resources:
  <your custom tool name>:
    user-defined-function-argument: "argument1"

에이전트 생성하기¶

• 모든 도구와 구성 요소를 결합하여 SQL을 통해 에이전트를 생성합니다.

  CREATE OR REPLACE AGENT <agent_name>
      COMMENT = 'agent level comment'
      PROFILE = '{"display_name": "My Business Assistant", "avatar":  "business-icon.png", "color": "blue"}'
      FROM SPECIFICATION
      $$
      models:
      orchestration: claude-4-sonnet
  
      orchestration:
      budget:
          seconds: 30
          tokens: 16000
  
      instructions:
      response: "You will respond in a friendly but concise manner"
      orchestration: "For any revenue question, use Analyst; for policy questions, use Search"
      system: "You are a friendly agent that helps with business questions"
      sample_questions:
          - question: "What was our revenue last quarter?"
          answer: "I'll analyze the revenue data using our financial database."
  
      tools:
      - tool_spec:
          type: "cortex_analyst_text_to_sql"
          name: "<your cortex analyst tool name>"
          description: "<clear and specific tool description>"
      - tool_spec:
          type: "cortex_search"
          name: "<your cortex search tool name>"
          description: "<clear and specific tool description>"
      - tool_spec:
          type: "data_to_chart"
          name: "data_to_chart"
          description: "Generates visualizations from data"
  
      tool_resources:
      <your cortex analyst tool name>:
          semantic_view: "<db>.<schema>.<semantic_view>"
      <your cortex search tool name>:
          name: "<db>.<schema>.<search_service_name>"
          max_results: "5"
          filter:
          "@eq":
              region: "North America"
          title_column: "<title_name>"
          id_column: "<column_name>"
      $$;
  

  Copy

기존 에이전트 수정하기¶

도구 추가 및 기타 세부 정보 업데이트를 포함하여 기존 에이전트의 구성을 수정하는 방법에 대한 지침은 도구 추가 섹션을 참조하세요.