에이전트 구성 및 상호 작용¶

에이전트 생성하기¶

에이전트의 이름 및 설명과 함께 에이전트가 위치해야 하는 데이터베이스 및 스키마를 지정하여 에이전트 오브젝트를 생성합니다. 또한 표시 이름, 아바타, 색상을 지정합니다. 이러한 특성은 클라이언트 애플리케이션에서 에이전트를 표시하는 데 사용됩니다. 표시 이름은 대화에서 에이전트를 참조하기 위한 핸들로도 사용됩니다.

다음 예에서는 |sf-web-interface|에서 또는 REST API를 사용하여 에이전트 오브젝트를 만드는 방법을 보여줍니다.

Method 1: Snowsight UIMethod 2: REST API

1. Snowsight 에 로그인합니다.

2. 탐색 메뉴에서 AI & ML » Agents 를 선택합니다.

3. Create agent 을 선택합니다.

4. :ui:`Agent object name`의 경우, UI에 표시될 에이전트 이름을 지정합니다.

5. :ui:`Display name`의 경우, 에이전트 목록에서 관리자에게 표시될 에이전트 이름을 지정합니다.

6. Create agent 을 선택합니다.

7. 에이전트에 일반 상식 요청을 입력합니다.

도구 추가¶

에이전트를 만든 후에는 도구를 추가하고 여러 도구를 오케스트레이션하는 방법에 대한 지침을 제공해야 합니다. 에이전트가 지원하는 도구 유형은 다음과 같습니다.

• Cortex Analyst: Cortex Analyst가 이러한 뷰를 사용하여 정형 데이터를 검색할 수 있도록 의미 체계 뷰를 지정합니다. 에이전트는 여러 의미 체계 뷰에 걸쳐 라우팅하여 응답을 제공할 수 있습니다.

• Cortex Search: 검색 필터, 열 이름, 메타데이터와 같은 관련 정보를 포함하여 Cortex Search 인덱스를 도구로 제공합니다. Cortex Agent는 Cortex Search 인덱스를 사용하여 비정형 데이터를 검색합니다.

• 사용자 지정 도구: 특정 비즈니스 논리에 대한 코드를 저장 프로시저 또는 UDF(사용자 정의 함수)로 구현할 수 있습니다. 또는 사용자 지정 도구를 사용하여 APIs를 통해 백엔드 시스템에서 데이터를 검색할 수 있습니다.

또한 각 도구에서 사용하는 리소스도 지정합니다. 예를 들어, Cortex Analyst에서 SQL 쿼리 실행에 대한 시간 제한과 함께 웨어하우스를 지정합니다. Cortex Search와 유사하게, 검색 응답의 최대 결과와 함께 검색 쿼리에 사용되는 필터와 열 이름을 지정합니다. 사용자 지정 도구의 경우 웨어하우스 세부 정보를 입력합니다.

Method 1: Snowsight UIMethod 2: REST API

기존 에이전트의 구성을 수정하려면 다음 단계를 완료합니다.

1. Edit 를 선택합니다.

2. :ui:`Description`에 에이전트와 사용자가 상호 작용할 수 있는 방법을 설명합니다.

3. 사용자가 에이전트에 질문할 수 있는 샘플 질문을 추가하려면 샘플 질문을 입력하고 :ui:`Add a question`을 선택합니다.

4. Tools 를 선택합니다. 다음 도구 중 하나 이상을 추가합니다.

   • Cortex Analyst의 의미 체계 뷰를 에이전트에 추가하려면: 이 섹션에서는 이미 의미 체계 뷰가 생성되어 있다고 가정합니다. 의미 체계 뷰에 대한 정보 및 생성 방법은 의미 체계 뷰 개요 섹션을 참조하세요.

     1. Cortex Analyst`를 찾아 해당 :ui:`+ Add 버튼을 선택합니다.

     2. :ui:`Name`에 의미 체계 뷰의 이름을 입력합니다.

     3. Semantic view 을 선택합니다.

     4. 에이전트가 사용하는 의미 체계 뷰를 선택합니다.

     5. :ui:`Warehouse`에서 에이전트가 쿼리를 실행하는 데 사용하는 웨어하우스를 선택합니다.

     6. :ui:`Query timeout (seconds)`에 에이전트가 시간 제한 전에 쿼리 완료를 기다리는 최대 시간을 초 단위로 지정합니다.

     7. :ui:`Description`에 의미 체계 뷰를 설명합니다.

     8. Add 를 선택합니다.

   • 에이전트에 Cortex Search Service를 추가하려면: 이 섹션에서는 이미 Cortex Search Service를 생성했다고 가정합니다. Cortex Search Service 생성 방법에 대한 정보는 Cortex Search 섹션을 참조하세요. 공유된 Cortex Knowledge Extension(CKE)도 사용할 수 있습니다. CKE를 사용하는 자습서는 문제 해결하기 섹션을 참조하세요.

     1. Cortex Search Services`를 찾아 해당 :ui:`+ Add 버튼을 선택합니다.

     2. :ui:`Name`에 Cortex Search Service의 이름을 입력합니다.

     3. :ui:`Description`에 Cortex Search Service를 설명합니다.

     4. :ui:`Search service`에서 에이전트가 사용하는 Cortex Search Service를 선택합니다.

     5. Add 를 선택합니다.

   • 에이전트에 사용자 지정 도구를 추가하려면: 사용자 지정 도구를 추가함으로써 에이전트의 기능을 확장할 수 있습니다. 사용자 지정 도구를 사용하면 에이전트가 정의한 저장 프로시저 및 함수를 호출하여 작업을 수행하거나 계산을 수행할 수 있습니다. 이 섹션에서는 사용자 지정 도구를 이미 만들었다고 가정합니다. 프로시저 및 트랜잭션에 대한 자세한 내용은 함수와 프로시저로 Snowflake 확장하기 섹션을 참조하세요.

     1. Custom tools`를 찾아 해당 :ui:`+ Add 버튼을 선택합니다.

     2. :ui:`Name`에 사용자 지정 도구의 이름을 입력합니다.

     3. Resource type`에서 사용자 지정 도구가 함수인지 프로시저인지 선택합니다. 함수 또는 프로시저 사용 여부에 대한 정보는 :doc:/developer-guide/stored-procedures-vs-udfs` 섹션을 참조하세요.

     4. :ui:`Custom tool identifier`에서 사용자 지정 도구로 추가하려는 기존 함수 또는 프로시저를 선택합니다.

     5. 함수나 프로시저의 관련 매개 변수가 자동으로 표시됩니다. 사용자 지정 도구에 대한 매개 변수를 수동으로 추가하여 이름, 유형, 설명을 입력하고 해당 매개 변수가 필수 항목인지 여부를 선택할 수 있습니다. 자동으로 채워지는 매개 변수를 수정할 수도 있습니다.

     6. :ui:`Warehouse`에서 에이전트가 사용자 지정 도구를 실행하는 데 사용하는 웨어하우스를 선택합니다. 웨어하우스를 수동으로 선택해야 합니다.

     7. :ui:`Description`에 사용자 지정 도구와 해당 사용법을 설명합니다.

     8. Add 를 선택합니다.

     9. 사용자 지정 도구를 생성한 후, 사용자 지정 도구로 추가한 함수 또는 프로시저에 대해 사용자에게 USAGE 권한이 부여되었는지 확인합니다. 저장 프로시저를 사용할 때 에이전트는 프로시저를 소유자 권한으로 실행할지, 호출자 권한으로 실행할지를 지정합니다. 소유자 권한 및 호출자 권한에 대한 자세한 내용은 호출자 권한 및 소유자 권한 저장 프로시저 이해하기 섹션을 참조하세요.

5. Save 를 선택합니다.

오케스트레이션 지정¶

Cortex Agent는 작업을 하위 작업 시퀀스로 나누고 각 하위 작업에 적합한 도구를 식별하여 작업을 오케스트레이션합니다. 에이전트가 이 오케스트레이션을 수행하는 데 사용해야 하는 LLM을 지정할 수 있습니다. 또한 지침을 제공하여 오케스트레이션에 영향을 줄 수도 있습니다. 예를 들어, 리테일 제품 질문에 응답하도록 만든 에이전트가 있다고 가정해 보겠습니다. 오케스트레이션 지침 "Use the search tool for all requests related to refunds"`를 사용하여 에이전트가 (Cortex Search를 사용하여) 환불 정책 세부 정보만 제공하고 (Cortex Analyst를 사용하여) 실제로 환불 금액을 계산하지 않도록 할 수 있습니다. 브랜드 또는 어조에 따라 응답을 조정하도록 지침을 지정할 수도 있습니다(예: :code:”Always provide provide a concise response; maintain a friendly tone”`).

에이전트에 대한 액세스 설정¶

사용자가 에이전트에 액세스할 수 있도록 Snowsight UI에서 또는 SQL을 사용하여 액세스 정책을 설정합니다. 에이전트에 대한 액세스 권한을 제공할 역할을 지정합니다.

GRANT USAGE PRIVILEGE ON AGENT my_agent TO ROLE test_rl;

에이전트 검토¶

에이전트를 만든 후에는 에이전트를 검토하여 모든 매개 변수를 확인할 수 있습니다.

에이전트 테스트¶

에이전트를 만든 후에는 테스트하여 사용자 쿼리에 어떻게 응답하는지 확인할 수 있습니다. :ref:`label_snowflake_data_agents_run_rest_api`을 사용하여 에이전트를 테스트할 수도 있습니다.

에이전트를 테스트하려면 다음 단계를 따릅니다.

1. Snowsight 에 로그인합니다.

2. 탐색 메뉴에서 AI & ML » Agents 를 선택합니다.

3. 에이전트 목록에서 에이전트를 선택합니다.

4. 에이전트 세부 정보 페이지에서 에이전트 플레이그라운드에 쿼리를 입력합니다.

5. 에이전트가 쿼리에 예상대로 응답하는지 확인합니다. 에이전트가 예상대로 응답하지 않으면 :ref:`label_snowflake_agents_modify_agents`의 단계에 따라 에이전트의 구성을 수정합니다.

에이전트와 상호 작용¶

에이전트 오브젝트를 생성한 후 REST API를 사용하여 에이전트를 애플리케이션에 직접 통합할 수 있습니다. 상호 작용 중에 컨텍스트를 유지하려면 스레드를 사용합니다. 에이전트 오브젝트와 스레드가 결합되어 클라이언트 애플리케이션 코드가 간소화됩니다.

curl -X POST "$SNOWFLAKE_ACCOUNT_BASE_URL/api/v2/cortex/threads" \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "Authorization: Bearer $PAT" \
--data '{
    "origin_application": <application_name>,
}'

curl -X POST "$SNOWFLAKE_ACCOUNT_BASE_URL/api/v2/databases/{database}/schemas/{schema}/agents/{name}:run" \
 --header 'Content-Type: application/json' \
 --header 'Accept: application/json' \
 --header "Authorization: Bearer $PAT" \
 --data '{
     "thread_id": <thread id for context>,
     "parent_message_id": <parent message id>,
     "messages": [
      {
         "role": "user",
         "content": [
           {
            "type": "text",
             "text": "What are the projected transportation costs for the next three quarters? "
             }
         ]
       }
     ],
     "tool_choice": {
       "type": "required",
       "name": [
         "Analyst1",
         "Search1"
       ]
     }
 }'

에이전트에 대한 피드백 수집¶

에이전트가 제공한 응답에 대한 사용자 피드백을 수집할 수 있습니다. 이 피드백은 사용 사례를 반복하면서 에이전트를 개선하는 데 도움이 될 수 있습니다. 사용자는 객관적인 평가(긍정/부정)과 더불어, 메시지에 더 주관적인 세부 정보도 제공할 수 있습니다. 또한, 사용자는 여러 카테고리 중 하나로 피드백을 분류할 수 있습니다.

curl -X POST "$SNOWFLAKE_ACCOUNT_BASE_URL/api/v2/databases/<database-name>/schemas/<schema-name>/agents/<agent-name>:feedback:" \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "Authorization: Bearer $PAT" \
--data '{
    "request_id": "<request-id>",
    "positive": true
    "feedback_message": "This answer was great",
    "categories":[
        "category1", "category2", "category3"
    ],
    "thread_id": "<thread-id>"
}'

에이전트 오브젝트 없이 상호 작용¶

경우에 따라 에이전트 오브젝트 없이 agent:run`을 사용하여 Cortex Agent를 시작할 수도 있습니다. 예를 들어, 사용 사례를 빠르게 시험해 보고 싶을 때 이 방식이 유용할 수 있습니다. REST API에 대한 자세한 내용은 :ref:`label_snowflake_lite_agents_run_rest_api 섹션을 참조하세요.