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

エージェントの作成¶

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

エージェントを作成する際のベストプラクティスについては、 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. :ui:`Tool details`で、エージェントが検索サービスを効果的に利用できるように:ui:`Columns Description`を追加します。列の説明はすべての列に必要なわけではありませんが、結果の品質を向上させるために、フィルター可能な列と検索可能な列には説明を提供することをお勧めします。列の内容とサンプル値を説明する説明を提供します。

     6. 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 権限が付与されていることを確認してください。ストアドプロシージャを使用する場合、プロシージャが所有者権限で実行されるか、呼び出し元権限で実行されるかをエージェントが維持します。所有者と呼び出し元の権利については、呼び出し元権限と所有者権限のストアドプロシージャについて をご参照ください。

   • エージェントにウェブ検索ツールを追加する場合：このセクションでは、アカウントレベルでウェブ検索がすでに有効になっていることを前提としています。アカウントレベルでウェブ検索を有効にする方法について詳しくは、:ref:`label-cortex_agents_web_search`を参照してください。

     1. :ui:`Web search`を見つけ、それぞれのトグルを選択して機能を有効にします。

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" のようなブランドやトーンに合わせた応答指示を指定することもできます。

ALTER AGENT <agent_name> MODIFY LIVE VERSION SET 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 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: "Analyst1"
        description: "Converts natural language to SQL queries for financial analysis"
    - tool_spec:
        type: "cortex_search"
        name: "Search1"
        description: "Searches company policy and documentation"
    - tool_spec:
        type: "data_to_chart"
        name: "data_to_chart"
        description: "Generates visualizations from data"

  tool_resources:
    Analyst1:
      semantic_view: "db.schema.semantic_view"
    Search1:
      name: "db.schema.service_name"
      max_results: "5"
      filter:
        "@eq":
          region: "North America"
      title_column: "<title_name>"
      id_column: "<column_name>"
$$;

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

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