エージェントの構成と操作¶

エージェントの作成¶

エージェントを配置するデータベースとスキーマを、エージェントの名前と説明とともに指定して、エージェントオブジェクトを作成します。さらに、表示名、アバター、色を指定します。これらの属性は、クライアントアプリケーションがエージェントを表示するために使用します。表示名は、会話でエージェントを参照するためのハンドルとしても使用されます。

エージェントを作成する際のベストプラクティスについては、 Cortex Agentsの構築のベストプラクティス をご参照ください。

次の例は、Snowsight から、または REST API を使用してエージェントオブジェクトを作成する方法を示しています。

Method 1: Snowsight UIMethod 2: REST APIMethod 3: SQL

1. Snowsight にサインインします。

2. ナビゲーションメニューで AI & ML » Agents を選択します。

3. Create agent を選択します。

4. :ui:`Agent object name`の場合、UI でユーザーに表示されるエージェントの名前を指定します。

5. Display name の場合、エージェントリストの管理者に表示されるエージェントの名前を指定します。

6. Create agent を選択します。

7. 一般的な知識のリクエストでエージェントにプロンプトを表示する。

ツールを追加する¶

エージェントを作成したら、ツールを追加し、ツール間でオーケストレーションを行う方法を指示する必要があります。エージェントは以下のツールタイプをサポートします。

• Cortex Analyst:セマンティックビューを指定すると、Cortex Analystはこれらを使用して構造化データを取得します。Agentは、複数のセマンティックビューにルーティングして応答を提供できます。

  注釈

  Cortex Analystがエージェントによって呼び出された場合、オープンソース LLM モデルにアクセスできません。エージェントから呼び出されたときにCortex Analystが使用できるモデルのリストについては、 Snowflakeサービス利用表 をご参照ください。

• Cortex Search:Cortex Searchインデックスを、検索フィルター、列名、メタデータなどの関連情報を含むツールとして提供します。Cortex Agentは、Cortex Searchインデックスを使用して非構造化データを取得します。

• Data to Chart:エージェントが、データから可視化を自動的に生成できるようになります。ツール配列に含めると、エージェントは視覚的表現の恩恵を受けるクエリに応答してVega-Lite仕様を使用してチャートを作成することができます。

• カスタムツール:特定のビジネスロジックのコードを、ストアドプロシージャまたはユーザー定義関数（UDF）として実装できます。または、カスタムツールを使用して、APIs を使ってバックエンドシステムからデータを取得することもできます。

また、各ツールが使用するリソースも指定します。例えば、Cortex Analystでは、SQL クエリ実行のタイムアウトとともにウェアハウスを指定します。Cortex Searchと同様に、検索クエリで使用するフィルターと列名を、検索応答結果の最大件数とともに指定します。カスタムツールの場合は、ウェアハウスの詳細を提示します。

Method 1: Snowsight UIMethod 2: REST APIMethod 3: SQL

既存のエージェントの構成を変更するには、次のステップに従います。

1. ナビゲーションメニューで AI & ML » Agents を選択します。

2. エージェントのリストから、変更するエージェントを選択します。

   エージェントの構成の詳細が表示されます。

3. Edit を選択します。

4. Description の場合、エージェントとユーザーがそのエージェントをどのように操作できるかを説明します。

5. ユーザーがエージェントにできるサンプルの質問を追加するには、サンプルの質問を入力して Add a question を選択します。

6. Tools を選択します。次のツールを1つ以上追加します。

   • エージェントにCortex Analystのセマンティックビューを追加する場合:このセクションは、既にセマンティックビューが作成されていることを前提としています。セマンティックビューとその作成方法の詳細については、セマンティックビューの概要 をご参照ください。

     1. Cortex Analyst を検索し、+ Add ボタンを選択します。

     2. :ui:`Name`には、セマンティックビューの名前を入力します。

     3. Semantic view を選択します。

     4. エージェントが使用するセマンティックビューを選択します。

     5. Warehouse には、エージェントがクエリを実行するために使用するウェアハウスを選択します。

     6. Query timeout (seconds) には、エージェントがタイムアウトするまでにクエリが完了するまでの最大待機時間を秒単位で指定します。

     7. Description では、セマンティックビューを説明します。

     8. Add を選択します。

   • エージェントにCortex Search Serviceを追加する場合:このセクションでは、すでにCortex Search Serviceが作成されていることを前提としています。Cortex Search Serviceの作成については、Cortex Search をご参照ください。共有されているCortexナレッジ拡張機能（CKE）も使用できます。CKE を使用するチュートリアルの場合 トラブルシューティング を参照してください。

     1. Cortex Search Services を検索し、+ Add ボタンを選択します。

     2. Name には、 Cortex Search Serviceの名前を入力します。

     3. :ui:`Description`は、 Cortex Searchサービスについて説明しています。

     4. Search service では、エージェントが使用するCortex Search serviceを選択します。

     5. Add を選択します。

   • エージェントにカスタムツールを追加する場合:カスタムツールを追加することで、エージェントの機能を拡張することができます。カスタムツールを使用すると、エージェントは定義したストアドプロシージャや関数を呼び出して、アクションを実行したり計算を実行したりできます。このセクションでは、すでにカスタムツールが作成されていることを前提としています。プロシージャと関数については、 関数とプロシージャによるSnowflakeの拡張 をご参照ください。

     1. Custom tools を検索し、+ Add ボタンを選択します。

     2. Name のカスタムツールの名前を入力します。

     3. Resource type では、カスタムツールが関数かプロシージャかを選択します。関数を使用するかプロシージャを使用するかどうかの情報については、ストアドプロシージャとユーザー定義関数のどちらを記述するかの選択 をご参照ください。

     4. :ui:`Custom tool identifier`の場合、カスタムツールとして追加する既存の関数またはプロシージャを選択します。

     5. 関数またはプロシージャの関連パラメーターが自動的に表示されます。名前、タイプ、説明を追加し、パラメーターが必須かどうかを選択すると、カスタムツールのパラメーターを手動で追加できます。自動的に入力されるパラメーターを変更することもできます。

        注釈

        Snowflake Cortexは、 object 型のパラメーターを持つストアドプロシージャおよびカスタムツールをサポートしていません。

     6. Warehouse では、エージェントがカスタムツールを実行するために使用するウェアハウスを選択します。手動でウェアハウスを選択する必要があります。

     7. :ui:`Description`では、カスタムツールとその使用方法について説明します。

     8. Add を選択します。

     9. カスタムツールを作成したら、カスタムツールとしてユーザーが追加した関数またはプロシージャに対してUSAGE 権限が付与されていることを確認してください。ストアドプロシージャを使用する場合、プロシージャが所有者権限で実行されるか、呼び出し元権限で実行されるかをエージェントが維持します。所有者と呼び出し元の権利については、呼び出し元権限と所有者権限のストアドプロシージャについて をご参照ください。

7. Save を選択します。

オーケストレーションを指定します。¶

Cortex Agentは、タスクをサブタスクのシーケンスに分割し、各サブタスクに適切なツールを特定することで、タスクをオーケストレーションします。Agent がこのオーケストレーションの実行に使用する必要がある LLM を指定します。指示することで、オーケストレーションに影響を与えることもできます。たとえば、小売製品の質問に応答するように構築されたエージェントを考えてみましょう。オーケストレーションの指示 "Use the search tool for all requests related to refunds" を使用すると、確実にAgentが払い戻しポリシーの詳細を提示する（Cortex Searchを使用）だけで、実際に払い戻し金額を計算する（Cortex Analystを使用）ことがないようにできます。"Always provide provide a concise response; maintain a friendly tone" のようなブランドやトーンに合わせた応答指示を指定することもできます。

エージェントへのアクセスを設定する¶

GRANT USAGE ON AGENT <database_name>.<schema_name>.<agent_name> TO ROLE <role_name>;

Snowsight UI から、または SQL を使用してアクセスポリシーを設定し、ユーザーがAgentにアクセスできるようにします。Agentへのアクセスを提供するロールを指定します。

GRANT USAGE ON AGENT myagent TO ROLE test_rl;

エージェントを精査する¶

Agentを構築したら、Agentを精査してすべてのパラメーターを確認できます。

エージェントをテストする¶

エージェントを作成したら、ユーザーのクエリにどのように応答するかをテストできます。エージェントオブジェクトによるエージェント実行リクエスト を使用してエージェントをテストすることもできます。

エージェントをテストするには、次のステップに従います。

1. Snowsight にサインインします。

2. ナビゲーションメニューで AI & ML » Agents を選択します。

3. エージェントのリストからエージェントを選択します。

4. エージェントの詳細ページで、エージェントプレイグラウンドにクエリを入力します。

5. エージェントがクエリに対して期待どおりに応答することを確認します。エージェントが期待どおりに応答しない場合は、ツールを追加する のステップに従ってエージェントの構成を変更します。

エージェントとやり取りする¶

エージェントオブジェクトを作成したら、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"
       ]
     }
 }'

エージェントに関するフィードバックを収集する¶

エージェントの応答について、ユーザーからのフィードバックを収集できます。このフィードバックは、ユースケースを反復する際にエージェントを改良するのに役立ちます。 ユーザーは、客観的な評価（肯定的/否定的）とともに、メッセージにより主観的な詳細も提供できます。また、ユーザーは多くのカテゴリの1つにフィードバックを分類できます。

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 の詳細については、エージェントオブジェクトなしでのエージェントの実行 をご参照ください。