---
title: "Snowflake Cortex Agentsとは？CREATE AGENT・REST API・権限とコストの実装手順【2026年10月】"
url: "https://www.issoh.co.jp/tech/details/9609/"
published: 2025-10-31
updated: 2026-10-31
categories: ["データ分析・BI"]
publisher: "株式会社一創"
---

# Snowflake Cortex Agentsとは？CREATE AGENT・REST API・権限とコストの実装手順【2026年10月】

Snowflake Cortex Agentsは、Snowflakeの権限管理の内側でAIエージェントを動かすマネージド基盤です。エージェントは質問を分解して計画を立て、Cortex AnalystでSQLを生成し、Cortex Searchで文書を探し、必要ならPythonを実行して答えをまとめます。この記事では、2026年10月時点の公式ドキュメントをもとに、CREATE AGENTでの作成からREST APIとSQL関数での呼び出し、権限の絞り込み、東京リージョンで使えるモデル、課金の見積もりまでを実装の順に整理します。

## まとめ

- Cortex Agentsは**スキーマ単位のAGENTオブジェクト**で、モデル・指示・ツールをYAMLの仕様にまとめて `CREATE AGENT ... FROM SPECIFICATION $$ ... $$` で作る。仕様の上限は100,000バイト。
- ツールはCortex Analyst・Cortex Search・Data to Chart・カスタムツール（UDF/ストアドプロシージャ）に加え、**Pythonのコード実行・Agent Skills・MCPコネクタ・ウェブ検索・他エージェントのツール継承**まで広がった。
- 本番運用は**バージョン管理**で分ける。`ALTER AGENT ... COMMIT` で不変の `VERSION$N` を作り、エイリアスや `DEFAULT_VERSION` で呼び出し先を切り替える。
- 呼び出しはREST APIの `agent:run`（既定でSSEストリーミング・同期15分／バックグラウンド6時間）、SQL関数 `SNOWFLAKE.CORTEX.DATA_AGENT_RUN`、Pythonの `CortexAgentService` の3つ。
- `SNOWFLAKE.CORTEX_USER` は既定でPUBLICに付与済み。エージェントだけ使わせたいならREVOKEしてから `CORTEX_AGENT_USER` を付ける。ツールの権限が足りなくても、既定ではランが止まらず警告だけ出る。
- 東京（AWS AP Northeast 1）ではClaude系はクロスリージョン推論経由。課金はAI Credits建てで、オンデマンドは1クレジットあたりGlobal 2.00ドル／Regional 2.20ドル。

以下、仕組み、作成、運用、呼び出し、権限、コストの順に説明します。

## Cortex Agentsの仕組みとCoWork・CoCoとの関係

### 計画・ツール実行・振り返りのループ

[公式ドキュメントの概要ページ](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents)は、エージェントが1回の依頼の中で「計画（Plan）→ツール使用（Use tools）→振り返りと応答（Reflect and respond）」を必要なだけ繰り返すと説明しています。曖昧な質問を言い換えたり、比較の質問を2つの検索に分けたりするのは計画の段階です。ループの実行基盤はSnowflakeが運用します。

ツールを1つも設定しないエージェントも作れますが、その場合はモデルの一般知識だけで答え、アカウント内のデータには一切触れません。会話の文脈は**スレッド**に保存され、クライアントで履歴を持ち回る必要はありません。

### Snowflake CoWork（旧Snowflake Intelligence）・CoCoとの違い

Cortex Agentsは開発者向けのAPIとオブジェクトで、業務ユーザーが触る対話アプリは**Snowflake CoWork**です。CoWorkは2026年6月のSnowflake Summitで旧称Snowflake Intelligenceから改称され、[CoWorkの概要ページ](https://docs.snowflake.com/en/user-guide/snowflake-cortex/snowflake-cowork)にはDeep Research（最大10分の調査モード）、ユーザーメモリ、定期実行のAutomations、iOSアプリが並びます。CoWorkで動いている「エージェント」の実体は、ここで作るAGENTオブジェクトです。ユーザーメモリはCoWork内だけの機能で、APIからの呼び出しには効きません。

開発者向けのコーディングエージェントは別製品で、[Snowflake CoCoとは？旧Cortex Codeからの改称・権限境界・課金の二重経路を実装目線で解説](/tech/details/15982/)で扱っています。Cortex AI全体の機能の地図は[Snowflake Cortex AIとは？読み方・機能一覧・料金と日本リージョンで使えるモデル](/tech/details/5958/)を参照してください。

## Cortex Agentsで使えるツールの種類

仕様の `tools` に `tool_spec` を並べ、`tool_resources` に同じ名前のキーで接続先を書きます。2026年10月時点で公式が挙げるツールは次の通りです。

| ツール               | type                             | 主な接続先・前提                         | 状態             |
| ----------------- | -------------------------------- | -------------------------------- | -------------- |
| Cortex Analyst    | `cortex_analyst_text_to_sql`     | セマンティックビュー＋ウェアハウス                | GA             |
| Cortex Search     | `cortex_search`                  | Cortex Searchサービス                | GA             |
| Data to Chart     | `data_to_chart`                  | なし（他ツールの結果を図にする）                 | GA             |
| カスタムツール           | `generic`                        | UDF・ストアドプロシージャ＋ウェアハウス            | GA             |
| コード実行             | `code_execution`                 | Python 3.12のサンドボックス              | GA             |
| ウェブ検索             | `web_search`                     | アカウント単位での有効化（BraveのWeb検索API）     | GA             |
| Agent Skills      | 仕様の `skills`                     | ステージかGitの `SKILL.md`             | GA             |
| MCPコネクタ           | 外部MCPサーバー                        | API統合（OAuth）＋EXTERNAL MCP SERVER | GA             |
| エージェントのツール継承      | `agent_toolset`                  | 参照先エージェントのUSAGE                  | GA             |
| Analytical search | `capabilities.analytical_search` | Cortex Search＋AI関数＋SQL           | Public Preview |

Cortex Searchの作り方と料金は[Snowflake Cortex Searchとは？作成SQL・検索API・料金とCORTEX\_SEARCH\_BATCHの使い分け](/tech/details/11632/)にまとめています。以下、コード実行・Agent Skills・MCPコネクタ・ツール継承の設定条件を説明します。

### コード実行ツール：Python 3.12のサンドボックス

[コード実行ツール](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-code-execution-tool)は、numpy・pandas・scipy・pyarrow・matplotlib・plotlyを入れたPython 3.12環境でエージェントにコードを書かせて実行します。Snowsightで作った新しいエージェントでは既定でオンです。サンドボックスからテーブルは直接読めず、SQLはエージェントが実行済みのクエリへの `RESULT_SCAN` に限られます。書き込めるのはマウントされたユーザーのワークスペースステージだけで、メモリ上の状態はスレッドをまたいで残りません。状態を変える操作は既定でユーザーの承認を求めます。明示する場合は、対象ツールのリソース設定に `permission_policy: {type: always_ask}` と書きます。オーナー権限で呼ぶエージェントではコード実行は使えません。

### Agent Skills・MCPコネクタ・agent\_toolsetの接続条件

**Agent Skills**は、指示とスクリプトを `SKILL.md` 単位でまとめた手順書です。名前付きステージかGitリポジトリに置き、仕様の `skills` から参照します。`SKILL.md` はフォルダ直下に置く必要があり、Gitのタグで参照したスキルは管理者がFETCHするまで更新されません。`SKILL.md` の書式そのものは[Agent Skillsとは？SKILL.md仕様とAAIF寄贈後も移植性を保つ実装手順](/tech/details/17685/)で説明しています。

**MCPコネクタ**は、Jira・Salesforce・自社アプリなどのリモートMCPサーバーのツールをエージェントから呼ぶ仕組みです。管理者がOAuth情報を持つAPI統合を作り、`CREATE EXTERNAL MCP SERVER` でサーバーオブジェクトを作ってから仕様に追加します。認証はOAuthのみ、使えるのはMCPのtools機能だけで、resourcesやpromptsは対象外です。ホスト名にアンダースコアを含むと接続できないため、ハイフンに置き換えます（[MCPコネクタの公式ページ](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-mcp-connectors)）。

**agent\_toolset**は、別のエージェントのツール構成を実行時に読み込む参照です。展開の既定上限は5階層・1回のランで参照先25エージェントまでで、アカウントパラメータで変更できます。また、呼び出し側のロールが参照先のUSAGEを持たないと、エラーにならず黙って読み飛ばされます。

## CREATE AGENTでエージェントを作成する手順

### 事前に用意する権限とオブジェクト

作成する側のロールには、スキーマの `CREATE AGENT` 権限が要ります。ツールの接続先として、Cortex Analyst用のセマンティックビュー、Cortex Searchサービス、ツールが使うウェアハウスを先に用意します。セッション限りの一時エージェント（`CREATE TEMPORARY AGENT`）なら `CREATE AGENT` 権限は不要で、検証用に向きます。ただし一時エージェントはセッション終了で消え、永続エージェントへ変換できず、バージョン管理も使えません。

### CREATE AGENTのSQLと仕様のYAML

次の例は、売上の質問をCortex Analystに、規程の質問をCortex Searchに振り分けるエージェントです。[CREATE AGENTのリファレンス](https://docs.snowflake.com/en/sql-reference/sql/create-agent)の構文に合わせています。

```
CREATE OR REPLACE AGENT sales_db.agents.sales_assistant
  COMMENT = '売上と社内規程に答えるエージェント'
  PROFILE = '{"display_name": "売上アシスタント", "color": "blue"}'
  FROM SPECIFICATION
  $$
  models:
    orchestration: auto
  orchestration:
    tool_not_accessible: reject
    budget:
      seconds: 60
      tokens: 32000
  instructions:
    orchestration: "売上・数量の質問はSalesAnalystを使う。規程や手順の質問はPolicySearchを使う"
    response: "日本語で簡潔に答え、集計値には対象期間を添える"
    sample_questions:
      - question: "先月の地域別売上を教えて"
  tools:
    - tool_spec:
        type: "cortex_analyst_text_to_sql"
        name: "SalesAnalyst"
        description: "売上テーブルを自然言語からSQLで集計する"
    - tool_spec:
        type: "cortex_search"
        name: "PolicySearch"
        description: "社内規程と業務マニュアルを検索する"
  tool_resources:
    SalesAnalyst:
      semantic_view: "sales_db.semantic.sales_sv"
      execution_environment:
        type: "warehouse"
        warehouse: "AGENT_WH"
    PolicySearch:
      search_service: "sales_db.docs.policy_search"
      max_results: "5"
  $$;
```

`models.orchestration` は公式も `auto` を推奨しています。公式のREST APIページのリクエスト例には `claude-4-sonnet` が残っていますが、このモデルは2026年10月14日にサポート終了しています。例をそのまま写さず、固定したいなら `SHOW CORTEX BASE MODELS IN SCHEMA SNOWFLAKE.MODELS` で現役のモデル名を確かめてから書きます。作成に成功してもツール仕様の正しさは保証されないため、Snowsightのプレイグラウンドで試してから公開します。

### budget・instructions・tool\_not\_accessibleの決め方

`budget` の秒数とトークン数は、どちらかに達した時点で応答の生成を止める上限です。**トークン上限はオーケストレーションの分だけ**で、Cortex AnalystやCortex Searchが使うトークンは含まれません。コストの上限としてはこれだけでは足りないため、後述のリソース予算と組み合わせます。

`tool_not_accessible` は、呼び出し側のロールがツールの権限を持たないときの動きを決めます。省略時の既定は `accept` で、ランは止まらず `response.warning` を出して残りのツールで答えます。便利な反面、売上の集計ツールが黙って外れたまま回答されると、利用者は欠けた理由に気づけません。数字の正確さが重要なエージェントでは、上の例のように `reject` を明示することを勧めます。設定場所は仕様の最上位の `orchestration` で、`models.orchestration` や `instructions.orchestration` ではありません。

## Cortex Agentsのバージョン管理と本番切り替え

[バージョン管理のページ](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-versioning)によると、エージェントを作ると不変の `VERSION$1` と、編集できる `LIVE` 版（Snowsightでは「DRAFT」表示）が同時にできます。開発はLIVE版で行い、リリース時にCOMMITして不変の版を切ります。

```
-- LIVE版を不変の版として確定（VERSION$2 などが採番される）
ALTER AGENT sales_db.agents.sales_assistant COMMIT
  COMMENT = '2026-11 リリース';

-- 確定した版にエイリアスを付け、既定の版にする
ALTER AGENT sales_db.agents.sales_assistant
  MODIFY VERSION VERSION$2 SET ALIAS = production;
ALTER AGENT sales_db.agents.sales_assistant
  SET DEFAULT_VERSION = 'VERSION$2';

-- 開発を再開するときは最新の確定版からLIVE版を作り直す
ALTER AGENT sales_db.agents.sales_assistant ADD LIVE VERSION FROM LAST;

SHOW VERSIONS IN AGENT sales_db.agents.sales_assistant;
```

COMMIT後、LIVE版は自動では作り直されないので、開発を続けるときは `ADD LIVE VERSION FROM LAST` が必要です。ロールバックはエイリアスや `DEFAULT_VERSION` を前の版へ向け直すだけで済みます。確定版は変更できないため、`tool_not_accessible` のような設定を変えるときもLIVE版を直してCOMMITし直します。版を指定しないときに使われる版の説明は、バージョン管理のページ（最新の確定版）とDATA\_AGENT\_RUNのページ（既定を設定していなければLIVE版）で食い違っています。本番では `DEFAULT_VERSION` を明示して曖昧さを残さないのが安全です。

もう1つの落とし穴は `CREATE OR REPLACE AGENT` です。`COPY GRANTS` を付けずに置き換えると、他のロールへ与えていたUSAGEなどの権限が消え、連携中のアプリが急に権限エラーになります。既存のエージェントを置き換えるときは `COPY GRANTS` を付け、終わったら `SHOW GRANTS ON AGENT` で確認します。

## Cortex Agentsを呼び出す3つの経路

### REST APIのagent:runとスレッド

[Cortex Agents Run API](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-run)には、オブジェクトを指定する経路と、仕様をリクエストに直接書く経路があります。

```
# オブジェクトを実行
POST /api/v2/databases/{db}/schemas/{schema}/agents/{name}:run
# 版を指定して実行
POST /api/v2/databases/{db}/schemas/{schema}/agents/{name}/versions/{version}:run
# オブジェクトなしで実行（仕様をリクエストに書く）
POST /api/v2/cortex/agent:run
# バックグラウンド実行への再接続と取り消し
GET  /api/v2/cortex/agent/runs/{run_id}
POST /api/v2/cortex/agent/runs/{run_id}/cancel
```

オブジェクト経由の実行では `models`・`instructions`・`orchestration` をリクエストで上書きできず、変える場合はエージェント自体を更新します。認証はプログラマティックアクセストークン（PAT）、キーペアのJWT、OAuthのいずれかで、権限の判定に使うロールは `X-Snowflake-Role` ヘッダー、省略時はユーザーの既定ロールです。

次の例はスレッドを使う会話です。先にThreads APIでスレッドを作成し、`1234` を返された `thread_id` に置き換えてください。`0` はそのスレッドの最初の発話に対する `parent_message_id` です。

```
curl -X POST "https://<account>.snowflakecomputing.com/api/v2/databases/SALES_DB/schemas/AGENTS/agents/SALES_ASSISTANT:run" \
  -H "Authorization: Bearer $PAT" \
  -H "X-Snowflake-Role: SALES_AGENT_ROLE" \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{
    "thread_id": 1234,
    "parent_message_id": 0,
    "messages": [
      {"role": "user", "content": [{"type": "text", "text": "先月の地域別売上は？"}]}
    ]
  }'
```

同期実行のタイムアウトは15分です。それより長い調査は `"background": true` にすると最大6時間動き、クライアントが切断しても続きます。backgroundはスレッドを使う会話でのみ指定できます。`thread_id` を使うときは `parent_message_id` も必須で、最初の発話では0を渡します。2025年9月1日より前の `agent:run` はリクエストとレスポンスの形が違っていたため、古いブログのコードは今の仕様と合いません。

### SSEイベントの読み方

既定のストリーミングでは、`response.status`（planning などの進行状況）、`response.thinking.delta`（推論のトークン）、`response.text.delta`（回答のトークン）、`response.tool_use` と `response.tool_result`、`response.table`・`response.chart` などが順に届き、最後に全体をまとめた `response` イベントが来ます。逐次表示が不要なら `response` だけを拾えば足ります。公式は「未知のイベント型も扱えるようにすること」と書いており、イベントは今後も増える前提で、知らない型で例外を投げる実装は避けます。

### SQL関数DATA\_AGENT\_RUN

[DATA\_AGENT\_RUN](https://docs.snowflake.com/en/sql-reference/functions/data%5Fagent%5Frun-snowflake-cortex)はRun APIの薄いラッパーで、SSEではなく集約済みのJSON文字列を返します。版は名前の後ろに `!VERSION$2`・`!LAST`・`!LIVE` などを付けて指定できます。

```
SELECT TRY_PARSE_JSON(
  SNOWFLAKE.CORTEX.DATA_AGENT_RUN(
    'SALES_DB.AGENTS.SALES_ASSISTANT!VERSION$2',
    $${
      "messages": [
        {"role": "user", "content": [{"type": "text", "text": "先月の地域別売上は？"}]}
      ]
    }$$
  )
) AS resp;
```

戻り値は文字列なので `TRY_PARSE_JSON` でVARIANTに変換して扱います。権限の足りないツールがあった場合は、最上位の `warnings` 配列に入るので、利用者に見せるかどうかを決めておきます。第3引数に `TRUE` を渡すとスレッドを自動作成し、返ってきた `thread_id` で会話を続けられます。公式はアプリへの組み込みにはストリーミングのREST APIを推奨しており、SQL関数はタスクでの定期実行やワークシートでの確認に向きます。

### PythonのCortexAgentServiceによる実行と対応範囲

Pythonでは `snowflake-core`（1.14.0・2026年10月22日公開・Python 3.11以上）の `CortexAgentService` が使えます。中身はオブジェクトなしの `/api/v2/cortex/agent:run` を呼ぶクライアントで、AGENTオブジェクトを作成・更新するクラス（`snowflake.core.agent`）はこの版にもありません。オブジェクトの管理はSQLかREST APIで行います。

`connection_parameters` には、利用環境の認証方式に合わせたSnowpark Session用の接続設定を事前に定義しておきます（例では省略しています）。

```
from snowflake.core import Root
from snowflake.core.cortex.lite_agent_service import AgentRunRequest
from snowflake.snowpark import Session

session = Session.builder.configs(connection_parameters).create()
root = Root(session)

req = AgentRunRequest.from_dict({
    "messages": [{"role": "user", "content": [{"type": "text", "text": "先月の地域別売上は？"}]}],
    "models": {"orchestration": "auto"},
    "tools": [{"tool_spec": {"type": "cortex_analyst_text_to_sql", "name": "sales"}}],
    "tool_resources": {"sales": {
        "semantic_view": "SALES_DB.SEMANTIC.SALES_SV",
        "execution_environment": {"type": "warehouse", "warehouse": "AGENT_WH"},
    }},
})

for event in root.cortex_agent_service.run(req).events():
    if event.event == "response.text.delta":
        print(event.data)
```

上の `AgentRunRequest.from_dict` は snowflake-core 1.14.0でリクエストオブジェクトの生成を確認しています。Snowflakeへの実通信と回答取得は、この確認には含みません。旧メソッドの `Run()` は非推奨で、`run()` と `run_async()` を使います。なお、Streamlit in Snowflakeのウェアハウスランタイムからは Cortex Agents API を呼べず、コンテナランタイムが必要です。ランタイムごとの費用は[Streamlit in Snowflakeの料金・課金体系｜ウェアハウスとコンテナランタイムの費用と使い方](/tech/details/5956/)で比べています。

## CORTEX\_USERとCORTEX\_AGENT\_USERの権限設計

エージェントを呼ぶロールには、`SNOWFLAKE.CORTEX_USER`（AI機能全般）か `SNOWFLAKE.CORTEX_AGENT_USER`（Cortex Agentsだけ）のどちらかのデータベースロールが必要です。[アクセス制御のページ](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-setup)の通り、**CORTEX\_USERは既定でPUBLICロールに付与されている**ため、CORTEX\_AGENT\_USERを付けただけでは対象を絞ったことになりません。

```
USE ROLE ACCOUNTADMIN;

-- 全ユーザーに開いているAI機能の利用権を閉じる
REVOKE DATABASE ROLE SNOWFLAKE.CORTEX_USER FROM ROLE PUBLIC;

-- エージェント専用のロールを作って付与する
CREATE ROLE sales_agent_role;
GRANT DATABASE ROLE SNOWFLAKE.CORTEX_AGENT_USER TO ROLE sales_agent_role;
GRANT USAGE ON DATABASE sales_db TO ROLE sales_agent_role;
GRANT USAGE ON SCHEMA sales_db.agents TO ROLE sales_agent_role;

-- ツールの接続先（セマンティックビューは基表のSELECTが不要）
GRANT USAGE ON SCHEMA sales_db.semantic TO ROLE sales_agent_role;
GRANT SELECT ON SEMANTIC VIEW sales_db.semantic.sales_sv TO ROLE sales_agent_role;
GRANT USAGE ON SCHEMA sales_db.docs TO ROLE sales_agent_role;
GRANT USAGE ON CORTEX SEARCH SERVICE sales_db.docs.policy_search TO ROLE sales_agent_role;
GRANT USAGE ON AGENT sales_db.agents.sales_assistant TO ROLE sales_agent_role;
GRANT USAGE ON WAREHOUSE agent_wh TO ROLE sales_agent_role;
GRANT ROLE sales_agent_role TO USER example_user;
```

ツールへのアクセスは**呼び出し元の有効なロール**で判定されます。ただし、ストアドプロシージャ内部の処理は、そのプロシージャに設定された所有者権限または呼び出し元権限で実行されます。エージェントのUSAGEだけでは足りず、セマンティックビュー自体のSELECT、Cortex SearchサービスのUSAGE、カスタムツールの関数やプロシージャのUSAGEも同じロールに要ります。管理側の権限は、更新と削除がMODIFY、スレッド・ログ・トレースの閲覧がMONITORです。

仕様に書いた指示（YAML）を利用者に見せたくない場合は、`CREATE SECURE AGENT` でセキュアエージェントにします。USAGEやMODIFYしか持たないロールからは、DESCRIBEやGET\_DDLで仕様が見えなくなります。ただし公式は「認可はエージェントの指示文ではなくSnowflakeのアクセス制御で強制すること」と明記しています。「この部署には売上を答えない」といった制限を指示文に書いて済ませるのは誤りで、ロールの権限で切ります。

## 東京リージョンで使えるモデルとクロスリージョン推論

[モデルの提供状況ページ](https://docs.snowflake.com/en/user-guide/snowflake-cortex/model-availability)の地域表を見ると、AWS AP Northeast 1（東京）でネイティブに動くのはllama3.1-8bなどごく一部で、ClaudeやGPTは載っていません。東京のアカウントでCortex Agentsを本格的に使うには、クロスリージョン推論が前提です。AWS JPのクロスリージョン枠で、Cortex Agents向けにGAとされているモデルが使えるのは2026年10月時点でclaude-sonnet-4-6・claude-sonnet-4-5・claude-haiku-4-5の3つです。claude-sonnet-5はAWS APJ以上の枠が必要です。

```
-- 今の設定値を確認する（value列が実際に効いている値）
SHOW PARAMETERS LIKE 'CORTEX_ENABLED_CROSS_REGION' IN ACCOUNT;

-- 日本国内の処理に限る場合
ALTER ACCOUNT SET CORTEX_ENABLED_CROSS_REGION = 'AWS_JP';
```

既定値はアカウントの作成時期や業種区分で異なります。2026年3月9日以降に新しい組織で作った商用アカウントは `ANY_REGION` です。データの所在に要件があるなら明示的に設定します。クロスリージョンでも処理先にデータは保存されず、課金は自アカウントのリージョンで、データ転送料はかかりません。リージョン別の詳細は[Cortex AIのハブ記事](/tech/details/5958/)の日本リージョンの章にまとめています。

## Cortex Agentsのコスト見積もりと上限設定

### 課金の構成とトークン単価

Cortex Agentsの費用は、オーケストレーションのトークン、Cortex Analystのトークン、Cortex Searchのインデックス保持料、カスタムツールやSQL実行のウェアハウス料金の合計です。コード実行・ウェブ検索・MCPコネクタ・Skillsも追加費用になり得ます。[Snowflake Service Consumption Table](https://www.snowflake.com/legal-files/CreditConsumptionTable.pdf)（2026年10月29日発効版）のTable 6(d)は、CoWork・Cortex Agents・それらを経由したCortex Analystのトークン単価をAI Credits（100万トークンあたり）で定めています。

| モデル               | 入力   | 出力    | キャッシュ読み出し |
| ----------------- | ---- | ----- | --------- |
| claude-haiku-4-5  | 0.65 | 3.25  | 0.06      |
| claude-sonnet-4-6 | 1.95 | 9.76  | 0.20      |
| claude-sonnet-5   | 1.30 | 6.50  | 0.13      |
| claude-opus-5-5   | 2.60 | 13.00 | 0.13      |
| openai-gpt-5.4    | 1.63 | 9.76  | 0.16      |

AI Creditsの単価は、オンデマンドでGlobal 2.00ドル／Regional 2.20ドルです。容量契約では年間契約額の帯ごとにGlobal 1.88〜2.00ドルまで下がりますが、Platform Creditsの割引率とは別建てです。`AWS_JP` のような地域指定はRegional側の単価になります。試算すると、claude-sonnet-4-6で入力2万・出力2千トークンのオーケストレーションは0.039＋0.0195＝約0.059 AI Credits、Regional単価で約0.13ドルです。ここにAnalystのトークンとウェアハウスの秒課金が乗るため、1回あたりの総額は仕様と質問の重さで大きく変わります。必ず下の利用履歴で実測してください。

### 利用履歴ビュー：CORTEX\_AGENT\_USAGE\_HISTORY

```
SELECT agent_name,
       user_name,
       COUNT(*)           AS runs,
       SUM(tokens)        AS tokens,
       SUM(token_credits) AS ai_credits
FROM SNOWFLAKE.ACCOUNT_USAGE.CORTEX_AGENT_USAGE_HISTORY
WHERE start_time >= DATEADD(day, -30, CURRENT_TIMESTAMP())
GROUP BY agent_name, user_name
ORDER BY ai_credits DESC;
```

[CORTEX\_AGENT\_USAGE\_HISTORY](https://docs.snowflake.com/en/sql-reference/account-usage/cortex%5Fagent%5Fusage%5Fhistory)は1行が1回の呼び出しで、ツール別の内訳は `TOKENS_GRANULAR`・`CREDITS_GRANULAR` に入ります。反映の遅れは最大1時間で、`METADATA` のSQL実行分のクレジットはさらに最大8時間遅れます。**CoWork経由の利用はこのビューに入らず**、`SNOWFLAKE_COWORK_USAGE_HISTORY` に記録されます。CoWorkで配ったエージェントの費用が合わないときは、まずビューの取り違えを疑います。

### 使いすぎを抑える3つの上限設定

- **budget（エージェント仕様）**：1回のランの秒数とオーケストレーションのトークンを制限する。ツール側のトークンは対象外。
- **リソース予算**：エージェントにタグを付けて予算と紐づけ、月間の閾値超過時に、あらかじめ登録したストアドプロシージャでアクセスを取り消すなどの処理を行う。反映には通常最大8時間、低遅延設定でも最大2時間かかり、その間は超過利用が生じ得る（[Resource budgets for Cortex Agents](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-resource-budgets)）。
- **ユーザー別クォータ**：ユーザーごとのクレジット上限を設け、ブロックを有効化すると、上限到達後に対応するAI機能への要求を拒否できる。判定には数分の遅延があり、上限を超過する場合がある。ウェアハウスの利用自体は停止対象外。

## Cortex Agentsを採用すべきでない場面

次の条件に当てはまるなら、より単純な仕組みで済ませた方が速く安く済みます。

- **質問の型が決まっている**：同じ集計を出すだけならダッシュボードかビューで足りる。エージェントは計画のたびにトークンを使い、経路も毎回同じとは限らない。
- **セマンティックビューが整っていない**：Analystの回答精度を評価する前に、セマンティックビューの列の意味・指標・結合条件を整える必要がある。列の意味や指標の定義が曖昧なままでは、意図と異なる集計SQLを生成するおそれがある。代表的な質問と期待する集計結果を用意し、一致を確認してから公開する。
- **国内処理が必須で、AWS JP枠の対応モデルでは要件を満たせない**：東京ではClaudeやGPTはクロスリージョン推論が前提になる。国外処理を認めない規程なら、Cortex Agents向けGAはclaude-sonnet-4-6・claude-sonnet-4-5・claude-haiku-4-5の3つに限られるため、この3モデルで精度と費用が足りるかを先に検証する。
- **Streamlit in Snowflakeのウェアハウスランタイムから呼びたい**：対応していないため、コンテナランタイムへの移行か外部アプリからのREST呼び出しが必要になる。

逆に、構造化データの集計と文書の検索を1つの質問の中で組み合わせる必要があり、Snowflake内で完結するツール構成を選べる場合は、オーケストレーション基盤の運用をSnowflakeに任せられます。ウェブ検索や外部MCPコネクタを使う場合は外部サービスへの通信が発生するため、送信するデータを別途確認する必要があります。業務への組み込み方から相談したい場合は、[AIエージェント開発の支援内容](/service/ai/agent/)も参考にしてください。

## よくある質問

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

Cortex AgentsはAGENTオブジェクトとAPIで、CoWorkはそのエージェントを業務ユーザーが使うための対話アプリです。CoWorkで選ぶエージェントの実体はCREATE AGENTで作ったオブジェクトです。利用履歴もCORTEX\_AGENT\_USAGE\_HISTORYとSNOWFLAKE\_COWORK\_USAGE\_HISTORYに分かれます。

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

Pythonではsnowflake-coreの `CortexAgentService` がagent:runを呼べます（1.14.0で確認）。エージェントオブジェクトの作成・更新はSDKのクラスが無いため、CREATE AGENTなどのSQLか、`/api/v2/databases/{db}/schemas/{schema}/agents` のREST APIを使います。

### CORTEX\_USERとCORTEX\_AGENT\_USERはどちらを付与すべきですか？

エージェントだけを使わせるならCORTEX\_AGENT\_USERです。ただしCORTEX\_USERは既定でPUBLICに付与されているため、ACCOUNTADMINでPUBLICからREVOKEしない限り、全ユーザーがAI機能全般を使える状態のままです。データベースロールはユーザーへ直接付与できないので、カスタムロール経由で渡します。

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

SNOWFLAKE.ACCOUNT\_USAGE.CORTEX\_AGENT\_USAGE\_HISTORYのTOKEN\_CREDITSで確認します。反映は最大1時間遅れ、CoWork経由の利用はSNOWFLAKE\_COWORK\_USAGE\_HISTORY側に入ります。単価はService Consumption TableのTable 6(d)で、モデルごとに入力と出力で異なります。

### 15分を超える長い処理はどう実行しますか？

リクエストに `"background": true` を指定すると、最大6時間のバックグラウンド実行になります。スレッドを使う会話でのみ指定でき、結果は `run_id` でStream Agent Runのエンドポイントから受け取るか、SQLではTHREAD\_MESSAGES関数で取得します。

## 関連記事

- [Snowflake Cortex AIとは？読み方・機能一覧・料金と日本リージョンで使えるモデル](/tech/details/5958/)
- [Snowflake Cortex Searchとは？作成SQL・検索API・料金とCORTEX\_SEARCH\_BATCHの使い分け](/tech/details/11632/)
- [Snowflake CoCoとは？旧Cortex Codeからの改称・権限境界・課金の二重経路を実装目線で解説](/tech/details/15982/)
- [Streamlit in Snowflakeの料金・課金体系｜ウェアハウスとコンテナランタイムの費用と使い方](/tech/details/5956/)
- [Snowflake Summit 2025の発表まとめ｜Openflow・Gen2・Intelligenceの現在の提供状況](/tech/details/7341/)

---

出典: [Snowflake Cortex Agentsとは？CREATE AGENT・REST API・権限とコストの実装手順【2026年10月】](<https://www.issoh.co.jp/tech/details/9609/>)（株式会社一創）