Cortex Agents

Get started with Cortex Agents

Try it in Snowsight

概要

Cortex Agentは、構造化データソースと非構造化データソースの両方をオーケストレーションしてインサイトを提供します。タスクを計画し、ツールを使用してこれらのタスクを実行し、応答を生成します。Agentは、LLMs とともに |cortex-analyst|（構造化）とCortex Search（非構造化）をツールとして使用し、データを分析します。Cortex Searchは非構造化ソースからインサイトを抽出しますが、|cortex-analyst| は SQL を生成して構造化データを処理します。 さらに、ストアドプロシージャとユーザー定義関数（UDFs）を使用してカスタムツールを実装できます。ツールの識別とツールの実行を包括的にサポートすることで、エンタープライズデータに基づいた高度なアプリケーションの配信を可能にします。

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

  1. 計画: アプリケーションは構造化ソースと非構造化ソースのデータを切り替えて処理することがよくあります。例えば、ユーザーのクエリに答えるように設計された会話アプリを考えてみましょう。ビジネスユーザーは、まず売上高上位の販売代理店を尋ね（構造化）、次に契約に関する問い合わせ（非構造化）に切り替えることができます。Cortex Agentは、リクエストを解析してプランをオーケストレーションし、ソリューションまたはレスポンスに到達します。

    1. オプションの探索: ユーザーが曖昧な質問（例えば、"Acme Suppliesについて教えてください"）を投げかけると、Agentは曖昧さをなくし、精度を向上させるために、製品、場所、営業担当者など、さまざまな組み合わせを検討します。

    2. サブタスクへの分割:Cortex Agentは、タスクやリクエスト（例えば、「Acme SuppliesとAcme Stationeryの契約条件の違いは何か」）を複数の部分に分割して、より的確な回答を得ることができます。

    3. ツール間のルーティング:Agentは、Cortex AnalystまたはCortex Searchという適切なツールを選択し、統制されたアクセスと企業ポリシーの遵守を保証します。

  2. ツールの使用: プランがあれば、Agent は効率的にデータを取得します。Cortex Searchは非構造化ソースから洞察を抽出し、Cortex Analystは構造化データを処理するために SQL を生成します。ツールの識別と実行を包括的にサポートすることで、企業データに基づいた高度なアプリケーションの提供が可能になります。

  3. 振り返り: 各ツールの使用後、エージェントは結果を評価し、次のステップ（説明を求める、反復する、最終的な回答を生成する）を決定します。このオーケストレーションにより、Snowflakeのセキュアな境界内で正確性とセキュリティを確保しながら、複雑なデータクエリを処理することができます。

  4. 監視と反復: 導入後、継続的な改善のために、メトリクスを追跡し、パフォーマンスを分析し、動作を改善することができます。クライアントアプリケーション開発者は、 TruLens を使用して Agent とのインタラクションを監視できます。ガバナンスコントロールを継続的に監視し改善することで、企業はセキュリティとコンプライアンスを維持しながら、 AI エージェントを自信を持って拡張することができます。

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

注釈

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

アクセス制御の要件

agent:run API を介してCortex Agentにリクエストを行うには、SNOWFLAKE.CORTEX_USER または SNOWFLAKE.CORTEX_AGENT_USER ロールが付与されたロールを使用します。CORTEX_USER が、Cortex Agentを含むすべての対象 AI 機能へのアクセスを提供する一方、CORTEX_AGENT_USER は Agent機能へのアクセスを提供します。

注釈

You must use the user's default role when calling or updating Cortex Agents. To allow another role to edit the agent, grant USAGE on the database, schema, and agent to that role.

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

セマンティックモデルで Cortex Agent を使用するには、以下の権限も必要です。

権限

オブジェクト

メモ

CREATE に AGENT

スキーマ

Cortex Agentの作成に必要です。

USAGE

Cortex Searchサービス

Cortex AgentsリクエストでCortex Searchサービスを実行するために必要です。

USAGE

データベース、スキーマ、テーブル

Cortex Agentsのセマンティックモデルで参照されるオブジェクトにアクセスするために必要です。

OWNERSHIP

エージェント

OWNERSHIP は、オブジェクトを作成したロールに自動的に付与されるオブジェクトに対する特別な権限ですが、所有ロール（または GRANT OWNERSHIP MANAGE 権限のある任意のロール）によって GRANTS コマンドを使用して別のロールに譲渡することもできます。マネージドアクセススキーマでは、スキーマ所有者（たとえば、スキーマの OWNERSHIP 権限を持つロール）または MANAGE GRANTS 権限を持つロールのみが、スキーマ内のオブジェクトに対して、将来の付与も含めて、権限を付与または取り消すことができます。

MODIFY

エージェント

Cortex Agentの更新に必要です。

MONITOR

エージェント

Cortex Agentのスレッド、ログ、トレースを表示するために必要です。

USAGE

エージェント

Cortex Agentにクエリして応答を生成するために必要です。

Cortex Agent API へのリクエストには認証トークンが含まれている必要があります。API への認証コードの詳細については、 Snowflakeでの Snowflake REST APIs 認証 をご参照ください。このトピックの例では、セッショントークンを使用してSnowflakeアカウントを認証していることに注意してください。

特定のロールへのアクセス制限

デフォルトでは、CORTEX_USERロールはPUBLICロールに付与されます。PUBLIC ロールは、すべてのユーザーとロールに自動的に付与されます。すべてのユーザーにこの権限を与えたくない場合は、PUBLICロールのアクセス権を取り消し、特定のロールにアクセス権を与えることができます。詳細については、 Cortex LLM 権限 をご参照ください。

Cortex Agentに選択的なアクセス権を提供し、ユーザーのサブセットのみがこの機能にアクセスできるようにするには、CORTEX_AGENTS_USER ロールを使用します。

Cortex Agentユーザーロールを使用したアクセス制限

特定のユーザーにCortex Agentへの選択的なアクセス権を提供するには、SNOWFLAKE.CORTEX_AGENT_USER データベースロールを使用します。このロールには、Cortex Agent API を呼び出すのに必要な権限が含まれます。

重要

ユーザーのロールに CORTEX_USER ロールがある場合、CORTEX_USER ロールへのアクセス権を取り消す必要があります。ユーザーロールから CORTEX_USER データベースロールを取り消すには、ACCOUNTADMIN ロールを使用して以下のコマンドを実行します。

REVOKE DATABASE ROLE SNOWFLAKE.CORTEX_USER FROM ROLE agent;
Copy

Cortex Agentにアクセス権を提供するには、ACCOUNTADMIN ロールを使用して以下を実行します。

  1. SNOWFLAKE.CORTEX_AGENT_USER データベースロールをカスタムロールに付与します。

  2. このカスタムロールをユーザーに割り当てます。

注釈

ユーザーにデータベースロールを直接付与することはできません。詳細については、 GRANT DATABASE ROLE をご参照ください。

次の例では、

  1. カスタムロール cortex_agent_user_role を作成します。

  2. これに CORTEX_AGENT_USER データベースロールを付与します。

  3. このロールを example_user に割り当てます。

USE ROLE ACCOUNTADMIN;
CREATE ROLE cortex_agent_user_role;
GRANT DATABASE ROLE SNOWFLAKE.CORTEX_AGENT_USER TO ROLE cortex_agent_user_role;

GRANT ROLE cortex_agent_user_role TO USER example_user;
Copy

既存のロールを介してCortex Agentへのアクセス権を付与することもできます。たとえば、組織でエージェントが使用する agent ロールがある場合、単一の GRANT ステートメントでアクセス権を付与できます。

GRANT DATABASE ROLE SNOWFLAKE.CORTEX_AGENT_USER TO ROLE agent;
Copy

認証

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

重要

Cortex Agentが使用するモデルは、すべてのリージョンで利用できるとは限りません。これらのモデルにアクセスするには、可能な場合、クロスリージョン推論を有効にする必要が生じます。詳細については、リージョンの可用性 をご参照ください。

コストの考慮事項

Cortex Agents incur charges for the orchestration and use of tools.

  • The orchestration usage is charged based on the tokens used.

  • Cortex Analyst is charged per token.

  • Cortex Search charges depend on the size of the index and the time it has persisted.

  • Warehouse charges depend on the size of the warehouse and how long it runs.

For more information, see the Snowflake Service Consumption Table. Also, use of custom tools may incur warehouse costs.

モデル

Cortex Agentでは以下のモデルを使用できます。モデルがローカルリージョンで利用できない場合は、クロスリージョン推論を使用する必要があります。

  • auto

  • claude-sonnet-4-5

  • claude-4-sonnet

  • claude-3-7-sonnet

  • claude-3-5-sonnet

  • openai-gpt-5

  • openai-gpt-4-1

エージェントを作成する際には、モデルに auto を選択することをお勧めします。このオプションを使用すると、Cortexは自動的にアカウントの最高品質のモデルを選択し、新しいモデルが利用可能になると自動的に品質が向上します。

Cortex Agentの概念

Cortex Agentは、Cortex Analyst、Cortex Search、カスタムツールを使用して、タスクを計画し、応答を生成します。指示によりオーケストレーションに影響を与えることができます。また、属性を指定して、ビジネスロジックに基づいて動的にツールを選択することもできます。

対話中、Agentはスレッドを使用してコンテキストを維持します。スレッドでは、アプリケーションロジックで使用するために、会話コンテキスト全体を簡単に取得できます。

継続的に反復してAgentを改良する際に、エンドユーザーからのフィードバックを収集できます。主観的なフィードバック（テキスト）と結び付いた明示的なフィードバックメカニズム（正/負の評価）により、Agentのライフサイクル全体でユーザー入力をキャプチャできます。

エージェントオブジェクト

エージェント構成には、エージェントオブジェクトに格納されているすべてのメタデータ、オーケストレーション設定、ツールの詳細が含まれます。エージェントオブジェクトを使って、エージェントと対話することができます。

スレッド

エージェントとのやり取りのコンテキストはスレッドで保持されるため、クライアントアプリケーション上でコンテキストを維持する必要はありません。スレッドを使用するには、スレッドオブジェクトを作成し、エージェントとのインタラクションでスレッド ID を参照します。

オーケストレーション

Cortex Agentは LLM ベースのオーケストレーションを使用してタスクを計画し、応答を生成します。オーケストレーションは次の設定で制御できます。

モデル

オーケストレーション用にCortex Agentで使用できるモデルの情報については、モデル をご参照ください。

手順

応答指示により、好みのブランドやトーンに合わせてエージェントの応答を構成できます。

サンプルの質問

これらの質問を使って、クライアントアプリケーションでの会話をシードできます。これらは、ユーザーがインタラクションを始める可能性のある一般的な質問です。

ツール

Cortex Agentは、構造化データと非構造化データの両方でオーケストレーションできます。また、カスタムツールにより、エージェントは他のバックエンドシステムと対話したり、カスタムロジックを実装したりできます。

Cortex Analystのセマンティックビュー

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

Cortex Search Service

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

注釈

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

カスタムツール

ストアドプロシージャとユーザー定義関数（UDF）を使用して、ツールとしてカスタムビジネスロジックを実装できます。詳細については、 ストアドプロシージャの概要 および ユーザー定義関数の概要 をご参照ください。

思考とリフレクション

Agentはインタラクション全体でイベントを発行し、推論プロセスに対する洞察を提供します。これらの手順は、タスクの最初の分割、サブタスクへのシーケンス、およびサブタスクのツールの選択をカバーします。さらに、エージェントは、ツールの結果と、これらがさらにオーケストレーションにどのように影響するかについてのリフレクションも表面化します。

モニターと反復

エンドユーザーからのフィードバックを評価（肯定/否定）として、主観的な入力（テキストとして）と合わせて収集することができます。これらは、ライフサイクル全体でAgentを調整および改善するために使用できます。

エージェントとのやり取り

Cortex Agentは、REST API を介してエージェントとやり取りするために2つの異なる方法をサポートしています。

  • エージェントオブジェクトがエージェントとやり取りするように構成する:このメソッドでは、まず、インタラクション全体で再利用できるエージェントオブジェクトを構成します。エージェントオブジェクトを構成すると、クライアントコードが簡素化され、エンタープライズ対応アプリケーションの CI/CD が可能になります。

  • エージェントオブジェクトなしでやりとりする:このメソッドでは、すべてのインタラクションリクエストの一部としてエージェント構成を渡す必要があります。エージェントオブジェクトなしのインタラクションにより、ユースケースを迅速に試し、さまざまなシナリオを実験できます。

これらのメソッドの詳細については、エージェントの構成と操作 をご参照ください。

言語: 日本語