Cortex Agents REST API¶

Cortex Agent REST API を使用すると、SnowflakeアカウントでCortex Agentオブジェクトを作成、管理、操作できます。

Cortex Agentを作成する¶

POST /api/v2/databases/{database}/schemas/{schema}/agents

指定された属性と仕様で新しい Cortex Agentオブジェクトを作成します。

リクエスト¶

パスパラメーター¶

パラメーター	説明
`database`	（必須）Snowflakeアカウント URL。
`schema`	（必須）スキーマ識別子。

クエリパラメーター¶

パラメーター	説明
`createMode`	（オプション）リソース作成モード。有効な値: `errorIfExists` `orReplace` `ifNotExists`

パラメーター

説明

createMode

（オプション）リソース作成モード。有効な値:

errorIfExists

orReplace

ifNotExists

リクエストヘッダー¶

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

リクエスト本文¶

フィールド	型	説明
`name`	string	エージェントの名前。
`comment`	string	エージェントに関する任意のコメント。
`profile`	AgentProfile	エージェントプロファイル情報（表示名、アバター、色など）。
`models`	ModelConfig	エージェントのモデル構成。オーケストレーションモデル（claude-4-sonnetなど）が含まれます。提示されない場合、モデルは自動的に選択されます。現在、`オーケストレーション` ステップでのみ利用可能です。
`instructions`	AgentInstructions	応答、オーケストレーション、システム、サンプルの質問など、エージェントの動作の指示。
`orchestration`	OrchestrationConfig	予算の制約（秒、トークンなど）を含むオーケストレーション構成。
`tools`	Tool の配列	エージェントが利用可能なツールのリスト。各ツールには、型、名前、説明、入力スキーマを含むtool_specが含まれています。toolsにはtool_resourcesに対応する構成がある場合があります。
`tool_resources`	ToolResource のマップ	ツール配列で参照される各ツールの構成。キーはそれぞれのツール名と一致する必要があります。

例

{
  "name": "MY_AGENT",
  "comment": "An agent to answer questions about all my data",
  "profile": {
    "display_name": "My Agent"
  },
  "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"
    }
  }
}

Copy

応答¶

正常な応答では、Cortex Agentの作成ステータスに関する詳細を含む JSON オブジェクトを返します。

応答本文¶

{"status": "Agent xxxx successfully created."}

Copy

Cortex Agentを説明する¶

GET /api/v2/databases/{database}/schemas/{schema}/agents/{name}

Cortex Agentを説明します。

リクエスト¶

パスパラメーター¶

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

リクエストヘッダー¶

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

応答¶

正常な応答では、Cortex Agentを説明する JSON オブジェクトを返します。

応答のヘッダ¶

ヘッダー	説明
`X-Snowflake-Request-ID`	API リクエストの一意の ID。
`Link`	結果のページへのリンク（最初のページ、最後のページなど）。ヘッダには、返すページを指定する異なるrel属性値（first、next、prev、last）を持つ複数のurlエントリを含めることができます。

応答本文¶

応答本文には、Cortex Agentの詳細が含まれています。

{
  "agent_spec": "{\"models\":{\"orchestration\":\"llama3.1-70B\"},\"experimental\":{\"foo\":\"bar\",\"nested\":{\"key\":\"value\"}},\"orchestration\":{\"budget\":{\"seconds\":30,\"tokens\":16000}},\"instructions\":{\"response\":\"You will respond in a friendly but concise manner\",\"orchestration\":\"For any revenue question use Analyst; for policy use Search\",\"system\":\"You are a friendly agent.\",\"sample_questions\":[{\"question\":\"question 1\"},{\"question\":\"question 2\"},{\"question\":\"question 3\"}]},\"tools\":[{\"tool_spec\":{\"type\":\"cortex_analyst_text_to_sql\",\"name\":\"Analyst1\",\"description\":\"test\"}},{\"tool_spec\":{\"type\":\"cortex_analyst_sql_exec\",\"name\":\"SQL_exec1\"}},{\"tool_spec\":{\"type\":\"cortex_search\",\"name\":\"Search1\"}},{\"tool_spec\":{\"type\":\"web_search\",\"name\":\"web_search_1\"}},{\"tool_spec\":{\"type\":\"generic\",\"name\":\"get_weather\",\"input_schema\":{\"type\":\"object\",\"properties\":{\"location\":{\"type\":\"string\",\"description\":\"The city and state\"}},\"required\":[\"Location\"]}}}],\"tool_unable_to_answer\":\"I don't know the answer to that\",\"tool_resources\":{\"Analyst1\":{\"semantic_model_file\":\"stage1\"},\"Analyst2\":{\"semantic_view\":\"db.schema.semantic_view\"},\"Search1\":{\"name\":\"db.schema.service_name\",\"Max_results\":\"5\",\"filter\":{\"@eq\":{\"region\":\"North America\"}},\"Title_column\":\"<title_name>\",\"ID_column\":\"<column_name>\"},\"SQL_exec1\":{\"Name\":\"my_warehouse\",\"Timeout\":\"30\",\"AutoExecute\":\"true\"},\"web_search\":{\"name\":\"web_search_1\",\"Function\":\"db/schema/search_web\"}}}",
  "name": "MY_AGENT1",
  "database_name": "TEST_DATABASE",
  "schema_name": "TEST_SCHEMA",
  "owner": "ACCOUNTADMIN",
  "created_on": "1967-06-23T07:00:00.123+00:00"
}

Copy

Cortex Agentを更新する¶

PUT /api/v2/databases/{database}/schemas/{schema}/agents/{name}

指定された属性と仕様で既存のCortex Agentを更新します。

リクエスト¶

パスパラメーター¶

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

リクエストヘッダー¶

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

リクエスト本文¶

フィールド	型	説明
`comment`	string	エージェントに関する任意のコメント。
`profile`	AgentProfile	エージェントプロファイル情報（表示名、アバター、色など）。
`models`	ModelConfig	エージェントのモデル構成。オーケストレーションモデル（claude-4-sonnetなど）が含まれます。提示されない場合、モデルは自動的に選択されます。現在、`オーケストレーション` ステップでのみ利用可能です。
`instructions`	AgentInstructions	応答、オーケストレーション、システム、サンプルの質問など、エージェントの動作の指示。
`orchestration`	OrchestrationConfig	予算の制約（秒、トークンなど）を含むオーケストレーション構成。
`tools`	Tool の配列	エージェントが利用可能なツールのリスト。各ツールには、型、名前、説明、入力スキーマを含むtool_specが含まれています。toolsにはtool_resourcesに対応する構成がある場合があります。
`tool_resources`	ToolResource のマップ	ツール配列で参照される各ツールの構成。キーはそれぞれのツール名と一致する必要があります。

例

{
  "comment": "An agent to answer questions about all my data",
  "profile": {
    "display_name": "My Agent"
  },
  "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"
    }
  }
}

Copy

応答¶

正常な応答では、Cortex Agentの更新ステータスに関する詳細を含む JSON オブジェクトを返します。

応答本文¶

{"status": "Agent xxxx successfully updated."}

Copy

Cortex Agentをリストする¶

GET /api/v2/databases/{database}/schemas/{schema}/agents

指定したデータベースとスキーマの下にあるCortex Agentをリストします。

リクエスト¶

パスパラメーター¶

パラメーター	説明
`database`	（必須）リソースが属するデータベースの識別子。/api/v2/databases GET リクエストを使用して、利用可能なデータベースのリストを取得できます。
`schema`	（必須）リソースが属するスキーマの識別子。/api/v2/databases/{database}/schemas GET リクエストを使用して、特定のデータベースで利用可能なスキーマのリストを取得できます。

クエリパラメーター¶

パラメーター	説明
`like`	（オプション）リソース名で出力をフィルタリングします。SQL ワイルドカード文字をサポートする、大文字と小文字を区別しないパターンマッチングを使用します。
`fromName`	（オプション）オブジェクト名が指定された文字列と一致する最初の行に続く行のみを取得できます。大文字と小文字が区別されます。完全な名前である必要はありません。
`showLimit`	（オプション）コマンドによって返される行の最大数を制限します。最小：1.最大：10000.

リクエストヘッダー¶

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

応答¶

正常な応答では、Cortex Agentリソースの JSON 配列を返します。

応答のヘッダ¶

ヘッダー	説明
`X-Snowflake-Request-ID`	API リクエストの一意の ID。
`Link`	結果のページへのリンク（最初のページ、最後のページなど）。ヘッダには、返すページを指定する異なるrel属性値（first、next、prev、last）を持つ複数のurlエントリを含めることができます。

応答本文¶

[
 {
  "name": "my_agent",
  "database": "TEST_DB",
  "schema": "TEST_SCHEMA",
  "created_on": "2024-06-01T12:00:00Z",
  "owner": "ACCOUNTADMIN",
  "comment": "Sample agent"
 },
 {
  "name": "another_agent",
  "database": "TEST_DB",
  "schema": "TEST_SCHEMA",
  "created_on": "2024-06-02T08:30:00Z",
  "owner": "SYSADMIN",
  "comment": ""
 }
]

Copy

Cortex Agentを削除する¶

DELETE /api/v2/databases/{database}/schemas/{schema}/agents/{name}

指定された名前のCortex Agentを削除します。ifExists パラメーターが true に設定されている場合、エージェントが存在しなくても操作は成功します。それ以外の場合は、エージェントを削除できないと操作は失敗します。

リクエスト¶

パスパラメーター¶

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

クエリパラメーター¶

パラメーター	説明
`ifExists`	（オプション）エージェントが存在しない場合にリクエストを処理する方法を指定します。 `true`:エージェントが存在しない場合、エンドポイントはエラーをスローしません。200（成功応答）を返しますが、アクションは実行しません。 `false`:エージェントが存在しない場合、エンドポイントはエラーをスローします。

パラメーター

説明

ifExists

（オプション）エージェントが存在しない場合にリクエストを処理する方法を指定します。

true:エージェントが存在しない場合、エンドポイントはエラーをスローしません。200（成功応答）を返しますが、アクションは実行しません。
false:エージェントが存在しない場合、エンドポイントはエラーをスローします。

リクエストヘッダー¶

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

応答¶

正常な応答では、確認メッセージを返します。

応答本文¶

{
 "status": "Request successfully completed"
}

Copy

スキーマ¶

`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 ..."
}

Copy

`AgentProfile`¶

Data Cortexエージェントのプロファイル情報。

フィールド	型	説明
`display_name`	string	エージェントの表示名。

例

{
  "display_name": "My Agent"
}

Copy

`BudgetConfig`¶

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

例

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

Copy

`ExecutionEnvironment`¶

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

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

例

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

Copy

`ModelConfig`¶

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

例

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

Copy

`OrchestrationConfig`¶

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

例

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

Copy

`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"
    ]
  }
}

Copy

`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"
  ]
}

Copy

`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
  }
}
Copy
検索機能の構成。ドキュメントの検索と取得を実行する方法を定義します。

フィールド

型

説明

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>"
    }
  }
}
Copy
フィールド

型

説明

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"
}
Copy

フィールド	型	説明
`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 の完全修飾名。

`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"
    ]
  }
}

Copy

Cortex Agents REST API¶

Cortex Agentを作成する¶

リクエスト¶

パスパラメーター¶

クエリパラメーター¶

リクエストヘッダー¶

リクエスト本文¶

応答¶

応答本文¶

Cortex Agentを説明する¶

リクエスト¶

パスパラメーター¶

リクエストヘッダー¶

応答¶

応答のヘッダ¶

応答本文¶

Cortex Agentを更新する¶

リクエスト¶

パスパラメーター¶

リクエストヘッダー¶

リクエスト本文¶

応答¶

応答本文¶

Cortex Agentをリストする¶

リクエスト¶

パスパラメーター¶

クエリパラメーター¶

リクエストヘッダー¶

応答¶

応答のヘッダ¶

応答本文¶

Cortex Agentを削除する¶

リクエスト¶

パスパラメーター¶

クエリパラメーター¶

リクエストヘッダー¶

応答¶

応答本文¶

スキーマ¶

AgentInstructions¶

AgentProfile¶

BudgetConfig¶

ExecutionEnvironment¶

ModelConfig¶

OrchestrationConfig¶

Tool¶

ToolInputSchema¶

ToolResource¶

ToolSpec¶

`AgentInstructions`¶

`AgentProfile`¶

`BudgetConfig`¶

`ExecutionEnvironment`¶

`ModelConfig`¶

`OrchestrationConfig`¶

`Tool`¶

`ToolInputSchema`¶

`ToolResource`¶

`ToolSpec`¶