Snowflake Cortex Agentsとは？CREATE AGENT・REST API・権限設定の実装手順

Snowflake Cortex Agentsは、Snowflakeのガバナンス境界の内側でAIエージェントを構築・実行するためのマネージド基盤です。エージェントはユーザーの依頼を解釈して実行計画を立て、Cortex AnalystやCortex Searchなどのツールを呼び出し、結果をまとめて返します。オーケストレーションのためのサーバーを別途用意する必要はありません。この記事では、スキーマレベルのAGENTオブジェクトを作るCREATE AGENT構文、agent:runのREST APIとSQL関数、権限設計、そしてAI Creditsによる課金の見積もりまで、Snowflake公式ドキュメントの記述に沿って整理します。

まとめ

• Cortex Agentsはスキーマレベルのオブジェクトで、Snowsight・SQL・REST APIの3経路で作成できる。SQLではCREATE AGENT ... FROM SPECIFICATION $$ ... $$ にYAMLで定義を書く。
• ツールはcortex_analyst_text_to_sql（構造化データのSQL生成）、cortex_search（非構造化データの検索）、data_to_chart（可視化）、generic（ストアドプロシージャ・UDF）、web_searchなどをtoolsに列挙し、参照先をtool_resourcesに紐付ける。
• 実行経路は3つ。REST APIのPOST /api/v2/databases/{db}/schemas/{schema}/agents/{name}:run、オブジェクトを作らないインライン実行のPOST /api/v2/cortex/agent:run、そしてSQL関数のSNOWFLAKE.CORTEX.DATA_AGENT_RUN／AGENT_RUN。SQL関数は常に非ストリーミングで返る。
• Pythonからはsnowflake.core.cortex.lite_agent_service.CortexAgentServiceのrun()が使える（AgentRunRequestを受け取りSSEClientを返す）。
• 利用側のロールにはSNOWFLAKE.CORTEX_USERまたはSNOWFLAKE.CORTEX_AGENT_USERデータベースロールが要る。CORTEX_USERは既定でPUBLICに付与済みのため、エージェントだけに絞りたいならCORTEX_USERのREVOKEが要る。
• 課金はAI Credits建てで、処理トークン100万あたりで課金される。AI CreditsはエディションによらずOn Demandで1クレジット2.00ドル（グローバルルーティング）／2.20ドル（リージョナル）。オーケストレーションと各ツールの費用は積み上がる。
• 2026年6月のSnowflake Summitで、Cortex Agents APIを土台とするSnowflake IntelligenceはSnowflake CoWorkへ改称された。

Cortex Agentsの定義とSnowflake CoWorkとの関係

エージェントが担う範囲：計画・ツール呼び出し・応答生成

公式ドキュメントはCortex Agentsを「Snowflakeのガバナンスされた環境の内側でAIエージェントを構築・実行するフルマネージドのエージェント基盤」と定義しています。エージェントは依頼を推論し、作業を計画し、ツールを呼び、コードを実行し、応答を生成します。従来のルールベース自動化との差は、実行順序を人があらかじめ固定するのではなく、オーケストレーションモデル（Claude／GPT／Grok／Geminiの各系列。auto指定ならSnowflakeがアカウントで利用可能な最高品質のモデルを選ぶ）が依頼ごとに呼ぶツールと順序を決める点にあります。

Snowflake IntelligenceがCoWorkへ改称した経緯

「Snowflake Intelligence」を探している場合、2026年6月開催のSnowflake Summit 2026で同製品がSnowflake CoWorkへ改称された点に注意してください。CoWorkはすぐ使える対話型のエージェントアプリケーションで、公式ドキュメントは「質問はCortex Agent APIへルーティングされ、それがSnowflake CoWorkを動かしている」と説明しています。つまりCoWorkは完成品のUI、Cortex Agentsはその下で動くAPIとオブジェクトです。自社アプリにエージェントを組み込むなら後者を直接叩き、社内の分析担当が対話的に使うだけならCoWorkのWebアプリで足ります。なお、CoWorkのiOSモバイルアプリはプレビュー扱いです。

Cortex Analyst・Cortex Searchとの役割分担

Cortex AnalystとCortex Searchはエージェントと並ぶ別機能ではなく、エージェントが呼ぶツールです。Cortex Analystはセマンティックビューを参照して自然言語からSQLを生成し、構造化データの集計に答えます。Cortex Searchは非構造化テキストから該当箇所を取り出します。「売上が落ちた理由は」のように両方が要る問いで、どちらを何回呼ぶかを決めるのがエージェントの役割です。Cortexというブランド全体の機能構成はCortex AI（Snowflake）とは？主要機能・導入メリット・読み方を解説で整理しています。

tool_specで指定できるツールの型

ツールは仕様のtoolsにtool_specとして列挙し、必要な参照先をtool_resourcesにツール名で紐付けます。tool_resourcesのキーは、対応するツールのnameと一致していなければなりません。仕様に書ける主な型は次のとおりです。

このほかに、隔離サンドボックス内でのPython実行、指示とスクリプトを束ねたエージェントスキル、リモートのMCPサーバー上のツールへ接続するMCPコネクタが利用できます。自社の業務ロジックをエージェントに実行させたい場合は、まず既存のストアドプロシージャをgenericツールとして登録するのが最短経路です。

ここで1つ落とし穴があります。Cortex Searchの参照先を指すキーは、CREATE AGENTのYAML仕様ではname、REST APIのリクエストボディではsearch_serviceと、公式ドキュメントの中でも表記が分かれています。SQLで作ったエージェント定義をそのままRESTのボディへ流用すると、ここでツールが参照先を見失います。

CREATE AGENTによる構築手順

AGENTオブジェクトを作成するSQL

エージェントはテーブルやビューと同じくスキーマに属するオブジェクトです。作成するロールには、対象スキーマに対するCREATE AGENT権限、Cortex SearchサービスへのUSAGE、参照するデータベース・スキーマ・テーブルへのUSAGEが要ります。models.orchestrationにはモデル名を直接書けますが、利用できるモデルはリージョンによって異なるため、特定のモデルに固定する理由がなければautoのままにしておくのが安全です。

CREATE OR REPLACE AGENT sales_agent
  COMMENT = 'sales support agent'
  PROFILE = '{"display_name": "Sales Assistant"}'
  FROM SPECIFICATION
  $$
  models:
    orchestration: auto
  orchestration:
    budget:
      seconds: 30
      tokens: 16000
  instructions:
    response: "根拠にしたテーブル名を必ず併記して回答する"
    orchestration: "売上・数値の問いはAnalyst1、規程や議事録の問いはSearch1を使う"
  tools:
    - tool_spec:
        type: "cortex_analyst_text_to_sql"
        name: "Analyst1"
    - tool_spec:
        type: "cortex_search"
        name: "Search1"
    - tool_spec:
        type: "data_to_chart"
        name: "data_to_chart"
  tool_resources:
    Analyst1:
      semantic_view: "sales_db.public.sales_sv"
    Search1:
      name: "sales_db.public.docs_search"
      max_results: "5"
  $$;

budget・instructionsによるコスト上限の設定

orchestration.budgetのsecondsとtokensは、体感速度の調整ではなくコストの上限装置として効きます。エージェントの課金は処理トークンに比例し、しかもツールを呼ぶたびに加算されるため、上限を置かない設定では1つの曖昧な質問がツール呼び出しを何往復も誘発します。instructions.orchestrationにどの問いでどのツールを使うかを書いておくと、この往復自体が減ります。実運用では、まずbudgetを絞った状態で典型的な質問をSnowsightのPlaygroundで通し、想定どおりのツールが呼ばれているかを確認してから緩めてください。公式が示す導入手順も、作成→ツール追加→Playgroundでのテスト→アプリ統合→監視の順です。

Cortex Agentsの呼び出し方：REST APIとSQL関数

agent:runの2経路とSQL関数DATA_AGENT_RUN

REST APIには、作成済みのエージェントを実行するエンドポイントと、オブジェクトを作らずに設定をリクエストへ直接書くエンドポイントの2系統があります。

POST /api/v2/databases/{database}/schemas/{schema}/agents/{name}:run
POST /api/v2/cortex/agent:run

ヘッダーはベアラートークンのAuthorizationとContent-Type: application/jsonが必須で、Acceptは任意です（text/event-streamかapplication/json）。ボディには会話履歴のmessages、ツール選択を制御するtool_choice、スレッドを継続するthread_idとparent_message_id（初回は0）を渡します。1リクエストは15分でタイムアウトします。なお、オブジェクト経由の:runではmodels・instructions・orchestrationをリクエストで上書きできません。これらをリクエストごとに変えたい場合はインライン実行の/api/v2/cortex/agent:runを使います。

curl -X POST \
  -H "Authorization: Bearer $SNOWFLAKE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "stream": false,
    "messages": [
      {"role": "user", "content": [{"type": "text", "text": "先月の売上上位3商品は?"}]}
    ]
  }' \
  "https://$ACCOUNT.snowflakecomputing.com/api/v2/databases/sales_db/schemas/public/agents/sales_agent:run"

HTTPを組まずにSQLだけで済ませたい場合は、SQL関数を使います。既存のエージェントオブジェクトを実行するSNOWFLAKE.CORTEX.DATA_AGENT_RUNと、設定を直接渡すSNOWFLAKE.CORTEX.AGENT_RUNの2本です。戻り値はJSON文字列なのでTRY_PARSE_JSONでVARIANTへ変換します。両関数ともリクエストのstreamフィールドは無視され、常に非ストリーミング応答が返る点が公式に明記されています。ストアドプロシージャやタスクからエージェントを呼びたいときは、この経路がいちばん短くなります。ただしSQL関数はRun APIのラッパーであり、公式はアプリケーション統合にはストリーミングのREST APIを直接呼ぶことを推奨しています。SQL関数は定期バッチや検証用と割り切るのが妥当です。

SELECT TRY_PARSE_JSON(
  SNOWFLAKE.CORTEX.DATA_AGENT_RUN(
    'SALES_DB.PUBLIC.SALES_AGENT',
    $${"parent_message_id": 0,
       "messages": [{"role": "user",
       "content": [{"type": "text", "text": "先月の売上上位3商品は?"}]}]}$$
  )
) AS resp;

SSEイベントの読み方とPythonからの呼び出し

RESTのstreamは既定がtrueで、応答はServer-Sent Eventsとして届きます。主なイベントは、テキストのresponse.text.delta、推論過程のresponse.thinking.delta、ツール呼び出しのresponse.tool_useとresponse.tool_result、表のresponse.table、グラフ仕様のresponse.chartで、最後に集約済みのresponseが届きます。エラーはerrorイベントです。イベント種別はこれ以外にもあり、公式は未知のイベント型を受け取っても処理できるように実装することを求めています。

チャットUIを作るのでなければ、stream: falseとAccept: application/jsonでSSEのパース自体を省くほうが実装は単純です。この場合のレスポンスは、ストリーミング時の最終responseイベントと同じ内容の単一JSONになります。バッチ処理や定期レポート生成に組み込むならstream: falseを既定にしてください。

Pythonから使う場合は、Snowflake Python APIのsnowflake.core.cortex.lite_agent_service.CortexAgentServiceが用意されています。run(agent_run_request: AgentRunRequest) -> SSEClientで実行し、非同期版のrun_async()はPollingOperation[SSEClient]を返します（旧Run()は非推奨）。CLIから扱う場合、SnowSQLはレガシー扱いで新機能が追加されないため、新規の連携はSnowflake CLI（snow）を前提に組んでください。

権限設計：CORTEX_AGENT_USERとCREATE AGENT

権限は「エージェントを使う側」と「作る側」で分かれます。使う側のロールにはSNOWFLAKE.CORTEX_USERまたはSNOWFLAKE.CORTEX_AGENT_USERデータベースロールに加え、エージェントオブジェクトと参照先リソースへの権限が要ります。作る側にはスキーマのCREATE AGENT権限が要ります。

-- エージェントを利用するロールへ付与
GRANT DATABASE ROLE SNOWFLAKE.CORTEX_AGENT_USER TO ROLE analyst_role;

-- エージェントを作成するロールへ付与
GRANT CREATE AGENT ON SCHEMA sales_db.public TO ROLE agent_builder;

ここで最も誤解されやすいのが、CORTEX_AGENT_USERを付ければ権限をエージェントだけに絞れる、という思い込みです。SNOWFLAKE.CORTEX_USERは既定でPUBLICロールに付与されており、PUBLICは全ユーザー・全ロールに自動で付きます。つまり何もしなければ、そのロールはCortexのAI機能全体へアクセスできたままです。エージェントだけに限定したいなら、ACCOUNTADMINでCORTEX_USERをREVOKEする必要があります。

-- Cortex全体へのアクセスを外し、エージェント専用にする
REVOKE DATABASE ROLE SNOWFLAKE.CORTEX_USER FROM ROLE PUBLIC;

もう1つ見落としやすいのは、エージェント自体の権限を絞っても参照先データの権限がそのまま効く点です。エージェントは問い合わせたユーザーの既定ロールで動くため、Cortex SearchサービスへのUSAGEも実行ユーザー側のロールに要ります（既定ロールや既定ウェアハウスが未設定のユーザーは、ここで権限エラーになります）。裏を返せば、行アクセスポリシーやマスキングポリシーで守られた列は自然言語経由でも同じように保護される一方、アクセス制御が緩いテーブルをセマンティックビューに載せれば、その緩さがそのまま対話UIに露出します。エージェント導入は権限棚卸しの機会と考えるべきで、Snowflake側のガバナンス機能はSnowflake Horizonとは何か？基本的な概念と利点を紹介にまとめています。

コスト見積もりとCortex Agentsを採用すべきでない場面

AI Creditsによる課金とツールごとの加算

課金の土台はAI Creditsです。公式ドキュメントは「AI CreditsはPlatform Creditsとは別で、Snowflakeのエディションに関係なく一貫した価格を提供する」と述べており、Standard／Enterprise／Business Critical／VPSのいずれでも1クレジットの価格は同じです。On Demandではグローバルルーティングで2.00ドル、リージョナルルーティングで2.20ドルです。ここで注意したいのが、Platform Creditに適用される容量割引はAI Creditsには適用されないと公式が明記している点です。既存のSnowflake契約の割引率をそのまま当てはめて見積もると、AI関連の費用だけが想定を超えます。Cortex Agentsは処理トークン100万あたりのAI Creditsで課金され、モデル別の単価はSnowflake Service Consumption Tableの表6(d)に掲載されています（同じモデルでも、エージェント経由の単価は素の推論より高く設定されています）。

見積もりで外しやすいのは、費用が1か所では発生しないことです。オーケストレーションのトークン課金に加え、Cortex Analystはエージェント経由ではトークン単位で課金され（API直接利用時はメッセージ数ベースで課金体系が異なります）、Cortex Searchはインデックスのサイズと保持時間に加えて埋め込み生成のトークン分がかかり、genericツールとして呼ぶストアドプロシージャはウェアハウス費用がかかります。1回の質問で3つのツールを呼べば、3種類の課金が同時に走ります。

実績値はSNOWFLAKE.ACCOUNT_USAGE.CORTEX_AGENT_USAGE_HISTORYビューでエージェント単位に確認できます。ただしこのビューにはCoWork経由のリクエストは含まれません（そちらはSNOWFLAKE_INTELLIGENCE_USAGE_HISTORYに記録されます）。両方を併用している環境でコストが合わないときは、まずこの分岐を疑ってください。PoCの段階から質問1件あたりの実コストを測っておくべきです。

見送るべき3条件：固定クエリ・SiSウェアハウスランタイム・セマンティックビュー未整備

次のいずれかに当てはまるなら、Cortex Agentsは正しい選択ではありません。

• 問い合わせのパターンが固定されている：毎回同じ集計を返すだけなら、オーケストレーションモデルにツール選択を推論させる意味がなく、トークン課金の分だけ従来のダッシュボードや定型SQLに劣ります。エージェントが効くのは、事前に列挙できない問いが来る場面です。
• Streamlit in Snowflakeのウェアハウスランタイムに載せたい：Cortex Agents APIはウェアハウスランタイムのStreamlit in Snowflakeアプリからはサポートされません。コンテナランタイムへ切り替える必要があるため、既存のSiSアプリに後付けする計画は先に実行環境を確認してください（Streamlit in Snowflakeとは？料金・課金体系と使い方を徹底解説）。
• セマンティックビューが整備されていない：Cortex Analystツールの回答精度はセマンティックビューの定義に依存します。列名の意味や指標の定義が曖昧なままエージェントを載せると、もっともらしく間違った数字が自然言語で返ってくる、最も厄介な失敗をします。データモデル側の整備が先です。

よくある質問

Cortex AgentsとSnowflake CoWork（旧Snowflake Intelligence）は何が違いますか？

CoWorkは、そのまま使える対話型のエージェントアプリケーション（Webアプリ）で、内部でCortex Agent APIを呼び出しています。Cortex Agentsは、そのAPIとAGENTオブジェクトそのものです。自社アプリや業務システムへ組み込むならCortex Agentsを直接、社内利用の対話UIが欲しいだけならCoWorkを選びます。

Cortex Agents用のSDKはありますか？

Pythonについては、Snowflake Python APIにsnowflake.core.cortex.lite_agent_service.CortexAgentServiceがあり、run()にAgentRunRequestを渡してSSEClientを受け取れます。それ以外の言語では、REST API（agent:run）を各言語のHTTPクライアントから呼び出す形になります。SQLだけで完結させたい場合はSNOWFLAKE.CORTEX.DATA_AGENT_RUNを使えます。

SNOWFLAKE.CORTEX_USERとSNOWFLAKE.CORTEX_AGENT_USERはどちらを付与すべきですか？

エージェントの実行にはどちらかがあれば足ります。ただしCORTEX_USERは既定でPUBLICロールへ付与されているため、CORTEX_AGENT_USERを付けるだけでは用途を絞ったことになりません。エージェントだけに限定したいなら、ACCOUNTADMINでCORTEX_USERをREVOKEしてください。いずれの場合も、エージェントオブジェクトと参照先データへの権限は別途必要です。

エージェントのコストはどこで確認できますか？

SNOWFLAKE.ACCOUNT_USAGE.CORTEX_AGENT_USAGE_HISTORYビューでエージェント単位の利用実績を確認できます。CoWork経由の利用はこのビューに含まれずSNOWFLAKE_INTELLIGENCE_USAGE_HISTORYに記録されます。オーケストレーション、Cortex Analyst、Cortex Search、カスタムツールのウェアハウス費用はそれぞれ別に発生するため、合算で見る必要があります。

エージェントの応答は必ずストリーミングで受け取る必要がありますか？

いいえ。REST APIのstreamの既定値はtrueですが、stream: falseとAccept: application/jsonを指定すれば、最終応答と同じ内容を単一のJSONで受け取れます。SQL関数のDATA_AGENT_RUN／AGENT_RUNにいたってはstreamの指定は無視され、常に非ストリーミングで返ります。

関連記事

• Snowflake CoCoとは？旧Cortex Codeからの改称・権限境界・課金の二重経路を実装目線で解説
• Cortex AI（Snowflake）とは？主要機能・導入メリット・読み方を解説
• Snowflake Horizonとは何か？基本的な概念と利点を紹介
• Streamlit in Snowflakeとは？料金・課金体系と使い方を徹底解説
• Snowflakeの新AI機能「AI_EXTRACT」と「AI_PARSE_DOCUMENT」が日本語に対応
• Snowflake Document AIとは何か？その概要と提供される価値