Cortex Agents REST API¶

対話型チャットアプリケーションの作成を簡素化するには、この API を使用します。

実行エージェント¶

POST <アカウントURL>/api/v2/cortex/agent:run

リクエスト本文でプロバイダーが提供するCortex Agentサービスにユーザークエリを送信し、その応答を返します。

リクエスト¶

パスパラメーター¶

パラメーター	説明
`account_url`	(必須) お客様の Snowflake アカウント URL。アカウント URL の見つけ方については、アカウントの組織名とアカウント名の検索を参照してください。

リクエストヘッダー¶

ヘッダー	説明
`Authorization`	（必須）認証トークン詳細については、 REST API 認証の構成をご参照ください。
`Content-Type`	（必須）application/json

リクエスト本文¶

リクエスト本文は、モデル、応答命令、実験フィールド、ツール、ツールリソース、メッセージを含みます。

フィールド	型	説明
`model`	string	Agent が応答を生成するために使用するモデルの名前。対応モデルのリストについては、対応モデルを参照してください。
`response_instruction`	string	モデルが応答を生成する際に従う指示。
`experimental`	object	エージェントに渡される実験フラグ。
`tools`	array	Agent が利用可能なツール仕様の配列。
`tool_resources`	object	ツールに必要なリソース。
`tool_choice`	object	ツールの選択に使用される構成。
`messages`	array	会話中のメッセージの配列。

応答指示¶

response_instruction フィールドは、モデルに対してレスポンス生成の指示を与える文字列です。

ツール構成¶

このセクションでは、サポートされているツールのタイプ、構成オプション、各ツールに必要なリソースの指定方法について詳しく説明します。

ツール仕様¶

tools フィールドには、利用可能なツールが配列されています：

フィールド	型	説明
`tool_spec.type`	string	ツールのタイプ。タイプと名前の組み合わせは、一意の識別子です。
`tool_spec.name`	string	ツールの名前。タイプと名前の組み合わせは、一意の識別子です。

サポートされている tool_spec.type の値は以下の通りです。

cortex_search: Cortexの検索関数に使用。
cortex_analyst_text_to_sql: Cortex Analystの SQL テキストに使用します。
sql_exec: SQL クエリの実行に使用。SQL クエリを実行し、結果をツールの結果として提供する責任があります。詳しくは、下記の回答サンプルリクエストを参照してください。
data_to_chart: チャートの生成に使用

ツールリソース¶

tool_resources オブジェクトは、各ツールの構成オブジェクトを提供します。

tool_resources: {
    "toolName1": {configuration object for toolName1},
    "toolName2": {configuration object for toolName2},
    // ...
}

Copy

各ツールタイプの構成は以下の通りです。

cortex_search

SearchName オブジェクトにはCortex Searchツールの構成が含まれています。

"SearchName": {
    // Required: The Snowflake search service identifier
    "name": "database.schema.service_name",
    // Optional: Number of search results to include
    "max_results": 5,
    // Optional: Column to use as document title
    "title_column": "title",
    // Optional: Column to use as document identifier
    "id_column": "id",
     // Optional: Filters to apply to search results (such as @eq for equality)
    "filter": {
      "@eq": {"<column>": "<value>"}
    }
}

Copy

cortex_analyst_text_to_sql

AnalystName オブジェクトには、Cortex Analyst text-to-SQL ツールの構成が含まれています。構成には、使用するセマンティックモデルまたは表示を含める必要があります。例:

"AnalystName": {
    // Stage path to semantic model file in `semantic_model_file`
    "semantic_model_file": "@database.schema.stage/my_semantic_model.yaml"
}

Copy

セマンティックビューの概要を使用するか

"AnalystName": {
    // Fully qualified name of the semantic view object
    "semantic_view": "@database.schema.semantic_view"
}

Copy

ツール選択¶

tool_choice フィールドはツール選択の動作を構成します。

フィールド	型	説明
`type`	string	ツールの選び方。有効な値: `"auto"` ` (デフォルト) `"required"` (少なくとも1つのツールを使用)。 `"tool"` (指定のツールを使用)
`name`	array	使用するツール名の配列 (オプション)。 `type = "tool"` の場合のみ有効です。

フィールド

型

説明

type

string

ツールの選び方。

有効な値:

"auto" ` (デフォルト)
"required" (少なくとも1つのツールを使用)。
"tool" (指定のツールを使用)

name

array

使用するツール名の配列 (オプション)。 type = "tool" の場合のみ有効です。

メッセージ¶

messages 配列はユーザーとアシスタントの会話履歴を含みます。

フィールド	型	説明
`messages[].role`	string	メッセージ送信者のロール。有効な値: `"system"` `"user"` `"assistant"`
`messages[].content`	array	メッセージを構成するコンテンツ要素の配列。

フィールド

型

説明

messages[].role

string

メッセージ送信者のロール。

有効な値:

"system"
"user"
"assistant"

messages[].content

array

メッセージを構成するコンテンツ要素の配列。

メッセージの内容構成¶

各メッセージの content 配列には、タイプの異なる複数のコンテント・エレメントを含めることができます。

フィールド	型	説明
`messages[].content[].type`	string	コンテンツのタイプ。有効な値: `"text"` `"chart"` `"table"` `"tool_use"` `"tool_results"`

フィールド

型

説明

messages[].content[].type

string

コンテンツのタイプ。

有効な値:

"text"
"chart"
"table"
"tool_use"
"tool_results"

テキストコンテンツ

type が "text" の場合：

フィールド	型	説明
`messages[].content[].text`	string	メッセージのテキスト内容。

例:

{
  "type": "text",
  "text": "Show me sales by region for Q1 2024"
}

Copy

チャートコンテンツ

type が「チャート」の場合：

フィールド	型	説明
`messages[].content[].chart`	object	メッセージのチャート内容。
`messages[].content[].chart.chart_spec`	string	Vega-Lite仕様のチャート。

例:

{
  "type": "chart",
  "chart": {
    "chart_spec": "{\"$schema\":\"https://vega.github.io/schema/vega-lite/v5.json\",\"data\":{\"values\":[{\"REGION\":\"NORTH_AMERICA\",\"SUM(SALES)\":\"2000.00\"},{\"REGION\":\"EUROPE\",\"SUM(SALES)\":\"1700.00\"},{\"REGION\":\"SAUTH_AMERICA\",\"SUM(SALES)\":\"1500.00\"}]},\"encoding\":{\"x\":{\"field\":\"REGION\",\"sort\":null,\"type\":\"nominal\"},\"y\":{\"field\":\"SUM(SALES)\",\"sort\":null,\"type\":\"quantitative\"}},\"mark\":\"bar\"}",
  }
}

Copy

テーブルの内容

type が「テーブル」の場合：

フィールド	型	説明
`messages[].content[].table`	object	メッセージのテーブルの内容。
`messages[].content[].table.query_id`	string	実行されたクエリの ID 。

例:

{
  "type": "table",
  "table": {
    "query_id": "01bbff92-0304-c8c7-0022-b7869a076c22"
  }
}

Copy

ツール使用

type が「tool_use」の場合：

フィールド	型	説明
`messages[].content[].tool_use`	object	ツール用コンテナーリクエスト詳細。
`messages[].content[].tool_use.tool_use_id`	string	このツール使用リクエストの一意識別子。
`messages[].content[].tool_use.name`	string	実行するツール名。ツール配列のツール名と一致する必要があります。
`messages[].content[].tool_use.input`	object	ツール実行時の入力パラメーター。

例:

{
  "type": "tool_use",
  "tool_use": {
    "tool_use_id": "tu_01",
    "name": "Analyst1",
    "input": {
      "query": "Show me sales by region for Q1 2024"
    }
  }
}

Copy

ツール結果

type が "tool_results" の場合：

フィールド

型

説明

messages[].content[].tool_results

object

ツールの実行結果とメタデータのコンテナー。

messages[].content[].tool_results.tool_use_id

string

これらの結果を生成した tool_use_id をリファレンスします。

messages[].content[].tool_results.name

string

実行されたツール名。ツール配列のツール名と一致する必要があります。

messages[].content[].tool_results.status

string

ツールの実行ステータス。

有効な値:

"success"
"error"

messages[].content[].tool_results.content

array

ツール実行によって生成されるコンテンツ要素の配列。

以下のタイプの要素を含むことができます：

型	フィールド	説明
`text`	`type: "text"` `text: string`	ツールが返すプレーンテキストの内容。
`json`	`type: "json"` `json: object`	ツールから返される構造化された JSON データ。

例:

{
  "type": "tool_results",
  "tool_results": {
    "tool_use_id": "tu_01",
    "status": "success",
    "content": [
      {
        "type": "json",
        "json": {
          "sql": "SELECT region, SUM(sales) FROM sales_data WHERE quarter='Q1' AND year=2024 GROUP BY region"
          "text": "This is our interpretation of your question: Show me sales by region for Q1 2024. We have generated the following SQL query for you: SELECT region, SUM(sales) FROM sales_data WHERE quarter='Q1' AND year=2024 GROUP BY region"
        }
      }
    ]
  }
}

Copy

完了メッセージの例¶

この例では、ユーザーのクエリ (role is user) とレスポンス (role is assistant) を含む完全なメッセージを示しています。応答には、 Analyst1 というツールのツール使用イベントと、同じツールのツール結果イベントが含まれます。

{
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "Show me sales by region for Q1 2024"
        }
      ]
    },
    {
      "role": "assistant",
      "content": [
        {
          "type": "tool_use",
          "tool_use": {
            "tool_use_id": "tu_01",
            "name": "Analyst1",
            "input": {
              "query": "Show me sales by region for Q1 2024"
            }
          }
        },
        {
          "type": "tool_results",
          "tool_results": {
            "tool_use_id": "tu_01",
            "name": "Analyst1",
            "status": "success",
            "content": [
              {
                "type": "json",
                "json": {
                  "sql": "SELECT region, SUM(sales) FROM sales_data WHERE quarter='Q1' AND year=2024 GROUP BY region"
                  "text": "This is our interpretation of your question: Show me sales by region for Q1 2024. We have generated the following SQL query for you: SELECT region, SUM(sales) FROM sales_data WHERE quarter='Q1' AND year=2024 GROUP BY region"
                }
              }
            ]
          }
        }
      ]
    }
  ]
}

Copy

応答¶

ストリームでは、各イベントはServer-Sent Events (SSE) 形式で届き、主なパターンは以下の通りです。

出力のチャンクに対する増分 message.delta イベント
何か問題が発生した場合の error イベント。

`message.delta` イベント¶

フィールド	型	説明
`event`	string	部分的なメッセージデータの場合の `message.delta`。
`data`	object	インクリメンタルアップデートデータを含みます。
`data.id`	string	メッセージの一意識別子。
`data.object`	string	`message.delta` または同様の記述子。
`data.delta.content`	array	チャンクまたは部分的なメッセージセグメントのリスト。
`data.delta.content[].index`	integer	現在のメッセージ内でのこのチャンクの位置。
`data.delta.content[].type`	string	コンテンツのタイプ有効な値: `"text"` `"chart"` `"table"` `"tool_use"` `"tool_results"`
`data.delta.content[].text`	string	`type = "text"` の場合、部分文字列。
`data.delta.content[].chart`	object	`type = "chart"` の場合、メッセージのチャート内容。
`data.delta.content[].chart.chart_spec`	string	Vega-Lite仕様のチャート。
`data.delta.content[].table`	object	`type = "table"` の場合、メッセージのテーブルの内容。
`data.delta.content[].table.query_id`	string	実行されたクエリの ID 。
`data.delta.content[].tool_use`	object	`type = "tool_use"` の場合、ツール呼び出し中であることを示します。tool_use_id, name, inputを含みます。
`data.delta.content[].tool_use.tool_use_id`	string	ツールコールの一意識別子。
`data.delta.content[].tool_use.name`	string	呼び出されるツールの名前。
`data.delta.content[].tool_use.input`	object	ツールの JSON ペイロード。
`data.delta.content[].tool_results`	object	`type = "tool_results"` の場合、ツール出力が含まれます。
`data.delta.content[].tool_results.tool_use_id`	string	ツール出力の一意識別子。
`data.delta.content[].tool_results.status`	string	ツールの実行ステータス。有効な値: `"success"` `"error"`
`data.delta.content[].tool_results.content`	array	ツールの返送データを説明する項目のリスト。
`data.delta.content[].tool_results.content[].type`	string	ツールが返すコンテンツのタイプ。有効な値: `"text/csv"` `"application/json"` `"application/pdf"`
`data.delta.content[].tool_results.content[].json`	object	`type = "application/json"` の場合、ツールから返される JSON データ。
`data.delta.content[].tool_results.content[].text`	string	`type = "text"` の場合、ツールが返すテキストデータ。

`error` イベント¶

フィールド	型	説明
`event`	string	エラーイベント用 `error`。
`data`	object	エラーの詳細を含みます。
`data.code`	string	Snowflakeエラーコード。例えば、 `"399505"` です。
`data.message`	string	何が悪かったのかの説明。例えば、 `"Internal server error"` です。

会話の流れのサンプル¶

このセクションでは、Cortex Agent REST API を使った、ユーザーとアシスタントの会話フローのサンプルを示します。

サンプルリクエスト¶

{
  "model": "llama3.3-70b",
  "response_instruction": "You will always maintain a friendly tone and provide concise response.",
  "experimental": {},
  "tools": [
    {
      "tool_spec": {
        "type": "cortex_analyst_text_to_sql",
        "name": "Analyst1"
      }
    },
    {
      "tool_spec": {
        "type": "cortex_analyst_text_to_sql",
        "name": "Analyst2"
      }
    },
    {
      "tool_spec": {
        "type": "sql_exec",
        "name": "sql_execution_tool"
      }
    },
    {
      "tool_spec": {
        "type": "data_to_chart",
        "name": "data_to_chart"
      }
    },
    {
      "tool_spec": {
        "type": "cortex_search",
        "name": "Search1"
      }
    }
  ],
  "tool_resources": {
    "Analyst1": { "semantic_model_file": "stage1"},
    "Analyst2": { "semantic_model_file": "stage2"},
    "Search1": {
      "name": "db.schema.service_name",
      "filter": {"@eq": {"region": "North America"} }
    }
  },
  "tool_choice": {
    "type": "auto"
  },
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "What are the top three customers by revenue?"
        }
      ]
    }
  ]
}

Copy

サンプル応答¶

{
  "id": "msg_001",
  "object": "message.delta",
  "delta": {
    "content": [
      {
        "index": 0,
        "type": "tool_use",
        "tool_use": {
          "tool_use_id": "toolu_XXXXXX",
          "name": "analyst1",
          "input": {
            "messages": [
              "role:USER content:{text:{text:\"What are the top three customers by revenue?\"}}"
            ],
            "model": "snowflake-hosted-semantic",
            "experimental": ""
          }
        }
      },
      {
        "index": 0,
        "type": "tool_results",
        "tool_results": {
          "tool_use_id": "toolu_XXXXXX",
          "content": [
            {
              "type": "json",
              "json": {
                "suggestions": [],
                "sql": "WITH __customers AS (\n  SELECT\n    customer_id,\n    revenue\n  FROM user_database.user_schema.user_table\n)\nSELECT\n  customer_id, revenue FROM __customers ORDER BY revenue DESC LIMIT 3\n -- Generated by Cortex Analyst\n;",
                "text": "This is our interpretation of your question:\n\n__What are the top three customers by revenue?\n\n"
              }
            }
          ],
          "status": "success"
        }
      },
        {
          "type": "tool_use",
          "tool_use": {
            "tool_use_id": "tool_002",
            "name": "sql_execution_tool",
            "input": {
              "sql": "WITH __customers AS (SELECT customer_id, revenue FROM user_database.user_schema.user_table) SELECT customer_id, revenue FROM __customers ORDER BY revenue DESC LIMIT 3"
            }
          }
        }
    ]
  }
}

Copy

サンプル回答リクエスト¶

Cortex Agentは、実行された SQL クエリに基づいて、テキストや図表による回答を生成できます。次の例は、Cortex Agent API を使用して、そのような回答を生成する方法を示しています。

答えを得るために、クライアントはCortex Agent API に、クライアント側で実行された SQL の query_id でフォローアップリクエストを行います。実行される SQL は、最新の応答メッセージの sql_exec ツールタイプの tool_use イベントでプロバイダーされます。

リクエストは、 cortex_analyst_text_to_sql および sql_exec ツールを使用してテキストによる回答を得る必要があり、さらに data_to_chart ツールを使用してチャートによる回答を得る必要があります。チャートは、エージェントがチャートが答えを提示する良い方法であると判断した場合にのみ返されます。

注釈

4000 セルを超える結果セットでは、 text および chart の回答の代わりに table の回答が返されます。

{
  "model": "llama3.3-70b",
  "response_instruction": "You will always maintain a friendly tone and provide concise response.",
  "experimental": {},
  "tools": [
    {
      "tool_spec": {
        "type": "cortex_analyst_text_to_sql",
        "name": "Analyst1"
      }
    },
    {
      "tool_spec": {
        "type": "cortex_analyst_text_to_sql",
        "name": "Analyst2"
      }
    },
    {
      "tool_spec": {
        "type": "sql_exec",
        "name": "sql_execution_tool"
      }
    },
    {
      "tool_spec": {
        "type": "data_to_chart",
        "name": "data_to_chart"
      }
    },
    {
      "tool_spec": {
        "type": "cortex_search",
        "name": "Search1"
      }
    }
  ],
  "tool_resources": {
    "Analyst1": { "semantic_model_file": "stage1"},
    "Analyst2": { "semantic_model_file": "stage2"},
    "Search1": {
      "name": "db.schema.service_name",
      "filter": {"@eq": {"region": "North America"} }
    }
  },
  "tool_choice": {
    "type": "auto"
  },
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "What are the top three customers by revenue?"
        }
      ]
    },
    {
      "role": "assistant",
      "content": [
        {
          "type": "tool_use",
          "tool_use": {
            "tool_use_id": "tool_001",
            "name": "Analyst1",
            "input": {
              "messages": [
                "role:USER content:{text:{text:\"What are the top three customers by revenue?\"}}"
              ],
              "model": "snowflake-hosted-semantic",
            }
          }
        },
        {
          "type": "tool_results",
          "tool_results": {
            "status": "success",
            "tool_use_id": "tool_001",
            "content": [
              {
                "type": "json",
                "json": {
                  "sql": "select * from table",
                  "text": "This is our interpretation of your question: What are the top three customers by revenue? \n\n"
                }
              }
            ]
          }
        }
      ]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "tool_results",
          "tool_results": {
            "tool_use_id": "tool_002",
            "result": {
              "query_id": "01bbff92-0304-c8c7-0022-b7869a076c22"
            }
          }
        }
      ]
    }
  ]
}

Copy

回答サンプル¶

{
  "id": "msg_001",
  "object": "message.delta",
  "delta": {
    "content": [
      {
        "index": 0,
        "type": "text",
        "text": "This is a textual answer to your question"
      },
      {
        "index": 0,
        "type": "chart",
        "chart": {
          "chart_spec": "{\"$schema\": \"https://vega.github.io/schema/vega-lite/v5.json\", \"title\": \"Example chart\", \"mark\": \"bar\", \"encoding\": {\"x\": {\"field\": \"column_x\", \"type\": \"nominal\", \"sort\": null}, \"y\": {\"field\": \"column_y\", \"type\": \"quantitative\"}}, \"data\": {\"values\": [{\"column_x\": \"A\", \"column_y\": \"1\"}, {\"column_x\": \"A\", \"column_y\": \"1\"}]}}"
        }
      }
    ]
  }
}

Copy

Cortex Agentの制限事項¶

Streamlit in Snowflake (SiS) アプリは所有者の権限の下で実行されるため、 SiS アプリ内で SQL ステートメントを実行することはサポートされていません。
Azure OpenAI モデルには対応していません。

Cortex Agents REST API¶

実行エージェント¶

リクエスト¶

パスパラメーター¶

リクエストヘッダー¶

リクエスト本文¶

応答指示¶

ツール構成¶

ツール仕様¶

ツールリソース¶

ツール選択¶

メッセージ¶

メッセージの内容構成¶

完了メッセージの例¶

応答¶

message.delta イベント¶

error イベント¶

会話の流れのサンプル¶

サンプルリクエスト¶

サンプル応答¶

サンプル回答リクエスト¶

回答サンプル¶

Cortex Agentの制限事項¶

`message.delta` イベント¶

`error` イベント¶