Cortex Agents¶

Cortex Agentは、構造化データソースと非構造化データソースの両方をオーケストレーションし、洞察を提供します。タスクを計画し、ツールを使ってタスクを実行し、レスポンスを生成します。Agentは、 LLMs とともに、 Cortex Analyst （構造化）およびCortex Search（非構造化）をデータ分析のツールとして使用します。Cortex Searchは非構造化ソースから洞察を抽出し、 Cortex Analyst は構造化データを処理するために SQL を生成します。ツールの識別と実行を包括的にサポートすることで、企業データに基づいた高度なアプリケーションの提供が可能になります。

ワークフローには4つのキーコンポーネントがあります：

計画: アプリケーションは構造化ソースと非構造化ソースのデータを切り替えて処理することがよくあります。例えば、ユーザーのクエリに答えるように設計された会話アプリを考えてみましょう。ビジネスユーザーは、まず売上高上位の販売代理店を尋ね（構造化）、次に契約に関する問い合わせ（非構造化）に切り替えることができます。Cortex Agentは、リクエストを解析してプランをオーケストレーションし、ソリューションまたはレスポンスに到達します。
1. オプションの探索: ユーザーが曖昧な質問（例えば、"Acme Suppliesについて教えてください"）を投げかけると、Agentは曖昧さをなくし、精度を向上させるために、製品、場所、営業担当者など、さまざまな組み合わせを検討します。
2. サブタスクへの分割: Cortex Agentは、タスクやリクエスト（例えば、「Acme SuppliesとAcme Stationeryの契約条件の違いは何か」）を複数の部分に分割して、より的確な回答を得ることができます。
3. ツール間のルーティング: Agentは、Cortex AnalystまたはCortex Searchという適切なツールを選択し、統制されたアクセスと企業ポリシーの遵守を保証します。
ツールの使用: プランがあれば、Agent は効率的にデータを取得します。Cortex Searchは非構造化ソースから洞察を抽出し、Cortex Analystは構造化データを処理するために SQL を生成します。ツールの識別と実行を包括的にサポートすることで、企業データに基づいた高度なアプリケーションの提供が可能になります。
振り返り: 各ツールの使用後、エージェントは結果を評価し、次のステップ（説明を求める、反復する、最終的な回答を生成する）を決定します。このオーケストレーションにより、Snowflakeのセキュアな境界内で正確性とセキュリティを確保しながら、複雑なデータクエリを処理することができます。
監視と反復: 導入後、継続的な改善のために、メトリクスを追跡し、パフォーマンスを分析し、動作を改善することができます。クライアントアプリケーション開発者は、 TruLens を使用して Agent とのインタラクションを監視できます。ガバナンスコントロールを継続的に監視し改善することで、企業はセキュリティとコンプライアンスを維持しながら、 AI エージェントを自信を持って拡張することができます。

チュートリアルについては、 Cortex Agentチュートリアルを参照してください。

注釈

Snowflakeは質の高い回答を提供するよう努めておりますが、 LLM の回答や提供された引用の正確性は保証されません。ユーザーに提供する前に、Agent API からのすべての回答を確認する必要があります。

アクセス制御の要件¶

クエリユーザーは、以下の条件を満たしている必要があります。

クエリで参照されているCortex Search Service上での USAGE。
Cortex Analystのセマンティックモデルで参照されるデータベース、スキーマ、テーブルについての USAGE。
CORTEX_USER データベースのロールが付与されたロール。詳細については、必要な権限をご参照ください。

Agent API の使い方¶

このセクションでは、Agent API を使用してエージェントを作成する手順を示します。

REST API 認証の構成¶

Snowflake REST APIs は、プログラムアクセストークン (PATs) による認証コード、 JSON Web トークン (JWTs) を使用したキーペア認証、および OAuth をサポートしています。詳細については、 Snowflakeでの Snowflake REST APIs 認証をご参照ください。

Cortex Analystのセマンティックモデルの作成¶

Cortex Analystを使用して、自然言語から SQL クエリを作成できます。Cortex Analystを使用するには、セマンティックモデルを作成する必要があります。詳細については、セマンティックモデルの作成をご参照ください。

Cortex Search Serviceの作成¶

Cortex Searchを使ってデータを検索します。詳細については、 CREATE CORTEX SEARCH SERVICE をご参照ください。

注釈

クエリユーザーの DEFAULT_ROLE は、Cortex Search Service、およびそれが存在するデータベースとスキーマに対して USAGE 権限を持っていなければなりません。

API を呼び出す¶

まず、 Snowflake アカウント URL を探します。URL と PAT ができたら、コマンドラインから cURL を使って API エージェントをクエリできます。

curl -X POST "$SNOWFLAKE_ACCOUNT_BASE_URL/api/v2/cortex/agent:run" \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header "Authorization: Bearer $PAT" \
--data '{
    "model": "llama3.1-70b",
    "messages": [
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "what are the top 3 customers by revenue"
                }
            ]
        }
    ],
    "tools": [
        {
            "tool_spec": {
                "type": "cortex_search",
                "name": "transcript_search"
            }
        },
        {
            "tool_spec": {
                "type": "cortex_analyst_text_to_sql",
                "name": "data_model"
            }
        }
    ],
    "tool_resources": {
        "transcript_search": {"name": "testdb.testschema.transcript_search_service"},
        "data_model": {"semantic_model_file": "@testdb.testschema.stage/sample_data_model.yaml"}
    }
}'

Copy

レスポンスはクライアントにインクリメンタルにストリームされます。

対応モデル¶

レスポンスを生成するために、Cortex Agentで以下のモデルを使用できます。このモデルはオーケストレーションには使用されません。

llama3.1-70b
llama3.3-70b
mistral-large2
claude-3-5-sonnet

エージェントの応答をカスタマイズするために、応答命令を指定することもできます。

{
    "response_instruction": "You will always maintain a friendly tone and provide concise response"
}

Copy

重要

Cortex Agentは、リージョンによっては入手できないモデルを使用しています。詳細については、可用性をご参照ください。

リージョンの可用性¶

Cortex Agent機能は、以下のリージョンで利用可能です。

関数（モデル）	AWS US西部2 （オレゴン）	AWS US東部1 （N.バージニア）	AWSヨーロッパ中部1 （フランクフルト）	AWS ヨーロッパ西部1 （アイルランド）	AWS AP 南東部2 (シドニー)	AWS AP 北東部1 （東京）	Azure東部 US 2 （バージニア）	Azure西ヨーロッパ（オランダ）	AWS (リージョン横断)
COMPLETE （`claude-3-5-sonnet`）	✔	✔							✔
COMPLETE （`llama3.2-1b`）	✔								✔
COMPLETE （`llama3.2-3b`）	✔								✔
COMPLETE （`llama3.1-8b`）	✔	✔	✔	✔		✔	✔	✔	✔
`llama3.1-70b`	✔	✔	✔	✔	✔	✔	✔	✔	✔
`llama3.3-70b`	✔					✔			✔
`snowflake-llama-3.3-70b`	✔								✔
`llama3.1-405b`	✔	✔					✔		✔
`snowflake-llama-3.1-405b`	✔								✔
`snowflake-arctic`	✔						✔		✔
`deepseek-r1`									✔
`reka-core`		✔							✔
`reka-flash`	✔	✔				✔			✔
`mistral-large2`	✔	✔	✔	✔	✔	✔	✔	✔	✔
`mixtral-8x7b`	✔	✔	✔	✔	✔	✔	✔	✔	✔
`mistral-7b`	✔	✔	✔	✔	✔	✔	✔	✔	✔
`jamba-instruct`	✔		✔			✔			✔
`jamba-1.5-mini`	✔		✔			✔			✔
`jamba-1.5-large`	✔								✔
`gemma-7b`	✔	✔	✔				✔	✔	✔
`e5-base-v2`	✔	✔	✔			✔	✔	✔	✔
`snowflake-arctic-embed-m`	✔	✔	✔	✔	✔	✔	✔	✔	✔
`snowflake-arctic-embed-m-v1.5`	✔	✔	✔	✔	✔	✔	✔	✔	✔
`snowflake-arctic-embed-l-v2.0`	✔	✔	✔	✔	✔	✔	✔	✔	✔
`nv-embed-qa-4`	✔								✔
`multilingual-e5-large`	✔	✔	✔	✔	✔	✔	✔	✔	✔
`voyage-multilingual-2`	✔	✔	✔	✔	✔	✔	✔	✔	✔

コストの考慮事項¶

プレビューでは、Cortex Searchサービスは、 Snowflake Service Consumption Table にリストされた詳細に従ってコストが発生します。

Cortex Agentの構築¶

Cortex Agentを使って、ビジネスユーザーからの契約条件に関する質問に答える会話型アプリケーションを実現します。主なコンポーネントをおさらいしましょう。(完全なチュートリアルについては、 Cortex Agentsを使い始めるにはを参照してください。）

ステップ1。リクエストで使用するツールを指定します。

{
    "tools": [
        {
            "tool_spec": {
                "name": "data_model",
                "type": "cortex_analyst_text_to_sql"
            }
        },
        {
            "tool_spec": {
                "name": "transcript_search",
                "type": "cortex_search"
            }
        },
        {
            "tool_spec": {
                "type": "sql_exec",
                "name": "sql_exec"
            }
        },
        {
            "tool_spec": {
                "type": "data_to_chart",
                "name": "data_to_chart"
            }
        }
    ]
}

Copy

ステップ2。Cortex Agentがツール呼び出しに使用できる静的引数（リソース）をツールに提供します。

{
    "tool_resources": {
        "data_model": {
            "semantic_model_file": "@cortex_tutorial_db.public.revenue_semantic_model.yaml"
        },
        "transcript_search": {
            "name": "cortex_tutorial_db.public.contract_terms",
            "max_results": 5,
            "title_column": "TRANSCRIPT_TITLE",
            "id_column": "TRANSCRIPT_ID",
            "filter": {"@eq": {"TRANSCRIPT_TYPE": "ENTERPRISE"} }
        }
    }
}

Copy

ステップ3。では、モデルとシステムプロンプトを指定して、応答を生成します。

{
    "model": "claude-3-5-sonnet",
    "messages": [
        {
            "role": "system",
            "content": {
                "type": "text",
                "text": "You’re a friendly assistant to answer questions."
            }
        }
    ]
}

Copy

ステップ4。Analystツールが構造化データにアクセスするために使用するセマンティックモデルファイルの作成

このガイドのステップ1から3に従い、Cortex Analystのセマンティックモデルを作成します。 Cortex Agentを使い始めるには

ステップ5。次に、構造化されていないデータにアクセスするために、Searchツールの検索サービスをセットアップします。

このガイドのステップ4から5に従って、Cortex Search Service Cortex Agentを使い始めるにはを作成します。

ステップ6: これでAgentと対話する準備ができました。メッセージフィールドを使ってリクエストを送信し、レスポンスを受け取ります。

{
    "model": "claude-3-5-sonnet",
    "messages": [
        {
            "role": "system",
            "content": [
                {
                    "type": "text",
                    "text": "You’re a friendly assistant to answer questions"
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "hello"
                }
            ]
        },
        {
            "role": "assistant",
            "content": [
                {
                    "type": "text",
                    "text": "hi there!"
                }
            ]
        },
        {
            "role": "user",
            "content": [
                {
                    "type": "text",
                    "text": "..."
                }
            ]
        }
    ]
}

Copy

ステップ7。インタラクションが進むにつれ、Agentはツールを識別子し、タスクを実行します（サービスサイド）。以下の例では、Agent は Text2SQL をツールとして識別子し、 SQL クエリを取得するために実行します。インタラクション中、Agentはクライアントアプリケーション（クライアントサイド）のツール使用をリクエストすることができます。例えば、Agentは実行すべきクエリ (SQL) を指定します。

{
    "role": "assistant",
    "content": [
        {
            "type": "tool_use",
            "tool_use": {
                "tool_use_id": "tool_001",
                "name": "cortex_analyst_text_to_sql",
                "input": {
                    "query": "...",
                    "semantic_model_file": "..."
                }
            }
        },
        {
            "type": "tool_results",
            "tool_results": {
                "status": "success",
                "tool_use_id": "tool_001",
                "content": [
                    {
                        "type": "json",
                        "json": {
                            "sql": "select * from table"
                        }
                    }
                ]
            }
        },
        {
            "type": "tool_use",
            "tool_use": {
                "tool_use_id": "tool_002",
                "name": "sql_exec",
                "input": {
                    "sql": "select * from table"
                }
            }
        }
    ]
}

Copy