Cortex Agents 実行 API¶

注釈

Cortex Agent REST API へのリクエストは、15分後にタイムアウトします。

Agentとやり取りするには2つの方法があります。

エージェントオブジェクトを構築し、agent:run API へのリクエストでこのエージェントオブジェクトを参照します。
エージェントオブジェクトを使用せずに直接 agent:run を呼び出します。agent:run のリクエスト本文で構成を提示します。

agent:run は デフォルトで応答のストリーミング をサポートしています。ストリーミングを無効にして単一の JSON 応答を受信するには、 stream を false に設定します。

エージェントオブジェクトによるエージェント実行リクエスト¶

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

ユーザークエリをエージェントオブジェクトに送信し、その応答を返します。

デフォルトでは、 API は応答をサーバー送信イベント（SSE）としてストリーミングします。単一の JSON 応答を受け取るには、リクエスト本文で stream を false に設定します。

注釈

このリクエストを使用して、 models 、 instructions 、 orchestration フィールドを設定、更新、上書きすることはできません。これらのフィールドを更新するには、 Cortex Agentを更新するを使用する必要があります。

パスパラメーター¶


パラメーター	説明
`database`	（必須）エージェントを含むデータベース。`/api/v2/databases` GET リクエストを使用して、利用可能なデータベースのリストを取得できます。
`schema`	（必須）エージェントを含むスキーマ。`/api/v2/databases/{database}/schemas` GET リクエストを使用して、特定のデータベースで利用可能なスキーマのリストを取得できます。
`name`	（必須）エージェントの名前。

リクエストヘッダー¶


ヘッダー	説明
`Authorization`	（必須）認証トークン:ref:`label-chat_api_authenticate_example` をご参照ください。
`Content-Type`	（必須）application/json
`Accept`	（オプション）応答のコンテンツタイプ。ストリーミング応答の場合は `text/event-stream` を使用し、単一の非ストリーミングの場合は `application/json` を使用します。

リクエスト本文¶


フィールド	型	説明
`thread_id`	整数	会話のためのスレッド ID。thread_idを使用する場合、parent_message_idも渡す必要があります。
`parent_message_id`	整数	そのスレッドの親メッセージの ID。これが最初のメッセージである場合、parent_message_idは0である必要があります。
`messages`	Message の配列	リクエストでthread_idとparent_message_idを渡す場合、messagesには会話の現在のユーザーメッセージが含まれます。そうでない場合は、messagesには会話履歴と現在のメッセージが含まれます。messagesには、ユーザークエリとアシスタントの応答の両方が時系列で含まれます。
`stream`	boolean	ストリーミング応答（`テキスト/イベントストリーム`）を返すか、非ストリーミング JSON 応答（`アプリケーション/JSON`）を返すかを指定します。trueの場合、応答はサーバー送信イベントとしてストリーミングされます。falseの場合、応答は JSON として返されます。
`tool_choice`	ToolChoice	対話中にエージェントがどのようにツールを選択し、使用するかを構成します。ツールの使用が自動か、必須か、または特定のツールを使用すべきかを制御します。

例

{
  "thread_id": 0,
  "parent_message_id": 0,
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "What is the total revenue for 2023?"
        }
      ]
    }
  ],
  "stream": false,
  "tool_choice": {
    "type": "auto",
    "name": [
      "analyst_tool",
      "search_tool"
    ]
  }
}

リクエスト本文はオプションの stream ブール値フィールドをサポートします：

stream を省略すると、デフォルト true に設定され、応答は SSE イベントとしてストリーミングされます。
stream が false の場合、 API は単一の JSON オブジェクトを返します（非ストリーミング応答（ストリーム：false）を参照）

エージェントオブジェクトなしでのエージェントの実行¶

POST /api/v2/cortex/agent:run

リクエスト本文で提供されたCortex Agentサービスにユーザークエリを送信し、その応答を返します。エージェントオブジェクトを作成せずにエージェントと対話します。

注釈

2025年9月1日より前には、agent:run API のリクエストと応答のスキーマはこのドキュメントに記載されているスキーマとは異なりました。以前は、オーケストレーションは静的であり、回答を生成するために同じシーケンスのツールが使用されていました。現在 agent:run には、リクエストと応答の両方についてスキーマが更新されています。さらに、API は動的にオーケストレーションし、最終的な応答に到達するまで反復するようになりました。エンドユーザーの体験を改善するために、このドキュメントで説明されているスキーマを使用することをお勧めします。

従来のスキーマと動作を使用するには、次のスキーマを使用します。

{
  "model": "claude-4-sonnet",
  "messages": [
     {"role":"user", "content": [] }
  ]
}

リクエストヘッダー¶


ヘッダー	説明
`Authorization`	（必須）認証トークン:ref:`label-chat_api_authenticate_example` をご参照ください。
`Content-Type`	（必須）application/json
`Accept`	（オプション）応答のコンテンツタイプ。ストリーミング応答の場合は `text/event-stream` を使用し、単一の非ストリーミングの場合は `application/json` を使用します。

リクエスト本文¶


フィールド	型	説明
`thread_id`	整数	会話のためのスレッド ID。thread_idを使用する場合、parent_message_idも渡す必要があります。
`parent_message_id`	整数	そのスレッドの親メッセージの ID。これが最初のメッセージである場合、parent_message_idは0である必要があります。
`messages`	Message の配列	リクエストでthread_idとparent_message_idを渡す場合、messagesには会話の現在のユーザーメッセージが含まれます。そうでない場合は、messagesには会話履歴と現在のメッセージが含まれます。messagesには、ユーザークエリとアシスタントの応答の両方が時系列で含まれます。
`stream`	boolean	ストリーミング応答（`テキスト/イベントストリーム`）を返すか、非ストリーミング JSON 応答（`アプリケーション/JSON`）を返すかを指定します。trueの場合、応答はサーバー送信イベントとしてストリーミングされます。falseの場合、応答は JSON として返されます。
`tool_choice`	ToolChoice	対話中にエージェントがどのようにツールを選択し、使用するかを構成します。ツールの使用が自動か、必須か、または特定のツールを使用すべきかを制御します。
`models`	ModelConfig	エージェントのモデル構成。オーケストレーションモデル（claude-4-sonnetなど）が含まれます。提示されない場合、モデルは自動的に選択されます。現在、`オーケストレーション` ステップでのみ利用可能です。
`instructions`	AgentInstructions	応答、オーケストレーション、システム、サンプルの質問など、エージェントの動作の指示。
`orchestration`	OrchestrationConfig	予算の制約（秒、トークンなど）を含むオーケストレーション構成。
`tools`	Tool の配列	エージェントが利用可能なツールのリスト。各ツールには、型、名前、説明、入力スキーマを含むtool_specが含まれています。toolsにはtool_resourcesに対応する構成がある場合があります。
`tool_resources`	ToolResource のマップ	ツール配列で参照される各ツールの構成。キーはそれぞれのツール名と一致する必要があります。

例

{
  "thread_id": 0,
  "parent_message_id": 0,
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "What is the total revenue for 2023?"
        }
      ]
    }
  ],
  "stream": false,
  "tool_choice": {
    "type": "auto",
    "name": [
      "analyst_tool",
      "search_tool"
    ]
  },
  "models": {
    "orchestration": "claude-4-sonnet"
  },
  "instructions": {
    "response": "You will respond in a friendly but concise manner",
    "orchestration": "For any query related to revenue we should use Analyst; For all policy questions we should use Search",
    "system": "You are a friendly agent ..."
  },
  "orchestration": {
    "budget": {
      "seconds": 30,
      "tokens": 16000
    }
  },
  "tools": [
    {
      "tool_spec": {
        "type": "generic",
        "name": "get_revenue",
        "description": "Fetch the delivery revenue for a location.",
        "input_schema": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "The city and state, e.g. San Francisco, CA"
            }
          }
        },
        "required": [
          "location"
        ]
      }
    }
  ],
  "tool_resources": {
    "get_revenue": {
      "type": "function",
      "execution_environment": {
        "type": "warehouse",
        "warehouse": "MY_WH"
      },
      "identifier": "DB.SCHEMA.UDF"
    }
  }
}

リクエスト本文はオプションの stream ブール値フィールドをサポートします：

stream を省略すると、デフォルト true に設定され、応答は SSE イベントとしてストリーミングされます。
stream が false の場合、 API は単一の JSON オブジェクトを返します（非ストリーミング応答（ストリーム：false）を参照）

ストリーミング応答¶

agent:run API はストリーミング応答を提供します。サーバーはイベントをストリームバックします。これにより、Agentによって生成された応答をトークンごとにアプリケーションで表示できます。API 応答でストリーミングされる各イベントには、厳密に型付けされたスキーマがあります。次のセクションにはすべてのイベントのリストがあるので、サブスクライブするイベントを選択できます。

API によって送信された最後のイベントは response イベントです。このイベントには、エージェントの出力全体が含まれます。これはエージェントの最終応答として使用できます。非ストリーミングクライアントの場合、このイベントは以前のすべてのイベントの論理的な集約であるため、このイベントにサブスクライブできます。ストリーミング応答を使用しない場合は、response イベントを待ち、それ以前のすべてのイベントは無視します。

ストリーミングされている他のイベントの大部分は、2つのカテゴリに分けられます。デルタ と コンテンツアイテム です。

デルタ イベントは、Agentによって生成された単一のトークンを表します。これらのイベントをリッスンすることで、タイプライター効果を作成できます。主なデルタイベントは、推論トークンを表す response.thinking.delta と、回答トークンを表す response.text.delta です。

コンテンツアイテム イベントは、最終的なエージェント応答の コンテンツ 配列を表します。

注釈

確実にアプリケーションが不明なイベント型を処理できるようにします。

応答例

event: response.status
data: {"message":"Planning the next steps","status":"planning"}

event: response.thinking.delta
data: {"content_index":0,"text":"\nThe user is asking for a"}

event: response.thinking.delta
data: {"content_index":0,"text":" chart showing the"}

...
...
...

event: response.status
data: {"message":"Reviewing the results","status":"reasoning_agent_stop"}

event: response.status
data: {"message":"Forming the answer","status":"proceeding_to_answer"}

`response`¶

最終的な応答が利用可能になったときにストリーミングされるイベント。これは出力された最後のイベントであり、以前にストリーミングされた他のすべてのイベントの集約を表します。


フィールド	型	説明
`role`	string	メッセージのロール。API 応答では常に `assistant`。
`content`	MessageContentItem の配列	エージェントによって生成されたコンテンツ。
`warnings`	Warning の配列	処理中に発生した致命的ではない警告。非ストリーミングクライアントまたは概要として存在します。
`metadata`	ResponseMetadata

例

{
  "role": "assistant",
  "content": [
    {
      "type": "chart",
      "chart": {
        "tool_use_id": "toolu_123",
        "chart_spec": "{\"$schema\":\"https://vega.github.io/schema/vega-lite/v5.json\",\"data\":{...},\"mark\":\"bar\"}"
      }
    }
  ],
  "warnings": [
    {
      "message": "Unable to fetch tools from MCP server 'foo'. Response quality may be degraded."
    }
  ],
  "metadata": {
    "usage": {
      "tokens_consumed": [
        {
          "model_name": "llama3.1-70b",
          "input_tokens": {
            "total": 175,
            "cache_read": 50,
            "cache_write": 25,
            "uncached": 100
          },
          "output_tokens": {
            "total": 75
          },
          "context_window": 128000
        }
      ]
    },
    "run_id": "123-456"
  }
}

`response.text`¶

テキストコンテンツブロックのストリーミングが完了したときにストリーミングされるイベントであり、特定のコンテンツインデックスのすべての集約されたデルタを含みます。


フィールド	型	説明
`content_index`	整数	このイベントが表す応答コンテンツ配列のインデックス
`text`	string	エージェントからのテキスト結果
`annotations`	Annotation の配列	テキスト結果に添付された注釈（引用など）
`is_elicitation`	boolean	このテキストコンテンツがエンドユーザーからの詳細情報を求めるエージェントであるかどうか。

例

{
  "content_index": 0,
  "text": "Lorem ipsum dolor...",
  "annotations": [
    {
      "type": "cortex_search_citation",
      "index": 0,
      "search_result_id": "cs_61987ff6-6d56-4695-83c0-1e7cfed818c7",
      "doc_id": "4ac085cb-82d0-4eb4-94f3-2672aa0599a2",
      "doc_title": "Earnings Report",
      "text": "The revenue for 2025 was..."
    }
  ],
  "is_elicitation": false
}

`response.text.delta`¶

新しい出力テキストデルタが生成されたときにストリーミングされるイベント。


フィールド	型	説明
`content_index`	整数	このイベントが表す応答コンテンツ配列のインデックス
`text`	string	テキストデルタ
`is_elicitation`	boolean	このテキストコンテンツがエンドユーザーからの詳細情報を求めるエージェントであるかどうか。

例

{
  "content_index": 0,
  "text": "Hello",
  "is_elicitation": false
}

`response.text.annotation`¶

テキストコンテンツにアノテーションが追加されたときにストリーミングされるイベント。


フィールド	型	説明
`content_index`	整数	このイベントが表す応答コンテンツ配列のインデックス
`annotation_index`	整数	この`アノテーション`が属するアノテーション配列のインデックス。
`annotation`	Annotation	追加されるアノテーションオブジェクト。

例

{
  "content_index": 0,
  "annotation_index": 0,
  "annotation": {
    "type": "cortex_search_citation",
    "index": 0,
    "search_result_id": "cs_61987ff6-6d56-4695-83c0-1e7cfed818c7",
    "doc_id": "4ac085cb-82d0-4eb4-94f3-2672aa0599a2",
    "doc_title": "Earnings Report",
    "text": "The revenue for 2025 was..."
  }
}

`response.thinking`¶

思考コンテンツブロックのストリーミングが完了したときにストリーミングされるイベントであり、特定のコンテンツインデックスのすべての集約されたデルタを含みます。


フィールド	型	説明
`content_index`	整数	このイベントが表す応答コンテンツ配列のインデックス
`text`	string	エージェントからの思考トークン
`signature`	string	思考トークンの署名

例

{
  "content_index": 0,
  "text": "To answer your question I must...",
  "signature": "lorem ipsum"
}

`response.thinking.delta`¶

思考デルタが生成されたときにストリーミングされるイベント。


フィールド	型	説明
`content_index`	整数	このイベントが表す応答コンテンツ配列のインデックス
`text`	string	思考トークン
`signature`	string	思考トークンの署名

例

{
  "content_index": 0,
  "text": "lorem ipsum",
  "signature": "lorem ipsum"
}

`response.tool_use`¶

エージェントがツールの使用をリクエストしたときにストリーミングされるイベント。


フィールド	型	説明
`content_index`	整数	このイベントが表す応答コンテンツ配列のインデックス
`tool_use_id`	string	このツールの使用に対する一意の識別子。関連ツールの結果に使用できます。
`type`	string	ツールの型（cortex_search、cortex_analyst_text_to_sqlなど）
`name`	string	このツールインスタンスの一意の識別子
`input`	object	このツールの構造化された入力。このオブジェクトのスキーマはツール仕様によって異なります。
`client_side_execute`	boolean	ツールの使用がクライアント側で実行されるかどうか。

例

{
  "content_index": 0,
  "tool_use_id": "toolu_123",
  "type": "cortex_analyst_text_to_sql",
  "name": "my_cortex_analyst_semantic_view",
  "input": {
    "location": "San Francisco, CA"
  },
  "client_side_execute": "true"
}

`response.tool_result`¶

ツールの実行が終了したときにストリーミングされるイベントで、ツールの結果も含まれます。


フィールド	型	説明
`content_index`	整数	このイベントが表す応答コンテンツ配列のインデックス
`tool_use_id`	string	このツールの使用に対する一意の識別子。関連ツールの結果に使用できます。
`type`	string	ツールの型（cortex_search、cortex_analyst_text_to_sqlなど）
`name`	string	このツールインスタンスの一意の識別子
`content`	ToolResultContent の配列	ツール結果のコンテンツ
`status`	string	ツールの実行のステータス

例

{
  "content_index": 0,
  "tool_use_id": "toolu_123",
  "type": "cortex_analyst_text_to_sql",
  "name": "my_cortex_analyst_semantic_view",
  "content": [
    {
      "type": "json",
      "json": {
        "answer": 42
      }
    }
  ],
  "status": "success"
}

`response.tool_result.status`¶

特定のツール使用のためのステータス更新。


フィールド	型	説明
`tool_use_id`	string	このツールの使用に対する一意の識別子。
`tool_type`	string	ツールの型（cortex_search、cortex_analyst_text_to_sqlなど）
`status`	string	現在の状態の列挙型。
`message`	string	現在のステータスを拡張するより説明的なメッセージ。
`details`	object	ツール固有のステータス詳細。

例

{
  "tool_use_id": "toolu_123",
  "tool_type": "cortex_analyst_text_to_sql",
  "status": "Executing SQL",
  "message": "Executing query 'SELECT * FROM my_table'",
  "details": {}
}

`response.tool_result.analyst.delta`¶

Cortex Analystツール実行用にストリーミングされたデルタイベント


フィールド	型	説明
`content_index`	整数	このイベントが表す応答コンテンツ配列のインデックス
`tool_use_id`	string	このツールの使用に対する一意の識別子。関連ツールの結果に使用できます。
`tool_type`	string	ツールの型（このイベントの場合は常にcortex_analyst_text_to_sql）
`tool_name`	string	このツールインスタンスの一意の識別子
`delta`	CortexAnalystToolResultDelta	コンテンツデルタ

例

{
  "content_index": 0,
  "tool_use_id": "toolu_123",
  "tool_type": "cortex_analyst_text_to_sql",
  "tool_name": "my_cortex_analyst_semantic_view",
  "delta": {
    "text": "The...",
    "think": "Thinking...",
    "sql": "SELECT...",
    "sql_explanation": "This...",
    "query_id": "707787a0-a684-4ead-adb0-3c3b62b043d9",
    "verified_query_used": false,
    "result_set": {
      "statementHandle": "707787a0-a684-4ead-adb0-3c3b62b043d9",
      "resultSetMetaData": {
        "partition": 0,
        "numRows": 0,
        "format": "jsonv2",
        "rowType": [
          {
            "name": "my_column",
            "type": "VARCHAR",
            "length": 0,
            "precision": 0,
            "scale": 0,
            "nullable": false
          }
        ]
      },
      "data": [
        [
          "row1 col1",
          "row1 col2"
        ],
        [
          "row2 col1",
          "row2 col2"
        ]
      ]
    },
    "suggestions": {
      "index": 0,
      "delta": "What..."
    }
  }
}

`response.table`¶

テーブルコンテンツブロックが追加されたときにストリーミングされるイベント。


フィールド	型	説明
`content_index`	整数	このイベントが表す応答コンテンツ配列のインデックス
`tool_use_id`	string	このテーブルを生成したツール使用の ID
`query_id`	string	このデータを生成したSQLクエリのクエリID
`result_set`	ResultSet	テーブルをレンダリングする SQL の結果。Snowflakeの SQL API ResultSet （https://docs.snowflake.com/en/developer-guide/sql-api/reference#resultset）のスキーマと一致します
`title`	string	このテーブルのタイトル

例

{
  "content_index": 0,
  "tool_use_id": "toolu_123",
  "query_id": "6ac75378-6337-48a6-80ab-6de48dd680eb",
  "result_set": {
    "statementHandle": "707787a0-a684-4ead-adb0-3c3b62b043d9",
    "resultSetMetaData": {
      "partition": 0,
      "numRows": 0,
      "format": "jsonv2",
      "rowType": [
        {
          "name": "my_column",
          "type": "VARCHAR",
          "length": 0,
          "precision": 0,
          "scale": 0,
          "nullable": false
        }
      ]
    },
    "data": [
      [
        "row1 col1",
        "row1 col2"
      ],
      [
        "row2 col1",
        "row2 col2"
      ]
    ]
  },
  "title": "Revenue by Month"
}

`response.chart`¶

チャートコンテンツブロックが追加されたときにストリーミングされるイベント。


フィールド	型	説明
`content_index`	整数	このイベントが表す応答コンテンツ配列のインデックス
`tool_use_id`	string	このチャートを生成したツール使用の ID
`chart_spec`	string	文字列としてシリアル化されたVega-Liteチャート仕様

例

{
  "content_index": 0,
  "tool_use_id": "toolu_123",
  "chart_spec": "{\"$schema\":\"https://vega.github.io/schema/vega-lite/v5.json\",\"data\":{...},\"mark\":\"bar\"}"
}

`response.status`¶

エージェント実行のステータス更新。


フィールド	型	説明
`status`	string	現在の状態の列挙型。
`message`	string	現在のステータスを拡張するより説明的なメッセージ。

例

{
  "status": "executing_tool",
  "message": "Executing tool `my_analyst_tool`"
}

`response.warning`¶

致命的ではない警告が発生したときに送信されます。このイベントの後、ストリームは継続します。


フィールド	型	説明
`message`	string	ユーザーに表示する警告メッセージ。

例

{
  "message": "Unable to fetch tools from MCP server 'foo'. Response quality may be degraded."
}

`error`¶

致命的なエラーが発生したときに送信されます。


フィールド	型	説明
`code`	string	Snowflakeエラーコード
`message`	string	エラーメッセージ
`request_id`	string	リクエストに対する一意の識別子。

例

{
  "code": "399504",
  "message": "Error during execution",
  "request_id": "61987ff6-6d56-4695-83c0-1e7cfed818c7"
}

`metadata`¶

リクエストに関するメタデータ。このイベントは、スレッドにメッセージが追加されたときに送信されます。Agents API に対する次のリクエストで使用する parent_message_id を取得するのに便利です。


フィールド	型	説明
`metadata`	Metadata

例

{
  "metadata": {
    "role": "user",
    "message_id": 0,
    "run_id": "123-456"
  }
}

スキーマ¶

`AgentInstructions`¶


フィールド	型	説明
`response`	string	応答生成の指示。
`orchestration`	string	これらのカスタム手順は、エージェントが使用するツールを計画するときに使用されます。
`system`	string	エージェントのシステム指示。

例

{
  "response": "You will respond in a friendly but concise manner",
  "orchestration": "For any query related to revenue we should use Analyst; For all policy questions we should use Search",
  "system": "You are a friendly agent ..."
}

`Annotation`¶

フィールド

型

説明

type

string

引用の型（常に cortex_search_citation）

index

整数

検索結果内の引用のインデックス。

search_result_id

string

検索結果の一意の識別子。

doc_id

string

ドキュメントに対する一意の識別子。

doc_title

string

ドキュメントのタイトル。

text

string

引用として使用されるドキュメントからのテキストの抜粋。

例
{
  "type": "cortex_search_citation",
  "index": 0,
  "search_result_id": "cs_61987ff6-6d56-4695-83c0-1e7cfed818c7",
  "doc_id": "4ac085cb-82d0-4eb4-94f3-2672aa0599a2",
  "doc_title": "Earnings Report",
  "text": "The revenue for 2025 was..."
}

フィールド	型	説明
`type`	string	引用の型（常に `cortex_search_citation`）
`index`	整数	検索結果内の引用のインデックス。
`search_result_id`	string	検索結果の一意の識別子。
`doc_id`	string	ドキュメントに対する一意の識別子。
`doc_title`	string	ドキュメントのタイトル。
`text`	string	引用として使用されるドキュメントからのテキストの抜粋。

`BudgetConfig`¶


フィールド	型	説明
`seconds`	整数	秒単位の時間予算。
`tokens`	整数	トークン予算。

例

{
  "seconds": 30,
  "tokens": 16000
}

`ChartContent`¶


フィールド	型	説明
`tool_use_id`	string	このチャートを生成したツール使用の ID
`chart_spec`	string	文字列としてシリアル化されたVega-Liteチャート仕様

例

{
  "tool_use_id": "toolu_123",
  "chart_spec": "{\"$schema\":\"https://vega.github.io/schema/vega-lite/v5.json\",\"data\":{...},\"mark\":\"bar\"}"
}

`CortexAnalystSuggestionDelta`¶


フィールド	型	説明
`index`	整数	このデルタが表す提案配列のインデックス
`delta`	string	このインデックスの提案のテキストデルタ

例

{
  "index": 0,
  "delta": "What..."
}

`CortexAnalystToolResultDelta`¶


フィールド	型	説明
`text`	string	Cortex Analystの最終応答からのテキストデルタ。
`think`	string	Cortex Analystの推論ステップからのテキストデルタ。
`sql`	string	Cortex Analystの SQL 出力からのデルタ。現在は、SQL クエリ全体が単一のイベントで送られますが、将来的には、トークン単位で SQL をストリーミングできます。
`sql_explanation`	string	Cortex Analystの SQL クエリが行うことの説明からのデルタ
`query_id`	string	SQL 実行開始後のクエリID
`verified_query_used`	boolean	この応答を生成するために検証済みクエリが使用されたかどうか
`result_set`	ResultSet	SQL 実行からの結果。Snowflakeの SQL API ResultSet （https://docs.snowflake.com/en/developer-guide/sql-api/reference#resultset）のスキーマと一致します
`suggestions`	CortexAnalystSuggestionDelta	Cortex Analystの提案する質問からのデルタ。これは、情報の欠落やその他の失敗により、Analystが質問に回答できない場合に送信されます。

例

{
  "text": "The...",
  "think": "Thinking...",
  "sql": "SELECT...",
  "sql_explanation": "This...",
  "query_id": "707787a0-a684-4ead-adb0-3c3b62b043d9",
  "verified_query_used": false,
  "result_set": {
    "statementHandle": "707787a0-a684-4ead-adb0-3c3b62b043d9",
    "resultSetMetaData": {
      "partition": 0,
      "numRows": 0,
      "format": "jsonv2",
      "rowType": [
        {
          "name": "my_column",
          "type": "VARCHAR",
          "length": 0,
          "precision": 0,
          "scale": 0,
          "nullable": false
        }
      ]
    },
    "data": [
      [
        "row1 col1",
        "row1 col2"
      ],
      [
        "row2 col1",
        "row2 col2"
      ]
    ]
  },
  "suggestions": {
    "index": 0,
    "delta": "What..."
  }
}

`ExecutionEnvironment`¶

サーバー実行ツールの構成。


フィールド	型	説明
`type`	string	実行環境の型。現在は `warehouse` のみがサポートされています。
`warehouse`	string	ウェアハウスの名前。大文字と小文字が区別され、引用符で囲まれていない識別子の場合は、名前をすべて大文字で指定します。
`query_timeout`	整数	クエリのタイムアウト（秒）

例

{
  "type": "warehouse",
  "warehouse": "MY_WAREHOUSE",
  "query_timeout": 60
}

`InputTokens`¶

キャッシュ使用状況による入力トークンの内訳。


フィールド	型	説明
`total`	整数	処理された入力トークンの合計（キャッシュされたトークンを含む）。
`cache_read`	整数	キャッシュから読み込まれた入力トークン。
`cache_write`	整数	キャッシュに書き込まれた入力トークン。
`uncached`	整数	キャッシュされなかった入力トークン。

例

{
  "total": 175,
  "cache_read": 50,
  "cache_write": 25,
  "uncached": 100
}

`Message`¶

会話の単一のメッセージを表します。ユーザーから、またはアシスタントからのいずれかです。


フィールド	型	説明
`role`	string	メッセージの送信者（ユーザーかアシスタントのいずれか）を識別します。通常、ユーザーメッセージにはクエリが含まれ、アシスタントメッセージには応答とツール結果が含まれます。
`content`	MessageContentItem の配列	メッセージを構成するコンテンツ要素の配列。テキスト、ツール結果、またはカスタムコンテンツの型を含めることができます。

例

{
  "role": "user",
  "content": [
    {
      "type": "text",
      "text": "What is the total revenue for 2023?"
    }
  ]
}

`MessageContentItem`¶


フィールド	型	説明
`type`	string	コンテンツの型（常に `chart`）。
`chart`	ChartContent	チャート。

例

{
  "type": "chart",
  "chart": {
    "tool_use_id": "toolu_123",
    "chart_spec": "{\"$schema\":\"https://vega.github.io/schema/vega-lite/v5.json\",\"data\":{...},\"mark\":\"bar\"}"
  }
}


フィールド	型	説明
`type`	string	コンテンツの型（常に `table`）。
`table`	TableContent	テーブル。

例

{
  "type": "table",
  "table": {
    "tool_use_id": "toolu_123",
    "query_id": "6ac75378-6337-48a6-80ab-6de48dd680eb",
    "result_set": {
      "statementHandle": "707787a0-a684-4ead-adb0-3c3b62b043d9",
      "resultSetMetaData": {
        "partition": 0,
        "numRows": 0,
        "format": "jsonv2",
        "rowType": [
          {
            "name": "my_column",
            "type": "VARCHAR",
            "length": 0,
            "precision": 0,
            "scale": 0,
            "nullable": false
          }
        ]
      },
      "data": [
        [
          "row1 col1",
          "row1 col2"
        ],
        [
          "row2 col1",
          "row2 col2"
        ]
      ]
    },
    "title": "Revenue by Month"
  }
}


フィールド	型	説明
`text`	string	エージェントからのテキスト結果
`annotations`	Annotation の配列	テキスト結果に添付された注釈（引用など）
`is_elicitation`	boolean	このテキストコンテンツがエンドユーザーからの詳細情報を求めるエージェントであるかどうか。
`type`	string	コンテンツの型（常に `text`）。

例

{
  "text": "Lorem ipsum dolor...",
  "annotations": [
    {
      "type": "cortex_search_citation",
      "index": 0,
      "search_result_id": "cs_61987ff6-6d56-4695-83c0-1e7cfed818c7",
      "doc_id": "4ac085cb-82d0-4eb4-94f3-2672aa0599a2",
      "doc_title": "Earnings Report",
      "text": "The revenue for 2025 was..."
    }
  ],
  "is_elicitation": false,
  "type": "text"
}


フィールド	型	説明
`type`	string	コンテンツの型（常に `thinking`）。
`thinking`	ThinkingContent	思考コンテンツ。

例

{
  "type": "thinking",
  "thinking": {
    "text": "To answer your question I must...",
    "signature": "lorem ipsum"
  }
}


フィールド	型	説明
`type`	string	コンテンツの型（常に `tool_result`）。
`tool_result`	ToolResult	ツールの結果。

例

{
  "type": "tool_result",
  "tool_result": {
    "tool_use_id": "toolu_123",
    "type": "cortex_analyst_text_to_sql",
    "name": "my_cortex_analyst_semantic_view",
    "content": [
      {
        "type": "json",
        "json": {
          "answer": 42
        }
      }
    ],
    "status": "success"
  }
}


フィールド	型	説明
`type`	string	コンテンツの型（常に `tool_use`）。
`tool_use`	ToolUse	ツールの使用。

例

{
  "type": "tool_use",
  "tool_use": {
    "tool_use_id": "toolu_123",
    "type": "cortex_analyst_text_to_sql",
    "name": "my_cortex_analyst_semantic_view",
    "input": {
      "location": "San Francisco, CA"
    },
    "client_side_execute": "true"
  }
}

`Metadata`¶


フィールド	型	説明
`role`	string	メッセージの送信者（ユーザーかアシスタントのいずれか）を識別します。
`message_id`	整数	スレッドメッセージID。この ID （ロールが `assistant` の場合）を使用してスレッドに関するフォローアップの質問をします。
`run_id`	string	このエージェント実行に対する一意の識別子。出力ストリームへの再接続に使用できます。

例

{
  "role": "user",
  "message_id": 0,
  "run_id": "123-456"
}

`ModelConfig`¶


フィールド	型	説明
`orchestration`	string	オーケストレーションに使用するモデル。提示されない場合、モデルは自動的に選択されます。

例

{
  "orchestration": "claude-4-sonnet"
}

`OrchestrationConfig`¶


フィールド	型	説明
`budget`	BudgetConfig	エージェントの予算の制約。複数の制約が指定されている場合は、最初のヒットでリクエストが終了します。

例

{
  "budget": {
    "seconds": 30,
    "tokens": 16000
  }
}

`OutputTokens`¶

出力トークンの詳細。


フィールド	型	説明
`total`	整数	生成された出力トークンの合計。

例

{
  "total": 75
}

`ResponseMetadata`¶

使用情報を含む、応答に関するメタデータ。


フィールド	型	説明
`usage`	UsageMetadata
`run_id`	string	このエージェント実行に対する一意の識別子。出力ストリームへの再接続に使用できます。

例

{
  "usage": {
    "tokens_consumed": [
      {
        "model_name": "llama3.1-70b",
        "input_tokens": {
          "total": 175,
          "cache_read": 50,
          "cache_write": 25,
          "uncached": 100
        },
        "output_tokens": {
          "total": 75
        },
        "context_window": 128000
      }
    ]
  },
  "run_id": "123-456"
}

`ResultSet`¶


フィールド	型	説明
`statementHandle`	string	クエリID。
`resultSetMetaData`	ResultSetMetaData	結果セットのメタデータ。
`data`	配列の配列	データを表す2D配列

例

{
  "statementHandle": "707787a0-a684-4ead-adb0-3c3b62b043d9",
  "resultSetMetaData": {
    "partition": 0,
    "numRows": 0,
    "format": "jsonv2",
    "rowType": [
      {
        "name": "my_column",
        "type": "VARCHAR",
        "length": 0,
        "precision": 0,
        "scale": 0,
        "nullable": false
      }
    ]
  },
  "data": [
    [
      "row1 col1",
      "row1 col2"
    ],
    [
      "row2 col1",
      "row2 col2"
    ]
  ]
}

`ResultSetMetaData`¶


フィールド	型	説明
`partition`	整数	パーティションのインデックス番号。
`numRows`	整数	結果の行の合計数。
`format`	string	結果セット内のデータの形式。
`rowType`	RowType の配列	結果内の列の説明。

例

{
  "partition": 0,
  "numRows": 0,
  "format": "jsonv2",
  "rowType": [
    {
      "name": "my_column",
      "type": "VARCHAR",
      "length": 0,
      "precision": 0,
      "scale": 0,
      "nullable": false
    }
  ]
}

`RowType`¶


フィールド	型	説明
`name`	string	列の名前。
`type`	string	Snowflakeの列のデータ型。（https://docs.snowflake.com/en/sql-reference/intro-summary-data-types）
`length`	整数	列の長さ。
`precision`	整数	列の精度。
`scale`	整数	列のスケール。
`nullable`	boolean	列がNULL許容かどうかを指定します。

例

{
  "name": "my_column",
  "type": "VARCHAR",
  "length": 0,
  "precision": 0,
  "scale": 0,
  "nullable": false
}

`TableContent`¶


フィールド	型	説明
`tool_use_id`	string	このテーブルを生成したツール使用の ID
`query_id`	string	このデータを生成したSQLクエリのクエリID
`result_set`	ResultSet	テーブルをレンダリングする SQL の結果。Snowflakeの SQL API ResultSet （https://docs.snowflake.com/en/developer-guide/sql-api/reference#resultset）のスキーマと一致します
`title`	string	このテーブルのタイトル

例

{
  "tool_use_id": "toolu_123",
  "query_id": "6ac75378-6337-48a6-80ab-6de48dd680eb",
  "result_set": {
    "statementHandle": "707787a0-a684-4ead-adb0-3c3b62b043d9",
    "resultSetMetaData": {
      "partition": 0,
      "numRows": 0,
      "format": "jsonv2",
      "rowType": [
        {
          "name": "my_column",
          "type": "VARCHAR",
          "length": 0,
          "precision": 0,
          "scale": 0,
          "nullable": false
        }
      ]
    },
    "data": [
      [
        "row1 col1",
        "row1 col2"
      ],
      [
        "row2 col1",
        "row2 col2"
      ]
    ]
  },
  "title": "Revenue by Month"
}

`ThinkingContent`¶


フィールド	型	説明
`text`	string	エージェントからの思考トークン
`signature`	string	思考トークンの署名

例

{
  "text": "To answer your question I must...",
  "signature": "lorem ipsum"
}

`TokensConsumed`¶

特定のモデルのトークン消費。


フィールド	型	説明
`model_name`	string	使用されたモデルの名前。
`input_tokens`	InputTokens
`output_tokens`	OutputTokens
`context_window`	整数	モデルのコンテキストウィンドウサイズ（トークン単位）。

例

{
  "model_name": "llama3.1-70b",
  "input_tokens": {
    "total": 175,
    "cache_read": 50,
    "cache_write": 25,
    "uncached": 100
  },
  "output_tokens": {
    "total": 75
  },
  "context_window": 128000
}

`Tool`¶

エージェントが使用できるツールを定義します。ツールは、データ分析、検索、または汎用関数などの特定の機能を提供します。


フィールド	型	説明
`tool_spec`	ToolSpec	ツールの型、構成、および入力要件の仕様。

例

{
  "tool_spec": {
    "type": "generic",
    "name": "get_revenue",
    "description": "Fetch the delivery revenue for a location.",
    "input_schema": {
      "type": "object",
      "properties": {
        "location": {
          "type": "string",
          "description": "The city and state, e.g. San Francisco, CA"
        }
      }
    },
    "required": [
      "location"
    ]
  }
}

`ToolChoice`¶


フィールド	型	説明
`type`	string	ツールの選択方法を定義します。autoは自動ツール選択（デフォルト）で、requiredは1つ以上のツールを使用する必要があり、toolは特定の名前のツールを使用します。
`name`	文字列の配列。	型が「tool」の場合に使用する特定のツール名のリスト。

例

{
  "type": "auto",
  "name": [
    "analyst_tool",
    "search_tool"
  ]
}

`ToolInputSchema`¶


フィールド	型	説明
`type`	string	入力スキーマオブジェクトのタイプ。
`description`	string	入力が何かの説明。
`properties`	ToolInputSchema のマップ	型が `object` の場合、各入力パラメーターの定義。
`items`	ToolInputSchema	型が `array` の場合、配列の要素のスキーマ。
`required`	文字列の配列。	型が `object` の場合、必要な入力パラメーター名のリスト。

例

{
  "type": "object",
  "description": "Input for my custom tool",
  "properties": {
    "location": {
      "type": "string",
      "description": "The city and state, e.g. San Francisco, CA"
    }
  },
  "items": {},
  "required": [
    "location"
  ]
}

`ToolResource`¶

テキストから SQL への分析ツールの構成。SQL クエリの生成と実行用のパラメーターを提供します。semantic_model_fileまたはsemantic_viewのいずれかを正確に提供する必要があります。

フィールド

型

説明

semantic_model_file

string

セマンティックモデルyamlを保持するSnowflakeステージに格納されているファイルへのパス。

semantic_view

string

Snowflakeネイティブセマンティックモデルオブジェクトの名前。

execution_environment

ExecutionEnvironment

生成された SQL クエリの実行方法の構成。

例
{
  "semantic_model_file": "@db.schema.stage/semantic_model.yaml",
  "semantic_view": "db.schema.semantic_view",
  "execution_environment": {
    "type": "warehouse",
    "warehouse": "MY_WAREHOUSE",
    "query_timeout": 60
  }
}
検索機能の構成。ドキュメントの検索と取得を実行する方法を定義します。

フィールド

型

説明

search_service

string

検索サービスの完全修飾名。

title_column

string

ドキュメントのタイトル列。

id_column

string

ドキュメントの ID 列。

filter

object

検索結果のクエリをフィルターします。

例
{
  "search_service": "database.schema.service_name",
  "title_column": "account_name",
  "id_column": "account_id",
  "filter": {
    "@eq": {
      "<column>": "<value>"
    }
  }
}
フィールド

型

説明

type

string

ツールがサーバー側で実行される場合、ストアドプロシージャか UDF のどちらであるか。

execution_environment

ExecutionEnvironment

identifier

string

ストアドプロシージャまたは UDF の完全修飾名。

例
{
  "type": "function",
  "execution_environment": {
    "type": "warehouse",
    "warehouse": "MY_WAREHOUSE",
    "query_timeout": 60
  },
  "identifier": "MY_DB.MY_SCHEMA.MY_UDF"
}
ウェブ検索機能の構成。

フィールド

型

説明

max_results

整数

返されるウェブ検索結果の最大数。

例
{
  "max_results": 20
}

`ToolResult`¶


フィールド	型	説明
`tool_use_id`	string	このツールの使用に対する一意の識別子。関連ツールの結果に使用できます。
`type`	string	ツールの型（cortex_search、cortex_analyst_text_to_sqlなど）
`name`	string	このツールインスタンスの一意の識別子
`content`	ToolResultContent の配列	ツール結果のコンテンツ
`status`	string	ツールの実行のステータス

例

{
  "tool_use_id": "toolu_123",
  "type": "cortex_analyst_text_to_sql",
  "name": "my_cortex_analyst_semantic_view",
  "content": [
    {
      "type": "json",
      "json": {
        "answer": 42
      }
    }
  ],
  "status": "success"
}

`ToolResultContent`¶

フィールド

型

説明

type

string

結果の型（常に json）

json

object

ツールからの構造化出力。スキーマはツールの型によって異なります。

例
{
  "type": "json",
  "json": {
    "answer": 42
  }
}
フィールド

型

説明

type

string

結果の型（常に text）

text

string

結果テキスト

例
{
  "type": "text",
  "text": "The answer is 42"
}

`ToolSpec`¶

ツールの型、構成、および入力要件の仕様。


フィールド	型	説明
`type`	string	ツール機能の型。「cortex_analyst_text_to_sql」のような特殊型や汎用ツール向けの「generic」など。
`name`	string	このツールインスタンスを参照するための一意の識別子。tool_resourcesの構成と照合するために使用されます。
`description`	string	ツールの使用を考慮するツールの説明。
`input_schema`	ToolInputSchema	このツールに対して想定される入力パラメーターの JSON スキーマ定義。エージェントにはこれが与えられることで、ToolUses の入力を生成する際に従うべき構造を知ることができます。汎用ツールが入力パラメーターを指定するために必要です。

例

{
  "type": "generic",
  "name": "get_weather",
  "description": "lorem ipsum",
  "input_schema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "The city and state, e.g. San Francisco, CA"
      }
    },
    "required": [
      "location"
    ]
  }
}

`ToolUse`¶


フィールド	型	説明
`tool_use_id`	string	このツールの使用に対する一意の識別子。関連ツールの結果に使用できます。
`type`	string	ツールの型（cortex_search、cortex_analyst_text_to_sqlなど）
`name`	string	このツールインスタンスの一意の識別子
`input`	object	このツールの構造化された入力。このオブジェクトのスキーマはツール仕様によって異なります。
`client_side_execute`	boolean	ツールの使用がクライアント側で実行されるかどうか。

例

{
  "tool_use_id": "toolu_123",
  "type": "cortex_analyst_text_to_sql",
  "name": "my_cortex_analyst_semantic_view",
  "input": {
    "location": "San Francisco, CA"
  },
  "client_side_execute": "true"
}

`UsageMetadata`¶

このリクエストのトークン使用情報。


フィールド	型	説明
`tokens_consumed`	TokensConsumed の配列	このリクエストで使用されたモデルごとのトークン消費に関する詳細。

例

{
  "tokens_consumed": [
    {
      "model_name": "llama3.1-70b",
      "input_tokens": {
        "total": 175,
        "cache_read": 50,
        "cache_write": 25,
        "uncached": 100
      },
      "output_tokens": {
        "total": 75
      },
      "context_window": 128000
    }
  ]
}

`Warning`¶


フィールド	型	説明
`message`	string	ユーザーに表示する警告メッセージ。

例

{
  "message": "Unable to fetch tools from MCP server 'foo'. Response quality may be degraded."
}

非ストリーミング応答（ストリーム：false）¶

単一の非ストリーミング JSON 応答 を受け取るには、リクエスト本文の stream を false に設定し、リクエスト Accept ヘッダーを application/json に設定します。

応答本文はストリーミングモードの response イベントペイロードと同じオブジェクトです（つまり SSE:code:response イベントの data フィールドに返される JSON に対応します）

応答例

{
  "role": "assistant",
  "content": [
    {
      "thinking": {
        "text": "\nThe user is asking about types of products...\n"
      },
      "type": "thinking"
    },
    {
      "tool_use": {
        "client_side_execute": false,
        "input": {
          "has_time_column": false,
          "need_future_forecasting_data": false,
          "original_query": "what are some types of products?",
          "previous_related_tool_result_id": "",
          "query": "What are the different types or categories of products?"
        },
        "name": "semantic_view_a",
        "tool_use_id": "<tool_use_id>",
        "type": "cortex_analyst_text_to_sql"
      },
      "type": "tool_use"
    },
    {
      "tool_result": {
        "content": [
          {
            "json": {
              "query_id": "<query_id>",
              "result_set": {
                "data": [
                  ["Electronics", "3", "3"],
                  ["Furniture", "2", "2"]
                ],
                "resultSetMetaData": {
                  "format": "jsonv2",
                  "numRows": 2,
                  "partition": 0
                },
                "statementHandle": "<statement_handle>"
              },
              "sql": "WITH __table_a AS (...) SELECT ...",
              "text": "The question is clear and I can answer it with the following SQL."
            },
            "type": "json"
          }
        ],
        "name": "semantic_view_a",
        "status": "success",
        "tool_use_id": "<tool_use_id>",
        "type": "cortex_analyst_text_to_sql"
      },
      "type": "tool_result"
    },
    {
      "text": "Based on the data available, there are 2 main types of products...",
      "type": "text"
    }
  ]
}

フィールド	型	説明
`semantic_model_file`	string	セマンティックモデルyamlを保持するSnowflakeステージに格納されているファイルへのパス。
`semantic_view`	string	Snowflakeネイティブセマンティックモデルオブジェクトの名前。
`execution_environment`	ExecutionEnvironment	生成された SQL クエリの実行方法の構成。

フィールド	型	説明
`search_service`	string	検索サービスの完全修飾名。
`title_column`	string	ドキュメントのタイトル列。
`id_column`	string	ドキュメントの ID 列。
`filter`	object	検索結果のクエリをフィルターします。

フィールド	型	説明
`type`	string	ツールがサーバー側で実行される場合、ストアドプロシージャか UDF のどちらであるか。
`execution_environment`	ExecutionEnvironment
`identifier`	string	ストアドプロシージャまたは UDF の完全修飾名。

フィールド	型	説明
`type`	string	結果の型（常に `json`）
`json`	object	ツールからの構造化出力。スキーマはツールの型によって異なります。

フィールド	型	説明
`type`	string	結果の型（常に `text`）
`text`	string	結果テキスト

Cortex Agents 実行 API¶

エージェントオブジェクトによるエージェント実行リクエスト¶

パスパラメーター¶

リクエストヘッダー¶

リクエスト本文¶

エージェントオブジェクトなしでのエージェントの実行¶

リクエストヘッダー¶

リクエスト本文¶

ストリーミング応答¶

response¶

response.text¶

response.text.delta¶

response.text.annotation¶

response.thinking¶

response.thinking.delta¶

response.tool_use¶

response.tool_result¶

response.tool_result.status¶

response.tool_result.analyst.delta¶

response.table¶

response.chart¶

response.status¶

response.warning¶

error¶

metadata¶

スキーマ¶

AgentInstructions¶

Annotation¶

BudgetConfig¶

ChartContent¶

CortexAnalystSuggestionDelta¶

CortexAnalystToolResultDelta¶

ExecutionEnvironment¶

InputTokens¶

Message¶

MessageContentItem¶

Metadata¶

ModelConfig¶

OrchestrationConfig¶

OutputTokens¶

ResponseMetadata¶

ResultSet¶

ResultSetMetaData¶

RowType¶

TableContent¶

ThinkingContent¶

TokensConsumed¶

Tool¶

ToolChoice¶

ToolInputSchema¶

ToolResource¶

ToolResult¶

ToolResultContent¶

ToolSpec¶

ToolUse¶

UsageMetadata¶

Warning¶

非ストリーミング応答（ストリーム：false）¶

`response`¶

`response.text`¶

`response.text.delta`¶

`response.text.annotation`¶

`response.thinking`¶

`response.thinking.delta`¶

`response.tool_use`¶

`response.tool_result`¶

`response.tool_result.status`¶

`response.tool_result.analyst.delta`¶

`response.table`¶

`response.chart`¶

`response.status`¶

`response.warning`¶

`error`¶

`metadata`¶

`AgentInstructions`¶

`Annotation`¶

`BudgetConfig`¶

`ChartContent`¶

`CortexAnalystSuggestionDelta`¶

`CortexAnalystToolResultDelta`¶

`ExecutionEnvironment`¶

`InputTokens`¶

`Message`¶

`MessageContentItem`¶

`Metadata`¶

`ModelConfig`¶

`OrchestrationConfig`¶

`OutputTokens`¶

`ResponseMetadata`¶

`ResultSet`¶

`ResultSetMetaData`¶

`RowType`¶

`TableContent`¶

`ThinkingContent`¶

`TokensConsumed`¶

`Tool`¶

`ToolChoice`¶

`ToolInputSchema`¶

`ToolResource`¶

`ToolResult`¶

`ToolResultContent`¶

`ToolSpec`¶

`ToolUse`¶

`UsageMetadata`¶

`Warning`¶